مقدّمة عن استدعاء الدوال باستخدام Gemini API

باستخدام ميزة استدعاء الدوال في Gemini API، يمكنك توفير وظائف مخصّصة تعريفات للنموذج. لا يستدعي النموذج هذه الدوال بشكل مباشر، ولكنه بدلاً من ذلك، يتم إنشاء إخراج منظم يحدد اسم دالة الوسيطة. يمكنك بعد ذلك استخدام اسم الدالة والمَعلمات لاستدعاء واجهة برمجة تطبيقات خارجية، ويمكنك دمج نتيجة واجهة برمجة التطبيقات في طلب بحث آخر موجَّه إلى النموذج، ما يتيح للنموذج تقديم استجابة أكثر شمولاً واتّخاذ إجراءات إضافية.

تتيح طلبات الدالة للمستخدمين التفاعل مع المعلومات وخدمات في الوقت الفعلي، مثل قواعد البيانات وأنظمة إدارة علاقات العملاء ومستودعات المستندات. تعمل هذه الميزة أيضًا على تحسين قدرة النموذج على تقديم معلومات ذات صلة وإجابات سياقية. يُعد استدعاء الدوال هو الأفضل للتفاعل مع البيانات والأنظمة المختلفة. إذا كان نموذج الاستخدام يتطلّب من النموذج إجراء عمليات حسابية ولكنّه لا يضمّن أنظمة أو واجهات برمجة تطبيقات خارجية، ننصحك باستخدام تنفيذ الرموز البرمجية بدلاً من ذلك.

للحصول على مثال عملي لاستدعاء الدوال، راجع "برنامج تتبُّع الضوء" دفتر ملاحظات.

آلية عمل استدعاء الدوالّ

يمكنك استخدام ميزة استدعاء الدوالّ من خلال إضافة بيانات طلب بحث منظَّمة تصف واجهات البرمجة، والتي تُعرف باسم بيانات تعريف الدوالّ، إلى طلب نموذجي. تشير رسالة الأشكال البيانية توفر بيانات الدوال اسم دالة واجهة برمجة التطبيقات وتشرح الغرض منها وأي معلمات تدعمها وأوصاف تلك المعلمات. بعد اجتياز التقييم قائمة بتعريفات الدوال في استعلام إلى النموذج، ويحلل الدالة وباقي الاستعلامات لتحديد كيفية استخدام البيانات واجهة برمجة التطبيقات استجابةً للطلب.

بعد ذلك، يعرض النموذج عنصرًا في مخطّط متوافق مع OpenAPI يحدّد كيفية طلب دالة واحدة أو أكثر من الدوال المُعلَن عنها للردّ على سؤال المستخدم. يمكنك بعد ذلك استخدام مَعلمات طلب الدالة المقترَحة، وطلب البيانات من واجهة برمجة التطبيقات الفعلية، والحصول على ردّ، وتقديم هذا الردّ إلى العميل أو اتّخاذ إجراء آخر. يُرجى العِلم أنّ النموذج لا يستدعي في الواقع الدوال المُعلَن عنها. وبدلاً من ذلك، يمكنك استخدام معلمات كائن المخطط الذي تم إرجاعه لاستدعاء الدالة. تتيح أيضًا واجهة برمجة التطبيقات Gemini API طلب الدوال الموازية، حيث يكون يقترح النموذج طلبات متعددة لدوال واجهة برمجة التطبيقات بناءً على طلب واحد.

إعلانات الدوال

عند تنفيذ استدعاء الدوال في الطلب، تنشئ كائن tools، الذي يحتوي على علامة function declarations واحدة أو أكثر أنت تحدد الدوال باستخدام JSON، خاصةً مع اختيار مجموعة فرعية من مخطّط OpenAPI . يمكن أن يتضمّن بيان دالة واحد المَعلمات التالية:

  • ‫name (سلسلة): المعرّف الفريد للدالة ضمن طلب اتّصال واجهة برمجة التطبيقات
  • ‫description (سلسلة): شرح شامل لهدف الدالة وإمكاناتها
  • parameters (كائن): يحدِّد بيانات الإدخال المطلوبة من الدالة.
    • type (سلسلة): تحدّد نوع البيانات العام، مثل object.
    • ‫properties (عنصر): يسرد المَعلمات الفردية، وكل منها يتضمّن ما يلي:
      • type (سلسلة): نوع بيانات المَعلمة، مثل string، integer، boolean.
      • description (سلسلة): شرح واضح للمَعلمة والغرض والتنسيق المتوقع.
    • ‫required (مصفوفة): مصفوفة من السلاسل التي تسرد أسماء المَعلمات التي تكون مطلوبة لكي تعمل الدالة.

للحصول على أمثلة على الرموز البرمجية لتعريف دالة باستخدام أوامر cURL، اطّلِع على أمثلة على استدعاء الدوالّ. للحصول على أمثلة على إنشاء بيانات الدوال باستخدام حِزم تطوير البرامج (SDK) لواجهة Gemini API، يمكنك الاطّلاع على دليل تعليمي حول استدعاء الدوال

