مقدّمة عن استدعاء الدوال باستخدام 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، ووصف الدالة.

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

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

نموذج curl التالي هو مثال على إدخال وصف لدالّة تعرض معلومات عن مكان عرض فيلم. يتم تضمين عدة بيانات وظائف في الطلب، مثل 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"
            ]
          }
        }
      ]
    }
  ]
}'

قد يكون ردّ مثال curl هذا مشابهًا لما يلي.

مثال على استجابة دالة تستدعي curl في خطوة واحدة

[{
  "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 والدوال المسموح بها

يشبه مثال curl التالي مثال الخطوة الواحدة، ولكنه يضبط الوضع على 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 متعددة الأدوار:

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

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

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

مثال على طلب دالّة متعددة الأدوار تستدعي 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"
            }]
          }
        }
      }
    }]
  }],
  "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

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"]
      }
    }]
  }]
}'

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

[{
  "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 أو قيمة منخفضة أخرى. ويؤدي ذلك إلى توجيه النموذج لإنشاء نتائج أكثر ثقة والحدّ من الأوهام.

طلب بيانات من واجهة برمجة التطبيقات

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