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

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

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

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

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

الطُرز المتوافقة

تتيح النماذج التالية ميزة استدعاء الدالة:

• gemini-1.0-pro
• gemini-1.0-pro-001
• gemini-1.5-flash-latest
• gemini-1.5-pro-latest

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

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

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

للحصول على أمثلة عن الرموز البرمجية لبيان دالة باستخدام أوامر cURL، راجع أمثلة على استدعاء الدوال أمثلة ومعلومات حول إنشاء بيانات الدوال للأنظمة الأساسية الأخرى، راجع دليل الأنظمة الأساسية لاستدعاء الدوال

أفضل الممارسات لإعلانات الدوال

يعد تحديد الدوال بدقة أمرًا ضروريًا عند دمجها في الطلبات. تعتمد كل دالة على معلمات محددة توجه سلوكها والتفاعل مع النموذج. توفر القائمة التالية إرشادات حول تحديد معلَمات دالة فردية في 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 فقط.

يمكنك أيضًا ضبط مجموعة من 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
  }
}]
    

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

مثال التجعيد التالي يشبه مثال على منعطف واحد، لكنه يحدد الوضع في 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 لأنّها غير مدرَجة في القائمة. من الدوال المسموح بها، لذا فهي تتنبأ بدالة مختلفة بدلاً منها. الردّ مشابه لما يلي:

{
  "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. يمكنك الحصول على استجابة لطلب الدالة من خلال استدعاء النموذج اللغوي. هذا هو الأول cannot translate
2. استدعِ النموذج اللغوي باستخدام استجابة استدعاء الدالة من أول منعطف والاستجابة الدالة التي تحصل عليها من استدعاء هذه الدالة. هذه هي منعطفة ثانية.

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

يتضمّن هذا الموضوع مثالين على تمويج الشعر متعدد الأدوار:

• مثال على تجعيد يستخدم استجابة دالة من منعطف سابق
• مثال على تجعيد يطلب نموذجًا لغويًا عدة مرات

استخدام رد من منعطف سابق

يستدعي نموذج التجعيد التالي الدالة والوسيطات التي تم عرضها بواسطة المثال السابق منعطفًا واحدًا للحصول على رد. الطريقة والمعلمات التي يتم إرجاعها في مثال دورة واحدة موجودة في ملف 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": "function",
    "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"]
      }
    }]
  }]
}'
    

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

{
  "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
  }
}
    

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

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

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": "function",
    "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 أو قيمة منخفضة أخرى. هذا يوجه النموذج لتوليد نتائج أكثر ثقة ويقلل من الهلوسة.

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

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