أفضل الممارسات المتعلّقة بتعريف الدوالّ

من الضروري تحديد وظائفك بدقة عند دمجها في طلباتك. تعتمد كل دالة على مَعلمات محدّدة توجّه سلوكها وتفاعلها مع النموذج. تقدّم القائمة التالية إرشادات حول تحديد مَعلمات دالة فردية في صفيف functions_declarations .

  • name: استخدِم أسماء واضحة ووصفية بدون مسافات أو فواصل (.) أو أحرف شرطة (-). بدلاً من ذلك، استخدِم أحرفًا تحتية (_) أو كتابة الكلمات بأسلوب الجمل اللاتينية.

  • description: قدِّم وصفًا تفصيليًا وواضحًا ومحدّدًا للدوالّ، مع تقديم أمثلة عند الضرورة. على سبيل المثال، بدلاً من find theaters، استخدِم find theaters based on location and optionally movie title that is currently playing in theaters.. تجنَّب استخدام وصف فضفاض أو غامض.

  • properties > type: استخدِم مَعلمات ذات أنواع محدّدة لتقليل الأخطاء الناتجة عن النموذج. على سبيل المثال، إذا كانت قيم المعلمات من نطاق محدود يُرجى استخدام الحقل enum بدلاً من إدراج القيم في الوصف (مثال: "type": "enum", "values": ["now_playing", "upcoming"]). إذا كانت قيمة المعلمة هي دائمًا عدد صحيح، اضبط النوع على integer بدلاً من number

  • properties description: قدِّم قيودًا وأمثلة ملموسة. على سبيل المثال، استخدِم The city and state, e.g. San Francisco, CA or a zip code e.g. 95616 بدلاً من the location to search.

لمزيد من أفضل الممارسات عند استخدام استدعاء الدوالّ، راجِع القسم أفضل الممارسات.

وضع استدعاء الدالة

يمكنك استخدام الدالة التي تستدعي مَعلمة mode لتعديل عملية التنفيذ. سلوك الميزة. تتوفّر ثلاثة أوضاع:

  • AUTO: سلوك النموذج التلقائي يقرر النموذج التنبؤ إما استدعاء الدالة أو استجابة لغة طبيعية.
  • ANY: يتم تقييد النموذج لتوقّع استدعاء دالة في كلّ الأوقات. في حال حذف لا يتم توفير allowed_function_names، يختار النموذج من بين جميع إعلانات الدوال المتوفرة. في حال توفّر allowed_function_names، يختار النموذج دالة من مجموعة الدوال المسموح بها.
  • NONE: لن يتوقّع النموذج استدعاء دالة. في هذه الحالة، يمثّل النموذج هو نفس الشيء كما لو لم يتم تمرير أي تعريفات دالة.

يمكن استخدام وضع ANY ("استدعاء الدالة القسري") في طُرز Gemini 1.5 Pro وGemini 1.5 Flash فقط.

يمكنك أيضًا ضبط مجموعة من allowed_function_names، وتفرض حدود عليها عند توفيرها. الدوال التي سيسميها النموذج. يجب عدم تضمين allowed_function_names إلا عندما يكون الوضع ANY. يجب أن تتطابق أسماء الدوال. بأسماء تعريف الدوال. عند ضبط الوضع على ANY ومجموعة allowed_function_names، سيتنبأ النموذج باستدعاء دالة من مجموعة أسماء الدوال المقدَّمة.

يوضّح مقتطف الرمز البرمجي التالي من مثال على طلب كيفية ضبط mode على ANY وتحديد قائمة بالدوال المسموح بها:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

أمثلة على استدعاء الدوال

يقدّم هذا القسم أمثلة على طلبات استدعاء الدوالّ باستخدام أوامر cURL. تتضمن الأمثلة سيناريوهات منعطف واحد ودورات متعددة وتمكين أوضاع استدعاء الدوال المختلفة.

عند استخدام أوامر cURL مع هذه الميزة، يتم تضمين معلومات الدالة والمَعلمة في العنصر tools. كل تصريح دالة في يحتوي العنصر tools على اسم الدالة، ويمكنك تحديد المعلمات باستخدام مخطط متوافق مع OpenAPI، ووصف الدالة.

مثال على جولة واحدة

ويتم تسجيل الدوران مرة واحدة عند استدعاء النموذج اللغوي مرة واحدة. باستخدام استدعاء الدالة، يمكن أن تكون حالة الاستخدام في منعطف واحد عند توفير لغة طبيعية للنموذج استعلام وقائمة من الدوال. في هذه الحالة، يستخدم النموذج بيان الدالة، الذي يتضمّن اسم الدالة والمَعلمات والوصف، لمحاولة توقّع الدالة التي سيتمّ استدعاؤها والوسيطات التي سيتمّ استدعاؤها بها.

