فراخوانی تابع

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

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

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

هنگامی که فراخوانی تابع را پیاده سازی می کنید، یک یا چند اعلان تابع ایجاد می کنید، سپس اعلان های تابع را به یک شی tools اضافه می کنید که به مدل ارسال می شود. هر اعلان تابع حاوی اطلاعاتی در مورد یک تابع است که شامل موارد زیر است:

  • نام تابع
  • پارامترهای تابع در قالب طرحواره سازگار با OpenAPI . یک زیر مجموعه انتخابی پشتیبانی می شود. هنگام استفاده از curl، طرحواره با استفاده از JSON مشخص می شود.
  • شرح عملکرد (اختیاری). برای بهترین نتیجه، توصیه می‌کنیم که توضیحاتی را نیز درج کنید.

این سند شامل نمونه های curl است که با کلاس GenerativeModel و متدهای آن، REST را فراخوانی می کند.

مدل های پشتیبانی شده

مدل های زیر از فراخوانی تابع پشتیبانی می کنند:

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

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

می توانید از حالت فراخوانی تابع برای تعریف رفتار اجرا برای فراخوانی تابع استفاده کنید. سه حالت موجود است:

  • AUTO : رفتار مدل پیش فرض. مدل تصمیم می گیرد که یک فراخوانی تابع یا یک پاسخ زبان طبیعی را پیش بینی کند.
  • ANY : مدل محدود شده است تا همیشه یک فراخوانی تابع را پیش بینی کند. اگر allowed_function_names ارائه نشده باشد، مدل از بین تمام اعلان‌های تابع موجود انتخاب می‌کند. اگر allowed_function_names ارائه شده باشد ، مدل از مجموعه توابع مجاز انتخاب می کند.
  • NONE : مدل فراخوانی تابع را پیش بینی نمی کند. در این مورد، رفتار مدل مانند این است که هیچ اعلان تابعی را ارسال نکنید.

همچنین می‌توانید مجموعه‌ای از allowed_function_names را ارسال کنید که در صورت ارائه، عملکردهایی را که مدل فراخوانی می‌کند محدود می‌کند. شما باید فقط allowed_function_names در زمانی بگنجانید که حالت ANY باشد. نام توابع باید با نام اعلان تابع مطابقت داشته باشد. با تنظیم حالت بر روی ANY و تنظیم نام allowed_function_names ، مدل یک فراخوانی تابع را از مجموعه نام های تابع ارائه شده پیش بینی می کند.

در اینجا بخشی از یک درخواست مثال است که حالت را روی ANY تنظیم می کند و لیستی از توابع مجاز را مشخص می کند:

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

تابع فراخوانی نمونه های cURL

هنگامی که از cURL استفاده می کنید، اطلاعات تابع و پارامتر در عنصر tools گنجانده می شود. هر اعلان تابع در عنصر tools حاوی نام تابع، پارامترهای مشخص شده با استفاده از طرحواره سازگار با OpenAPI و توضیحات تابع است. نمونه‌های زیر نحوه استفاده از دستورات curl را با فراخوانی تابع نشان می‌دهند:

نمونه حلقه یک دور

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

نمونه curl زیر نمونه‌ای از توضیح عملکردی است که اطلاعات مربوط به مکان پخش فیلم را برمی‌گرداند. چندین اعلان تابع در درخواست گنجانده شده است، مانند find_movies و find_theaters .

درخواست مثال 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?"
    }
  },
  "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 که از پاسخی از نوبت قبلی استفاده می کند

نمونه 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": "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"]
      }
    }]
  }]
}'

پاسخ به این مثال 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

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

تابع چند چرخشی فراخوانی پاسخ مثال 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
  }
}
]

بهترین شیوه ها

این بهترین شیوه ها را برای بهبود دقت و قابلیت اطمینان تماس های عملکرد خود دنبال کنید.

فیلدهای کلید تابع

تعریف دقیق توابع هنگام ادغام آنها در درخواست های شما ضروری است. هر تابع بر پارامترهای خاصی متکی است که رفتار و تعامل آن با مدل را هدایت می کند. در اینجا یک تفکیک از پارامترهای کلیدی مورد استفاده در آرایه functions_declarations آمده است.

function_declarations (آرایه) :

  • شامل یک یا چند شیء است که هر کدام یک تابع مجزا را نشان می دهند.

در هر شیء function_declarations :

  • name (string) : شناسه منحصر به فرد برای تابع در فراخوانی API.
    • بهترین تمرین : از نام‌های واضح و توصیفی بدون فاصله، نقطه ( . ) یا خط تیره ( - ) استفاده کنید. در عوض، از نویسه های زیرخط ( _ ) یا شتر استفاده کنید.
  • description (رشته) : توضیحی جامع از هدف و قابلیت های تابع.
    • بهترین روش : در توضیحات عملکرد دقیق، واضح و مشخص باشید و در صورت لزوم مثال هایی ارائه دهید. به‌عنوان مثال، به‌جای find theaters ، find theaters based on location and optionally movie title that is currently playing in theaters. از توصیف های بیش از حد گسترده یا مبهم خودداری کنید.
  • parameters (شیء) : داده های ورودی مورد نیاز تابع را تعریف می کند.
    • type (string) : نوع کلی داده را مشخص می کند (به عنوان مثال، object ).
    • properties (شیء) :
      • پارامترهای جداگانه را فهرست می کند، که هر کدام دارای:
        • type (string) : نوع داده پارامتر (به عنوان مثال، string ، integer ، boolean ).
          • بهترین تمرین : از پارامترهای تایپ شده قوی برای کاهش توهمات مدل استفاده کنید. به عنوان مثال، اگر مقادیر پارامتر از یک مجموعه محدود هستند، به جای فهرست کردن مقادیر در توضیحات، از یک فیلد enum استفاده کنید (به عنوان مثال، "type": "enum", "values": ["now_playing", "upcoming"] ) . اگر مقدار پارامتر همیشه یک عدد صحیح است، نوع را به جای number ، integer قرار دهید.
        • description (رشته) : توضیح واضحی از هدف پارامتر و قالب مورد انتظار.
          • بهترین روش : مثال‌ها و محدودیت‌های عینی ارائه کنید. به عنوان مثال، به جای the location to search ، از The city and state, eg San Francisco, CA or a zip code eg 95616 استفاده کنید.
    • required (آرایه) :
      • آرایه ای از رشته ها که نام پارامترهایی را که برای عملکرد تابع الزامی هستند فهرست می کند.

درخواست کاربر

برای بهترین نتایج، درخواست کاربر را با جزئیات زیر اضافه کنید:

  • زمینه اضافی برای مدل برای مثال، 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

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