استدعاء الدوالّ

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

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

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

عند تنفيذ استدعاء الدالة، يمكنك إنشاء بيان دالة واحد أو أكثر، ثم إضافة إعلانات الدوال إلى عنصر tools الذي تم تمريره إلى النموذج. يحتوي كل تعريف دالة على معلومات حول دالة واحدة تتضمن ما يلي:

  • اسم الوظيفة
  • معلمات الدالة بتنسيق مخطط OpenAPI متوافق. ويمكن استخدام مجموعة فرعية محدّدة. عند استخدام curl، يتم تحديد المخطط باستخدام JSON.
  • وصف الدالة (اختياري). لتحقيق أفضل النتائج، ننصحك بتضمين وصف

يتضمن هذا المستند أمثلة على التوليف لإجراء استدعاءات REST باستخدام الفئة GenerativeModel وطرقها.

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

تدعم النماذج التالية وظيفة استدعاء الدالة:

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

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

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

  • 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 مع استدعاء الدالة:

عينة اللفّات الأحادية الدوران

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

عينة 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
  }
}]

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

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

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

استدعاء وظيفة أحادية الدوران باستخدام وضع "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 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. قد يكون الرد مشابهًا لما يلي:

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

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

مثال على عملية تجعيد يستدعي نموذجًا لغويًا عدة مرات

يستدعي مثال curl التالي النموذج اللغوي عدة مرات لاستدعاء دالة. في كل مرة يستدعي النموذج الدالة، يمكن أن يستخدم دالة مختلفة للإجابة عن استعلام مستخدم مختلف في الطلب.

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

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "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 (سلسلة): المعرّف الفريد للدالة ضمن طلب بيانات من واجهة برمجة التطبيقات.
    • أفضل الممارسات: استخدِم أسماءً واضحةً ووصفية بدون مسافة أو حرف (.) أو شرطة (-). بدلاً من ذلك، استخدِم أحرف الشرطة السفلية (_) أو حالة الجمل.
  • description (سلسلة): شرح شامل للغرض من الدالة وإمكاناتها
    • أفضل الممارسات: قدِّم أوصافًا مفصّلة وواضحة ومحددة، مع تقديم أمثلة إذا لزم الأمر. على سبيل المثال، بدلاً من find theaters، استخدِم find theaters based on location and optionally movie title that is currently playing in theaters. وتجنَّب الأوصاف الواسعة النطاق أو الغامضة.
  • parameters (كائن): لتحديد بيانات الإدخال التي تطلبها الدالة.
    • type (سلسلة): تحدِّد نوع البيانات بشكل عام (مثلاً، object).
    • properties (كائن):
      • يسرد المَعلمات الفردية، مع كلّ منها:
        • type (سلسلة): نوع البيانات للمَعلمة (مثل string، integer، boolean).
          • أفضل الممارسات: استخدِم المَعلمات المكتوبة بشدّة لتقليل الهلوسة في النموذج. على سبيل المثال، إذا كانت قيم المَعلمات من مجموعة محدودة، استخدِم الحقل enum بدلاً من إدراج القيم في الوصف (مثل "type": "enum", "values": ["now_playing", "upcoming"]). إذا كانت قيمة المعلَمة دائمًا عدد صحيح، اضبط النوع على integer بدلاً من number.
        • description (سلسلة): شرح واضح للغرض من المَعلمة والتنسيق المتوقَّع
          • أفضل الممارسات: قدِّم أمثلة وقيودًا ملموسة. على سبيل المثال، استخدِم The city and state, e.g. San Francisco, CA or a zip code e.g. 95616 بدلاً من the location to search.
    • 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 أو قيمة أخرى منخفضة. حيث يوجه هذا النموذج لإنشاء نتائج أكثر ثقة ويقلل من الهلوسة.

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

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