مقدمه ای برای فراخوانی تابع با Gemini API

توابع سفارشی را می توان با استفاده از قابلیت فراخوانی تابع تعریف و برای مدل های Gemini ارائه کرد. مدل‌ها مستقیماً این توابع را فراخوانی نمی‌کنند، بلکه در عوض خروجی داده‌های ساختاری تولید می‌کنند که نام تابع و آرگومان‌های پیشنهادی را مشخص می‌کند. این خروجی به شما امکان می‌دهد برنامه‌هایی بنویسید که خروجی ساخت‌یافته را می‌گیرند و APIهای خارجی را فراخوانی می‌کنند، و خروجی API حاصل می‌تواند در یک اعلان مدل دیگر گنجانده شود و پاسخ‌های پرس و جو جامع‌تری را ممکن می‌سازد. فراخوانی تابع، کاربران را قادر می‌سازد تا با اطلاعات بلادرنگ و خدمات مختلف، مانند پایگاه‌های داده، سیستم‌های مدیریت ارتباط با مشتری و مخازن اسناد تعامل داشته باشند و توانایی آن‌ها را برای ارائه پاسخ‌های مرتبط و متنی افزایش دهد.

فراخوانی تابع چگونه کار می کند

شما از ویژگی فراخوانی تابع با افزودن داده های پرس و جوی ساختاریافته که رابط های برنامه نویسی را توصیف می کنند، به نام اعلان تابع ، به اعلان مدل استفاده می کنید. اعلان‌های تابع نام تابع API را ارائه می‌کنند، هدف آن، هر پارامتری را که پشتیبانی می‌کند و توصیف آن پارامترها را توضیح می‌دهند. پس از اینکه لیستی از اعلان های تابع در یک کوئری را به مدل ارسال کردید، اعلان های تابع و بقیه پرس و جو را تجزیه و تحلیل می کند تا نحوه استفاده از API اعلام شده در پاسخ به درخواست را تعیین کند.

سپس مدل یک شی را در یک طرحواره سازگار با OpenAPI برمی گرداند که نحوه فراخوانی یک یا چند تابع اعلام شده را برای پاسخ به سؤال کاربر مشخص می کند. سپس می‌توانید پارامترهای فراخوانی تابع توصیه‌شده را بگیرید، API واقعی را فراخوانی کنید، پاسخی دریافت کنید و آن پاسخ را به کاربر ارائه دهید یا اقدامات بعدی را انجام دهید. توجه داشته باشید که مدل در واقع توابع اعلام شده را فراخوانی نمی کند. در عوض، شما از پارامترهای شی طرحواره برگشتی برای فراخوانی تابع استفاده می کنید. Gemini API همچنین از فراخوانی تابع موازی پشتیبانی می کند، که در آن مدل چندین تابع 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 (رشته): شناسه منحصر به فرد برای تابع در فراخوانی API.
  • description (رشته): توضیحی جامع از هدف و قابلیت های تابع.
  • parameters (شیء): داده های ورودی مورد نیاز تابع را تعریف می کند.
    • type (string): نوع کلی داده را مشخص می کند، مانند object .
    • properties (شیء): پارامترهای فردی را فهرست می کند که هر کدام دارای:
      • type (string): نوع داده پارامتر مانند 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 location to search ، از The city and state, eg San Francisco, CA or a zip code eg 95616 استفاده کنید.

برای بهترین روش‌های بیشتر هنگام استفاده از فراخوانی تابع، بخش بهترین روش‌ها را ببینید.

عملکرد حالت تماس

می توانید از پارامتر 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 و شرح تابع مشخص می‌کنید.

مثال تک چرخشی

Single-turn زمانی است که یک بار مدل زبان را فرا می خوانید. با فراخوانی تابع، یک مورد استفاده تک نوبتی ممکن است زمانی باشد که یک جستار زبان طبیعی و لیستی از توابع را به مدل ارائه دهید. در این حالت، مدل از اعلان تابع استفاده می کند که شامل نام تابع، پارامترها و توضیحات است تا پیش بینی کند کدام تابع را فراخوانی کند و آرگومان هایی که آن را با آن فراخوانی کند.

نمونه 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 

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

مثال حلقه زیر شبیه به مثال یک چرخش است، اما حالت را روی 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"
      }
    ]
  }
}

مثال تک چرخشی با استفاده از هر حالت و توابع مجاز

مثال 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 را پیش‌بینی کند، زیرا در لیست توابع مجاز نیست، بنابراین در عوض یک تابع متفاوت را پیش‌بینی می‌کند. پاسخ ممکن است مشابه موارد زیر باشد:

فراخوانی تابع تک چرخشی با استفاده از هر حالت و توابع مجاز (پاسخ) 

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

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 زیر چندین بار مدل AI مولد را برای فراخوانی یک تابع فراخوانی می کند. هر بار که مدل تابع را فراخوانی می‌کند، می‌تواند از یک تابع متفاوت برای پاسخ به درخواست کاربر مختلف در درخواست استفاده کند.

تابع چند نوبتی فراخوانی درخواست مثال 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 یا مقدار پایین دیگری استفاده کنید. این به مدل دستور می دهد تا نتایج مطمئن تری تولید کند و توهمات را کاهش دهد.

فراخوانی API

اگر مدل فراخوانی تابعی را پیشنهاد می‌کند که می‌تواند سفارشی را ارسال کند، پایگاه داده را به‌روزرسانی کند یا پیامدهای مهمی داشته باشد، قبل از اجرای فراخوانی تابع با کاربر اعتبارسنجی کنید.