نموذج الضفيرة التالية هو مثال على إدخال وصف التي تُرجع معلومات حول مكان تشغيل الفيلم. يتم تضمين عدة بيانات وظائف في الطلب، مثل find_movies و find_theaters.

مثال لطلب استدعاء دالة أحادية الدور

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'

قد تشبه الرد على مثال الضفائر هذا ما يلي.

مثال لاستجابة الدالة الأحادية الدوران للحصول على استجابة

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]

مثال بدورة واحدة باستخدام وضع "أي"

يشبه مثال curl التالي مثال اللفة الواحدة، ولكنه يضبط الوضع على ANY:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

الاتصال بدالة أحادية الدور باستخدام أي وضع (طلب)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'

قد يكون الرد مشابهًا لما يلي:

استدعاء دالة من دور واحد باستخدام أي وضع (ردّ)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

مثال بدورة واحدة باستخدام وضع "أي" والدوال المسموح بها

مثال التجعيد التالي يشبه مثال على منعطف واحد، لكنه يحدد الوضع إلى ANY ويتضمن قائمة الدوال:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

استدعاء دالة من دور واحد باستخدام أي وضع والدوال المسموح بها (الطلب)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'

لا يمكن للنموذج توقُّع الدالة find_movies لأنّها غير مدرَجة في القائمة. من الدوال المسموح بها، لذا فهي تتنبأ بدالة مختلفة بدلاً منها. الردّ مشابه لما يلي:

استدعاء دالة في خطوة واحدة باستخدام وضع ANY والدوال المسموح بها (الردّ)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

أمثلة على المحادثات المتعدّدة المقاطع

يمكنك تنفيذ سيناريو استدعاء دالة متعدّد الأدوار باتّباع الخطوات التالية:

  1. يمكنك الحصول على استجابة لطلب الدالة من خلال استدعاء النموذج اللغوي. هذه هي المرة الأولى التي يتم فيها تنفيذ الخطوة.
  2. استخدِم استجابة طلب الدالة من الردّ الأول واستجابة الدالة التي تحصل عليها من طلب هذه الدالة للاتصال بنموذج اللغة. هذه هي الجولة الثانية.

تلخص الاستجابة من الدور الثاني النتائج للإجابة على في الدور الأول، أو يحتوي على استدعاء دالة ثانٍ يمكنك استخدامه مزيد من المعلومات حول طلب بحثك.

يتضمّن هذا الموضوع مثالَين على طلبات curl متعددة الأدوار:

استخدام ردّ من جولة سابقة

يستدعي نموذج التجعيد التالي الدالة والوسيطات التي تم عرضها بواسطة المثال السابق منعطفًا واحدًا للحصول على رد. تتوفّر في ملف JSON هذا الطريقة والمَعلمات التي يعرضها مثال الردّ الواحد.

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

مثال لطلب استدعاء دالة متعددة الأدوار

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

يتضمّن الردّ على مثال curl هذا نتيجة استدعاء الأسلوب find_theaters. قد يكون الرد مشابهًا لما يلي:

مثال على استجابة دالة متعددة الأدوار تستدعي curl

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}

طلب النموذج عدة مرات

يستدعي مثال cURL التالي نموذج الذكاء الاصطناعي التوليدي عدة مرات لاستدعاء دالة. في كل مرة يستدعي فيها النموذج الدالة، يمكنه استخدام دالة مختلفة للإجابة عن طلب بحث مختلف من المستخدم في الطلب.

مثال لطلب استدعاء دالة متعددة الأدوار

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

مثال على ردّ استدعاء دالة متعددة الأدوار

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]

أفضل الممارسات

اتبع أفضل الممارسات هذه لتحسين دقة موثوقية استدعاءات الدوال.

طلب من المستخدم

للحصول على أفضل النتائج، أضِف طلب بحث المستخدم في البداية مع تضمين التفاصيل التالية:

  • سياق إضافي للنموذج على سبيل المثال، You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • تفاصيل أو تعليمات حول كيفية استخدام الدوالّ وحالات استخدامها على سبيل المثال: Don't make assumptions on showtimes. Always use a future date for showtimes.
  • تعليمات لطرح أسئلة توضيحية إذا كانت طلبات بحث المستخدمين مبهمة بالنسبة مثال: Ask clarifying questions if not enough information is available to complete the request.

معلمات أخذ العينات

بالنسبة إلى مَعلمة درجة الحرارة، استخدِم 0 أو قيمة منخفضة أخرى. ويؤدي ذلك إلى توجيه النموذج لإنشاء نتائج أكثر ثقة والحدّ من الأوهام.

استدعاء واجهة برمجة التطبيقات

إذا اقترح النموذج استدعاء دالة من شأنها إرسال طلب، أو تحديث قاعدة بيانات، أو كان هناك عواقب وخيمة، فتحقق من صحة مع المستخدم قبل تنفيذه.