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

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

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

طريقة عمل ميزة "استدعاء الدوال"

نظرة عامة على ميزة "استدعاء الدوال"

تتضمّن ميزة "استدعاء الدوال" تفاعلاً منظَّمًا بين تطبيقك والنموذج والدوال الخارجية. في ما يلي تفاصيل العملية:

  1. تحديد تعريف الدالة: حدِّد تعريف الدالة في رمز تطبيقك. تصف تعريفات الدوال اسم الدالة ومعلماتها والغرض منها للنموذج.
  2. استدعاء نموذج اللغة الكبير باستخدام تعريفات الدوال: أرسِل طلب المستخدم مع تعريفات الدوال إلى النموذج. ويحلّل الطلب ويحدّد ما إذا كان استدعاء دالة سيكون مفيدًا. وفي حال توفّرها، سيردّ عليك بنتيجة منظَّمة على شكل عنصر JSON.
  3. تنفيذ رمز الدالة (مسؤوليتك): لا ينفّذ النموذج الدالة بنفسه. يقع على عاتق تطبيقك مسؤولية معالجة الرد والتحقّق من Function Call، إذا كان
    • نعم: استخرِج اسم الدالة ووسيطاتها ونفِّذ الدالة المقابلة في تطبيقك.
    • لا: قدّم النموذج ردًا نصيًا مباشرًا على الطلب (هذا المسار أقل أهمية في المثال، لكنّه نتيجة محتملة).
  4. إنشاء ردّ سهل الاستخدام: إذا تم تنفيذ دالة، سجِّل النتيجة وأرسِلها مرة أخرى إلى النموذج في دورة لاحقة من المحادثة. سيستخدم النتيجة لإنشاء رد نهائي سهل الاستخدام يتضمّن المعلومات من طلب تنفيذ الدالة.

يمكن تكرار هذه العملية عدة مرات، ما يتيح إجراء تفاعلات وعمليات سير عمل معقّدة. يتيح النموذج أيضًا استدعاء دوال متعددة في دورة واحدة (استدعاء الدوال المتوازية) وبشكل متسلسل (استدعاء الدوال التركيبية).

الخطوة 1: تحديد تعريف دالة

حدِّد دالة وبيانها ضمن رمز تطبيقك يسمح للمستخدمين بضبط قيم الإضاءة وإجراء طلب إلى واجهة برمجة التطبيقات. يمكن أن تستدعي هذه الدالة خدمات أو واجهات برمجة تطبيقات خارجية.

Python

# Define a function that the model can call to control smart lights
set_light_values_declaration = {
    "name": "set_light_values",
    "description": "Sets the brightness and color temperature of a light.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "integer",
                "description": "Light level from 0 to 100. Zero is off and 100 is full brightness",
            },
            "color_temp": {
                "type": "string",
                "enum": ["daylight", "cool", "warm"],
                "description": "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
            },
        },
        "required": ["brightness", "color_temp"],
    },
}

# This is the actual function that would be called based on the model's suggestion
def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {"brightness": brightness, "colorTemperature": color_temp}

JavaScript

import { Type } from '@google/genai';

// Define a function that the model can call to control smart lights
const setLightValuesFunctionDeclaration = {
  name: 'set_light_values',
  description: 'Sets the brightness and color temperature of a light.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'Light level from 0 to 100. Zero is off and 100 is full brightness',
      },
      color_temp: {
        type: Type.STRING,
        enum: ['daylight', 'cool', 'warm'],
        description: 'Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.',
      },
    },
    required: ['brightness', 'color_temp'],
  },
};

/**

*   Set the brightness and color temperature of a room light. (mock API)
*   @param {number} brightness - Light level from 0 to 100. Zero is off and 100 is full brightness
*   @param {string} color_temp - Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
*   @return {Object} A dictionary containing the set brightness and color temperature.
*/
function setLightValues(brightness, color_temp) {
  return {
    brightness: brightness,
    colorTemperature: color_temp
  };
}

الخطوة 2: استدعاء النموذج باستخدام تعريفات الدوال

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

Python

from google.genai import types

# Configure the client and tools
client = genai.Client()
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])

# Define user prompt
contents = [
    types.Content(
        role="user", parts=[types.Part(text="Turn the lights down to a romantic level")]
    )
]

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=contents
    config=config,
)

print(response.candidates[0].content.parts[0].function_call)

JavaScript

import { GoogleGenAI } from '@google/genai';

// Generation config with function declaration
const config = {
  tools: [{
    functionDeclarations: [setLightValuesFunctionDeclaration]
  }]
};

// Configure the client
const ai = new GoogleGenAI({});

// Define user prompt
const contents = [
  {
    role: 'user',
    parts: [{ text: 'Turn the lights down to a romantic level' }]
  }
];

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: contents,
  config: config
});

console.log(response.functionCalls[0]);

بعد ذلك، يعرض النموذج كائن functionCall في مخطط متوافق مع OpenAPI يحدّد كيفية طلب دالة واحدة أو أكثر من الدوال المحدّدة من أجل الرد على سؤال المستخدم.

Python

id=None args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'

JavaScript

{
  name: 'set_light_values',
  args: { brightness: 25, color_temp: 'warm' }
}

الخطوة 3: تنفيذ رمز الدالة set_light_values

استخرِج تفاصيل طلب استدعاء الدالة من ردّ النموذج، وحلِّل الوسيطات، ونفِّذ الدالة set_light_values.

Python

# Extract tool call details, it may not be in the first part.
tool_call = response.candidates[0].content.parts[0].function_call

if tool_call.name == "set_light_values":
    result = set_light_values(**tool_call.args)
    print(f"Function execution result: {result}")

JavaScript

// Extract tool call details
const tool_call = response.functionCalls[0]

let result;
if (tool_call.name === 'set_light_values') {
  result = setLightValues(tool_call.args.brightness, tool_call.args.color_temp);
  console.log(`Function execution result: ${JSON.stringify(result)}`);
}

الخطوة 4: إنشاء ردّ سهل الاستخدام يتضمّن نتيجة الدالة واستدعاء النموذج مرة أخرى

أخيرًا، أرسِل نتيجة تنفيذ الدالة إلى النموذج ليتمكّن من دمج هذه المعلومات في الرد النهائي الذي يقدّمه للمستخدم.

Python

# Create a function response part
function_response_part = types.Part.from_function_response(
    name=tool_call.name,
    response={"result": result},
)

# Append function call and result of the function execution to contents
contents.append(response.candidates[0].content) # Append the content from the model's response.
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response

final_response = client.models.generate_content(
    model="gemini-2.5-flash",
    config=config,
    contents=contents,
)

print(final_response.text)

JavaScript

// Create a function response part
const function_response_part = {
  name: tool_call.name,
  response: { result }
}

// Append function call and result of the function execution to contents
contents.push(response.candidates[0].content);
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });

// Get the final response from the model
const final_response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: contents,
  config: config
});

console.log(final_response.text);

بهذا تنتهي عملية استدعاء الدوال. استخدم النموذج الدالة set_light_values بنجاح لتنفيذ الإجراء المطلوب من المستخدم.

تعريفات الدوال

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

  • name (string): اسم فريد للدالة (get_weather_forecast، send_email). استخدِم أسماء وصفية بدون مسافات أو أحرف خاصة (استخدِم الشرطات السفلية أو camelCase).
  • description (سلسلة): شرح واضح ومفصّل لغرض الدالة وإمكاناتها. وهذا أمر بالغ الأهمية لكي يفهم النموذج متى يجب استخدام الدالة. كن دقيقًا وقدِّم أمثلة إذا كان ذلك مفيدًا ("تعثر على دور السينما استنادًا إلى الموقع الجغرافي وعنوان الفيلم اختياريًا، والذي يتم عرضه حاليًا في دور السينما").
  • parameters (كائن): يحدّد مَعلمات الإدخال التي تتوقّعها الدالة.
    • type (سلسلة): يحدّد نوع البيانات العام، مثل object.
    • properties (عنصر): يدرج المَعلمات الفردية، ويتضمّن كل منها:
      • type (string): نوع بيانات المَعلمة، مثل string وinteger وboolean, array
      • description (سلسلة): وصف لغرض المَعلمة وتنسيقها. قدِّم أمثلة وقيودًا ("المدينة والولاية، مثل "القاهرة، مصر" أو رمز بريدي، مثل '95616'.").
      • enum (مصفوفة، اختياري): إذا كانت قيم المَعلمات من مجموعة ثابتة، استخدِم "enum" لإدراج القيم المسموح بها بدلاً من مجرد وصفها في الوصف. يؤدي ذلك إلى تحسين الدقة ("enum": ["daylight", "cool", "warm"]).
    • required (مصفوفة): مصفوفة من السلاسل النصية تسرد أسماء المَعلمات التي يجب توفّرها لكي تعمل الدالة.

استدعاء الدوال مع التفكير

يمكن أن يؤدي تفعيل "التفكير" إلى تحسين أداء طلبات الدوال من خلال السماح للنموذج بالاستدلال على الطلب قبل اقتراح طلبات الدوال.

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

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

لاستخدام توقيعات الأفكار، اتّبِع الخطوات التالية:

  1. تلقّي التوقيع: عند تفعيل ميزة "التفكير"، سيتضمّن الردّ من واجهة برمجة التطبيقات الحقل thought_signature الذي يحتوي على تمثيل مشفّر لعملية الاستدلال التي أجراها النموذج.
  2. إرجاع التوقيع: عند إرسال نتيجة تنفيذ الدالة إلى الخادم، يجب تضمين thought_signature الذي تلقّيته.

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

تلقّي التواقيع من الخادم

يتم عرض التوقيعات في الجزء الذي يلي مرحلة التفكير في النموذج، والذي يكون عادةً نصًا أو استدعاء دالة.

في ما يلي بعض الأمثلة على شكل توقيعات الأفكار التي يتم عرضها في كل نوع من الأجزاء، وذلك استجابةً للطلب "ما هي حالة الطقس في بحيرة تاهو؟" باستخدام المثال Get Weather:

جزء النص

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here's what the weather in Lake Tahoe is today",
            "thoughtSignature": "ClcBVKhc7ru7KzUI7SrdUoIdAYLm/+i93aHjfIt4xHyAoO/G70tApxnK2ujBhOhC1PrRy1pkQa88fqFvpHNVd1HDjNLO7mkp6/hFwE+SPPEB3fh0hs4oM8MKhgIBVKhc7uIGvrS7i/T4HpfbnYrluFfWNjZ62gewqe4cVdR/Dlh+zbjtYmDD0gPZ+SuBO7vvHQdzsjePRP+2Y5XddX6LEf/cGGgakq8EhVvw/a6IVzUO6XmpHg2Ag1sl8E9+VFH/lC0R0ZuYdFWligtDuYwp5p5q3o59G0TtWeU2MC1y2MJfE9u/KWd313ldka80/X2W/xF2O/4djMp5G2WKcULfve75zeRCy0mc5iS3SB9mTH0cT6x0vtKjeBx50gcg+CQWtJcRuwTVzz54dmvmK9xvnqA8gKGw3DuaM9wfy5hyY7Qg0z3iyyWdP8T/lbjKim8IEQOk7O1vVwP1Ko7oMYH8JgA1CsoBAVSoXO6v4c5RSyd1cn6EIU0pEFQsjW7rYWPuZdOFq/tsGJT9BCfW7KGkPGwlNSq8jTJFvbcJ/DjtndISQYXwiXd2kGa5JfdS2Kh4zOxCxiWtOk+2nCc3+XQk2nonhO+esGJpkDdbbHZSqRgcUtYKq7q28iPFOQvOFyCiZNB7K86Z/6Hnagu2snSlN/BcTMaFGaWpcCClSUo4foRZn3WbNCoM8rcpD7qEJMp4a5baaSxyyeL1ZTGd2HLpFys/oiW6e3oAnhxuIysCwg=="
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  # Remainder of response...

جزء استدعاء الدالة

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "getWeather",
              "args": {
                "city": "Lake Tahoe"
              }
            },
            "thoughtSignature": "CiwBVKhc7nRyTi3HmggPD9iQiRc261f5jwuMdw3H/itDH0emsb9ZVo3Nwx9p6wpsAVSoXO5i8fDV4jBSBLoaWxB5zUdlGY6aIGp+I0oEnwRRSRQ1LOvrDlojEH8JE8HjiKXALdJrvNPiG+HY3GZEO8pZjEZtc3UoBUh7+SVyjK7Xolu7aRYYeUyzrCapoETWypER1jbrJXnFV23hCosBAVSoXO6oIPNJSmbuEDfGafOhuCSHkpr1yjTp35RXYqmCESzRzWf5+nFXLqncqeFo4ohoxbiYQVpVQbOZF81p8o9zg6xeRE7qMeOv+XN7enXGJ4/s3qNFQpfkSMqRdBITN1VpX7jyfEAjvxBNc7PDfDJZmEPY338ZIY5nFFcmzJSWjVrboFt2sMFv+A=="
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  # Remainder of response...

يمكنك التأكّد من تلقّي توقيع والاطّلاع على شكله باستخدام الرمز التالي:

# Step 2: Call the model with function declarations
# ...Generation config, Configure the client, and Define user prompt (No changes)

# Send request with declarations (using a thinking model)
response = client.models.generate_content(
  model="gemini-2.5-flash", config=config, contents=contents)

# See thought signatures
for part in response.candidates[0].content.parts:
  if part.thought_signature:
    print("Thought signature:")
    print(part.thought_signature)

إعادة التواقيع إلى الخادم

لاستعادة التواقيع، اتّبِع الخطوات التالية:

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

سيبقى الرمز كما هو في الخطوة 4 من القسم السابق. ولكن في هذه الحالة (كما هو موضّح في التعليق أدناه)، ستعرض التوقيعات على النموذج مع نتيجة تنفيذ الدالة حتى يتمكّن النموذج من دمج الأفكار في رده النهائي:

Python

# Step 4: Create user friendly response with function result and call the model again
# ...Create a function response part (No change)

# Append thought signatures, function call and result of the function execution to contents
function_call_content = response.candidates[0].content
# Append the model's function call message, which includes thought signatures
contents.append(function_call_content)
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response

final_response = client.models.generate_content(
    model="gemini-2.5-flash",
    config=config,
    contents=contents,
)

print(final_response.text)

JavaScript

// Step 4: Create user friendly response with function result and call the model again
// ...Create a function response part (No change)

// Append thought signatures, function call and result of the function execution to contents
const function_response_content = response.candidates[0].content;
contents.push(function_response_content);
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });

const final_response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: contents,
  config: config
});

console.log(final_response.text);

يوضّح ما يلي الشكل الذي قد يبدو عليه طلب يعرض توقيعًا فكريًا:

[{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "what is the weather in Lake Tahoe?"
        }
      ]
    },
    {
      "parts": [
        {
          "functionCall": {
            "name": "getWeather",
            "args": {
              "city": "Lake Tahoe"
            }
          },
          "thoughtSignature": "CiIBVKhc7oDPpCaXyJKKssjqr4g3JNOSgJ/M2V+1THC1icsWCmwBVKhc7pBABbZ+zR3e9234WnWWS6GFXmf8IVwpnzjd5KYd7vyJbn/4vTorWBGayj/vbd9JPaZQjxdAIXhoE5mX/MDsQ7M9N/b0qJjHm39tYIBvS4sIWkMDHqTJqXGLzhhKtrTkfbV3RbaJEkQKmwEBVKhc7qVUgC3hfTXZLo9R3AJzUUIx50NKvJTb9B+UU+LBqgg7Nck1x5OpjWVS2R+SsveprIuYOruk2Y0H53J2OJF8qsxTdIq2si8DGW2V7WK8xyoJH5kbqd7drIw1jLb44b6lx4SMyB0VaULuTBki4d+Ljjg1tJTwR0IYMKqDLDZt9mheINsi0ZxcNjfpnDydRXdWbcSwzmK/wgqJAQFUqFzuKgNVElxs3cbO+xebr2IwcOro84nKTisi0tTp9bICPC9fTUhn3L+rvQWA+d3J1Za8at2bakrqiRj7BTh+CVO9fWQMAEQAs3ni0Z2hfaYG92tOD26E4IoZwyYEoWbfNudpH1fr5tEkyqnEGtWIh7H+XoZQ2DXeiOa+br7Zk88SrNE+trJMCogBAVSoXO5e9fBLg7hnbkmKsrzNLnQtLsQm1gNzjcjEC7nJYklYPp0KI2uGBE1PkM8XNsfllAfHVn7LzHcHNlbQ9pJ7QZTSIeG42goS971r5wNZwxaXwCTphClQh826eqJWo6A/28TtAVQWLhTx5ekbP7qb4nh1UblESZ1saxDQAEo4OKPbDzx5BgqKAQFUqFzuVyjNm5i0wN8hTDnKjfpDroEpPPTs531iFy9BOX+xDCdGHy8D+osFpaoBq6TFekQQbz4hIoUR1YEcP4zI80/cNimEeb9IcFxZTTxiNrbhbbcv0969DSMWhB+ZEqIz4vuw4GLe/xcUvqhlChQwFdgIbdOQHSHpatn5uDlktnP/bi26nKuXIwo0AVSoXO7US22OUH7d1f4abNPI0IyAvhqkPp12rbtWLx9vkOtojE8IP+xCfYtIFuZIzRNZqA=="
        }
      ],
      "role": "model"
    },
    {
      "role": "user",
      "parts": [
        {
          "functionResponse": {
            "name": "getWeather",
            "response": {
              "response": {
                "stringValue": "Sunny and hot. 90 degrees Fahrenheit"
              }
            }
          }
        }
      ]
    }
  ],
  # Remainder of request...

يمكنك الاطّلاع على مزيد من المعلومات حول القيود المفروضة على استخدام توقيعات الأفكار، وحول نماذج التفكير بشكل عام، في صفحة التفكير.

استدعاء الدوال بشكلٍ متوازٍ

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

Python

power_disco_ball = {
    "name": "power_disco_ball",
    "description": "Powers the spinning disco ball.",
    "parameters": {
        "type": "object",
        "properties": {
            "power": {
                "type": "boolean",
                "description": "Whether to turn the disco ball on or off.",
            }
        },
        "required": ["power"],
    },
}

start_music = {
    "name": "start_music",
    "description": "Play some music matching the specified parameters.",
    "parameters": {
        "type": "object",
        "properties": {
            "energetic": {
                "type": "boolean",
                "description": "Whether the music is energetic or not.",
            },
            "loud": {
                "type": "boolean",
                "description": "Whether the music is loud or not.",
            },
        },
        "required": ["energetic", "loud"],
    },
}

dim_lights = {
    "name": "dim_lights",
    "description": "Dim the lights.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "number",
                "description": "The brightness of the lights, 0.0 is off, 1.0 is full.",
            }
        },
        "required": ["brightness"],
    },
}

JavaScript

import { Type } from '@google/genai';

const powerDiscoBall = {
  name: 'power_disco_ball',
  description: 'Powers the spinning disco ball.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      power: {
        type: Type.BOOLEAN,
        description: 'Whether to turn the disco ball on or off.'
      }
    },
    required: ['power']
  }
};

const startMusic = {
  name: 'start_music',
  description: 'Play some music matching the specified parameters.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      energetic: {
        type: Type.BOOLEAN,
        description: 'Whether the music is energetic or not.'
      },
      loud: {
        type: Type.BOOLEAN,
        description: 'Whether the music is loud or not.'
      }
    },
    required: ['energetic', 'loud']
  }
};

const dimLights = {
  name: 'dim_lights',
  description: 'Dim the lights.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'The brightness of the lights, 0.0 is off, 1.0 is full.'
      }
    },
    required: ['brightness']
  }
};

اضبط وضع "استدعاء الدوال" للسماح باستخدام جميع الأدوات المحدّدة. لمزيد من المعلومات، يمكنك الاطّلاع على ضبط ميزة "استدعاء الدوال".

Python

from google import genai
from google.genai import types

# Configure the client and tools
client = genai.Client()
house_tools = [
    types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]
config = types.GenerateContentConfig(
    tools=house_tools,
    automatic_function_calling=types.AutomaticFunctionCallingConfig(
        disable=True
    ),
    # Force the model to call 'any' function, instead of chatting.
    tool_config=types.ToolConfig(
        function_calling_config=types.FunctionCallingConfig(mode='ANY')
    ),
)

chat = client.chats.create(model="gemini-2.5-flash", config=config)
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call
print("Example 1: Forced function calling")
for fn in response.function_calls:
    args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
    print(f"{fn.name}({args})")

JavaScript

import { GoogleGenAI } from '@google/genai';

// Set up function declarations
const houseFns = [powerDiscoBall, startMusic, dimLights];

const config = {
    tools: [{
        functionDeclarations: houseFns
    }],
    // Force the model to call 'any' function, instead of chatting.
    toolConfig: {
        functionCallingConfig: {
            mode: 'any'
        }
    }
};

// Configure the client
const ai = new GoogleGenAI({});

// Create a chat session
const chat = ai.chats.create({
    model: 'gemini-2.5-flash',
    config: config
});
const response = await chat.sendMessage({message: 'Turn this place into a party!'});

// Print out each of the function calls requested from this single call
console.log("Example 1: Forced function calling");
for (const fn of response.functionCalls) {
    const args = Object.entries(fn.args)
        .map(([key, val]) => `${key}=${val}`)
        .join(', ');
    console.log(`${fn.name}(${args})`);
}

تعكس كل نتيجة مطبوعة طلبًا واحدًا للدالة قد طلبه النموذج. لإعادة إرسال النتائج، يجب تضمين الردود بالترتيب نفسه الذي تم طلبها به.

تتيح حزمة تطوير البرامج (SDK) الخاصة بلغة Python استدعاء الدوال تلقائيًا، ما يؤدي إلى تحويل دوال Python تلقائيًا إلى تعريفات، والتعامل مع دورة تنفيذ استدعاء الدالة والاستجابة نيابةً عنك. في ما يلي مثال على حالة استخدام الديسكو.

Python

from google import genai
from google.genai import types

# Actual function implementations
def power_disco_ball_impl(power: bool) -> dict:
    """Powers the spinning disco ball.

    Args:
        power: Whether to turn the disco ball on or off.

    Returns:
        A status dictionary indicating the current state.
    """
    return {"status": f"Disco ball powered {'on' if power else 'off'}"}

def start_music_impl(energetic: bool, loud: bool) -> dict:
    """Play some music matching the specified parameters.

    Args:
        energetic: Whether the music is energetic or not.
        loud: Whether the music is loud or not.

    Returns:
        A dictionary containing the music settings.
    """
    music_type = "energetic" if energetic else "chill"
    volume = "loud" if loud else "quiet"
    return {"music_type": music_type, "volume": volume}

def dim_lights_impl(brightness: float) -> dict:
    """Dim the lights.

    Args:
        brightness: The brightness of the lights, 0.0 is off, 1.0 is full.

    Returns:
        A dictionary containing the new brightness setting.
    """
    return {"brightness": brightness}

# Configure the client
client = genai.Client()
config = types.GenerateContentConfig(
    tools=[power_disco_ball_impl, start_music_impl, dim_lights_impl]
)

# Make the request
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Do everything you need to this place into party!",
    config=config,
)

print("\nExample 2: Automatic function calling")
print(response.text)
# I've turned on the disco ball, started playing loud and energetic music, and dimmed the lights to 50% brightness. Let's get this party started!

استدعاء الدوال التركيبية

تسمح ميزة "استدعاء الدوال التركيبي أو التسلسلي" لـ Gemini بربط عدة طلبات استدعاء دوال معًا لتلبية طلب معقّد. على سبيل المثال، للإجابة عن السؤال "ما هي درجة الحرارة في موقعي الجغرافي الحالي؟"، قد تستدعي Gemini API أولاً الدالة get_current_location() ثم الدالة get_weather() التي تأخذ الموقع الجغرافي كمعلَمة.

يوضّح المثال التالي كيفية تنفيذ استدعاء الدوال التركيبية باستخدام حزمة تطوير البرامج (SDK) الخاصة بلغة Python واستدعاء الدوال تلقائيًا.

Python

يستخدم هذا المثال ميزة استدعاء الدوال التلقائي في google-genai Python SDK. تحوّل حزمة تطوير البرامج (SDK) تلقائيًا دوال Python إلى المخطط المطلوب، وتنفّذ طلبات استدعاء الدوال عند طلب النموذج، وترسل النتائج مرة أخرى إلى النموذج لإكمال المهمة.

import os
from google import genai
from google.genai import types

# Example Functions
def get_weather_forecast(location: str) -> dict:
    """Gets the current weather temperature for a given location."""
    print(f"Tool Call: get_weather_forecast(location={location})")
    # TODO: Make API call
    print("Tool Response: {'temperature': 25, 'unit': 'celsius'}")
    return {"temperature": 25, "unit": "celsius"}  # Dummy response

def set_thermostat_temperature(temperature: int) -> dict:
    """Sets the thermostat to a desired temperature."""
    print(f"Tool Call: set_thermostat_temperature(temperature={temperature})")
    # TODO: Interact with a thermostat API
    print("Tool Response: {'status': 'success'}")
    return {"status": "success"}

# Configure the client and model
client = genai.Client()
config = types.GenerateContentConfig(
    tools=[get_weather_forecast, set_thermostat_temperature]
)

# Make the request
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.",
    config=config,
)

# Print the final, user-facing response
print(response.text)

الناتج المتوقّع

عند تشغيل الرمز، ستلاحظ أنّ حزمة SDK تنظّم عمليات استدعاء الدوال. يستدعي النموذج أولاً get_weather_forecast، ويتلقّى درجة الحرارة، ثم يستدعي set_thermostat_temperature بالقيمة الصحيحة استنادًا إلى المنطق الوارد في الطلب.

Tool Call: get_weather_forecast(location=London)
Tool Response: {'temperature': 25, 'unit': 'celsius'}
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: {'status': 'success'}
OK. I've set the thermostat to 20°C.

JavaScript

يوضّح هذا المثال كيفية استخدام حزمة تطوير البرامج (SDK) JavaScript/TypeScript لتنفيذ استدعاءات الدوال التركيبية باستخدام حلقة تنفيذ يدوية.

import { GoogleGenAI, Type } from "@google/genai";

// Configure the client
const ai = new GoogleGenAI({});

// Example Functions
function get_weather_forecast({ location }) {
  console.log(`Tool Call: get_weather_forecast(location=${location})`);
  // TODO: Make API call
  console.log("Tool Response: {'temperature': 25, 'unit': 'celsius'}");
  return { temperature: 25, unit: "celsius" };
}

function set_thermostat_temperature({ temperature }) {
  console.log(
    `Tool Call: set_thermostat_temperature(temperature=${temperature})`,
  );
  // TODO: Make API call
  console.log("Tool Response: {'status': 'success'}");
  return { status: "success" };
}

const toolFunctions = {
  get_weather_forecast,
  set_thermostat_temperature,
};

const tools = [
  {
    functionDeclarations: [
      {
        name: "get_weather_forecast",
        description:
          "Gets the current weather temperature for a given location.",
        parameters: {
          type: Type.OBJECT,
          properties: {
            location: {
              type: Type.STRING,
            },
          },
          required: ["location"],
        },
      },
      {
        name: "set_thermostat_temperature",
        description: "Sets the thermostat to a desired temperature.",
        parameters: {
          type: Type.OBJECT,
          properties: {
            temperature: {
              type: Type.NUMBER,
            },
          },
          required: ["temperature"],
        },
      },
    ],
  },
];

// Prompt for the model
let contents = [
  {
    role: "user",
    parts: [
      {
        text: "If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise set it to 18°C.",
      },
    ],
  },
];

// Loop until the model has no more function calls to make
while (true) {
  const result = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents,
    config: { tools },
  });

  if (result.functionCalls && result.functionCalls.length > 0) {
    const functionCall = result.functionCalls[0];

    const { name, args } = functionCall;

    if (!toolFunctions[name]) {
      throw new Error(`Unknown function call: ${name}`);
    }

    // Call the function and get the response.
    const toolResponse = toolFunctions[name](args);

    const functionResponsePart = {
      name: functionCall.name,
      response: {
        result: toolResponse,
      },
    };

    // Send the function response back to the model.
    contents.push({
      role: "model",
      parts: [
        {
          functionCall: functionCall,
        },
      ],
    });
    contents.push({
      role: "user",
      parts: [
        {
          functionResponse: functionResponsePart,
        },
      ],
    });
  } else {
    // No more function calls, break the loop.
    console.log(result.text);
    break;
  }
}

الناتج المتوقّع

عند تشغيل الرمز، ستلاحظ أنّ حزمة SDK تنظّم عمليات استدعاء الدوال. يستدعي النموذج أولاً get_weather_forecast، ويتلقّى درجة الحرارة، ثم يستدعي set_thermostat_temperature بالقيمة الصحيحة استنادًا إلى المنطق الوارد في الطلب.

Tool Call: get_weather_forecast(location=London)
Tool Response: {'temperature': 25, 'unit': 'celsius'}
Tool Call: set_thermostat_temperature(temperature=20)
Tool Response: {'status': 'success'}
OK. It's 25°C in London, so I've set the thermostat to 20°C.

استدعاء الدوال التركيبي هو إحدى الميزات الأصلية في Live API. وهذا يعني أنّ Live API يمكنه التعامل مع استدعاء الدوال بشكل مشابه لحزمة تطوير البرامج (SDK) الخاصة بلغة Python.

Python

# Light control schemas
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

JavaScript

// Light control schemas
const turnOnTheLightsSchema = { name: 'turn_on_the_lights' };
const turnOffTheLightsSchema = { name: 'turn_off_the_lights' };

const prompt = `
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
`;

const tools = [
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] }
];

await run(prompt, tools=tools, modality="AUDIO")

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

تتيح لك Gemini API التحكّم في طريقة استخدام النموذج للأدوات المقدَّمة (تعريفات الدوال). على وجه التحديد، يمكنك ضبط الوضع ضمن function_calling_config.

  • AUTO (Default): يقرّر النموذج ما إذا كان سيقدّم ردًا باللغة الطبيعية أو سيقترح طلب وظيفة استنادًا إلى الطلب والسياق. هذا الوضع هو الأكثر مرونة ويُنصح به في معظم السيناريوهات.
  • ANY: يكون النموذج مقيّدًا بالتوقّع دائمًا لاستدعاء دالة، ويضمن الالتزام بمخطط الدالة. إذا لم يتم تحديد allowed_function_names، يمكن للنموذج الاختيار من أي من تعريفات الدوال المقدَّمة. إذا تم تقديم allowed_function_names كقائمة، يمكن للنموذج الاختيار فقط من الدوال في تلك القائمة. استخدِم هذا الوضع عندما تحتاج إلى استجابة من دالة لكل طلب (إذا كان ذلك منطبقًا).
  • NONE: محظور على النموذج إجراء استدعاءات الدوال. وهذا الإجراء مكافئ لإرسال طلب بدون أي تعريفات للدوال. يمكنك استخدام هذه السمة لإيقاف ميزة "استدعاء الدوال" مؤقتًا بدون إزالة تعريفات الأدوات.

Python

from google.genai import types

# Configure function calling mode
tool_config = types.ToolConfig(
    function_calling_config=types.FunctionCallingConfig(
        mode="ANY", allowed_function_names=["get_current_temperature"]
    )
)

# Create the generation config
config = types.GenerateContentConfig(
    tools=[tools],  # not defined here.
    tool_config=tool_config,
)

JavaScript

import { FunctionCallingConfigMode } from '@google/genai';

// Configure function calling mode
const toolConfig = {
  functionCallingConfig: {
    mode: FunctionCallingConfigMode.ANY,
    allowedFunctionNames: ['get_current_temperature']
  }
};

// Create the generation config
const config = {
  tools: tools, // not defined here.
  toolConfig: toolConfig,
};

استدعاء الدوال تلقائيًا (في Python فقط)

عند استخدام حزمة تطوير البرامج (SDK) الخاصة بلغة Python، يمكنك تقديم دوال Python مباشرةً كأدوات. تحوّل حزمة SDK تلقائيًا دالة Python إلى تعريفات، وتتعامل مع تنفيذ طلب استدعاء الدالة ودورة الاستجابة نيابةً عنك. بعد ذلك، ينفّذ حزمة تطوير البرامج (SDK) الخاصة بلغة Python تلقائيًا ما يلي:

  1. يرصد هذا الإعداد الردود على استدعاء الدوال من النموذج.
  2. استدعِ دالة Python المناسبة في الرمز البرمجي.
  3. ترسل هذه السمة استجابة الدالة إلى النموذج.
  4. تعرض هذه السمة الردّ النصي النهائي للنموذج.

لاستخدام هذه الميزة، حدِّد الدالة باستخدام تلميحات الأنواع وسلسلة التوثيق، ثم مرِّر الدالة نفسها (وليس تعريف JSON) كأداة:

Python

from google import genai
from google.genai import types

# Define the function with type hints and docstring
def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

# Configure the client
client = genai.Client()
config = types.GenerateContentConfig(
    tools=[get_current_temperature]
)  # Pass the function itself

# Make the request
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What's the temperature in Boston?",
    config=config,
)

print(response.text)  # The SDK handles the function call and returns the final text

يمكنك إيقاف ميزة استدعاء الدوال التلقائي باستخدام:

Python

config = types.GenerateContentConfig(
    tools=[get_current_temperature],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

بيان مخطط الدالة التلقائي

لا يمكن استخراج المخطط تلقائيًا من دوال Python في بعض الحالات. على سبيل المثال، لا يمكنه التعامل مع الحالات التي تصف فيها حقول عنصر قاموس متداخل. يمكن لواجهة برمجة التطبيقات وصف أي من الأنواع التالية:

Python

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

للاطّلاع على شكل المخطط الاستنتاجي، يمكنك تحويله باستخدام from_callable:

Python

def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
print(fn_decl.to_json_dict())

استخدام أدوات متعددة: الجمع بين الأدوات الأصلية واستدعاء الدوال

يمكنك تفعيل أدوات متعددة تجمع بين الأدوات المضمّنة واستدعاء الدوال في الوقت نفسه. في ما يلي مثال يفعّل أداتَين، الاستناد إلى معلومات من "بحث Google" وتنفيذ الرمز البرمجي، في طلب باستخدام Live API.

Python

# Multiple tasks example - combining lights, code execution, and search
prompt = """
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
  """

tools = [
    {'google_search': {}},
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]} # not defined here.
]

# Execute the prompt with specified tools in audio modality
await run(prompt, tools=tools, modality="AUDIO")

JavaScript

// Multiple tasks example - combining lights, code execution, and search
const prompt = `
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
`;

const tools = [
  { googleSearch: {} },
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] } // not defined here.
];

// Execute the prompt with specified tools in audio modality
await run(prompt, {tools: tools, modality: "AUDIO"});

يمكن لمطوّري Python تجربة هذه الميزة في دفتر ملاحظات استخدام أداة Live API.

بروتوكول سياق النموذج (MCP)

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

تتضمّن حِزم تطوير البرامج (SDK) الخاصة بـ Gemini إمكانية استخدام أدوات MCP بشكل مباشر، ما يقلّل من الرموز النموذجية ويوفّر ميزة استدعاء الأدوات تلقائيًا لأدوات MCP. عندما ينشئ النموذج طلبًا لاستخدام أداة MCP، يمكن لحزمة تطوير البرامج (SDK) الخاصة بالعميل في Python وJavaScript تنفيذ أداة MCP تلقائيًا وإرسال الردّ إلى النموذج في طلب لاحق، مع مواصلة هذه العملية إلى أن يتوقف النموذج عن إرسال طلبات لاستخدام الأدوات.

يمكنك هنا الاطّلاع على مثال حول كيفية استخدام خادم MCP محلي مع Gemini وmcp SDK.

Python

تأكَّد من تثبيت أحدث إصدار من حزمة تطوير البرامج mcp على النظام الأساسي الذي تختاره.

pip install mcp
import os
import asyncio
from datetime import datetime
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai

client = genai.Client()

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="npx",  # Executable
    args=["-y", "@philschmid/weather-mcp"],  # MCP Server
    env=None,  # Optional environment variables
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Prompt to get the weather for the current day in London.
            prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"

            # Initialize the connection between client and server
            await session.initialize()

            # Send request to the model with MCP function declarations
            response = await client.aio.models.generate_content(
                model="gemini-2.5-flash",
                contents=prompt,
                config=genai.types.GenerateContentConfig(
                    temperature=0,
                    tools=[session],  # uses the session, will automatically call the tool
                    # Uncomment if you **don't** want the SDK to automatically call the tool
                    # automatic_function_calling=genai.types.AutomaticFunctionCallingConfig(
                    #     disable=True
                    # ),
                ),
            )
            print(response.text)

# Start the asyncio event loop and run the main function
asyncio.run(run())

JavaScript

تأكَّد من تثبيت أحدث إصدار من حزمة تطوير البرامج (SDK) mcp على المنصة التي تختارها.

npm install @modelcontextprotocol/sdk
import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai';
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create server parameters for stdio connection
const serverParams = new StdioClientTransport({
  command: "npx", // Executable
  args: ["-y", "@philschmid/weather-mcp"] // MCP Server
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

// Configure the client
const ai = new GoogleGenAI({});

// Initialize the connection between client and server
await client.connect(serverParams);

// Send request to the model with MCP tools
const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`,
  config: {
    tools: [mcpToTool(client)],  // uses the session, will automatically call the tool
    // Uncomment if you **don't** want the sdk to automatically call the tool
    // automaticFunctionCalling: {
    //   disable: true,
    // },
  },
});
console.log(response.text)

// Close the connection
await client.close();

القيود المفروضة على التوافق المضمّن مع منصّات إدارة الموافقة

تتوفّر ميزة دعم MCP المضمّنة تجريبيًا في حِزم SDK، وتخضع للقيود التالية:

  • لا تتوفّر سوى الأدوات، وليس المراجع أو الطلبات
  • وهي متاحة لحزمة تطوير البرامج (SDK) الخاصة بلغة Python وJavaScript/TypeScript.
  • قد تحدث تغييرات غير متوافقة مع الإصدارات السابقة في الإصدارات المستقبلية.

يمكنك دائمًا دمج خوادم MCP يدويًا إذا كانت هذه الخوادم تفرض قيودًا على ما تنوي إنشاءه.

النماذج المتوافقة

يسرد هذا القسم النماذج وإمكاناتها في استدعاء الدوال. ولا يتم تضمين النماذج التجريبية. يمكنك الاطّلاع على نظرة عامة شاملة حول الإمكانات في صفحة نظرة عامة على النموذج.

الطراز استدعاء الدوال استدعاء الدوال بشكل متوازٍ استدعاء الدوال التركيبية
Gemini 2.5 Pro ✔️ ✔️ ✔️
‫Gemini 2.5 Flash ✔️ ✔️ ✔️
Gemini 2.5 Flash-Lite ✔️ ✔️ ✔️
‫Gemini 2.0 Flash ✔️ ✔️ ✔️
‫Gemini 2.0 Flash-Lite X X X

أفضل الممارسات

  • أوصاف الدوال والمَعلمات: يجب أن تكون أوصافك واضحة ومحدّدة للغاية. ويعتمد النموذج على هذه المعلومات لاختيار الدالة الصحيحة وتقديم الوسيطات المناسبة.
  • التسمية: استخدِم أسماء دوال وصفية (بدون مسافات أو نقاط أو شرطات).
  • الكتابة القوية: استخدِم أنواعًا محدّدة (عدد صحيح، سلسلة، تعداد) للمَعلمات للحدّ من الأخطاء. إذا كانت إحدى المَعلمات تتضمّن مجموعة محدودة من القيم الصالحة، استخدِم نوع البيانات enum.
  • اختيار الأدوات: على الرغم من أنّ النموذج يمكنه استخدام عدد غير محدود من الأدوات، فإنّ توفير عدد كبير جدًا منها قد يزيد من خطر اختيار أداة غير صحيحة أو غير مثالية. للحصول على أفضل النتائج، احرص على توفير الأدوات ذات الصلة فقط بالسياق أو المهمة، مع الحفاظ على المجموعة النشطة عند 10 إلى 20 أداة كحد أقصى. ننصحك باختيار الأدوات بشكل ديناميكي استنادًا إلى سياق المحادثة إذا كان لديك عدد كبير من الأدوات.
  • هندسة الطلبات:
    • توفير سياق: أخبر النموذج بدوره (مثلاً "أنت مساعد مفيد بشأن الطقس").
    • تقديم التعليمات: حدِّد كيفية استخدام الدوال ومتى يجب استخدامها (مثلاً لا تخمّن التواريخ، بل استخدِم دائمًا تاريخًا مستقبليًا للتوقّعات").
    • تشجيع التوضيح: اطلب من النموذج طرح أسئلة توضيحية إذا لزم الأمر.
  • درجة الحرارة: استخدِم درجة حرارة منخفضة (مثل ‫0) لإجراء عمليات استدعاء للدوال أكثر تحديدًا وموثوقية.
  • التحقّق من الصحة: إذا كان لطلب تنفيذ دالة عواقب كبيرة (مثل تقديم طلب)، يجب التحقّق من صحة الطلب مع المستخدم قبل تنفيذه.
  • التعامل مع الأخطاء: عليك تنفيذ عملية التعامل مع الأخطاء بشكل فعّال في الدوال للتعامل مع الإدخالات غير المتوقّعة أو حالات تعذُّر الوصول إلى واجهة برمجة التطبيقات. عرض رسائل خطأ مفيدة يمكن للنموذج استخدامها لإنشاء ردود مفيدة للمستخدم.
  • الأمان: يُرجى مراعاة الأمان عند استدعاء واجهات برمجة التطبيقات الخارجية. استخدام آليات المصادقة والتفويض المناسبة تجنَّب عرض البيانات الحسّاسة في استدعاءات الدوال.
  • حدود الرموز المميزة: يتم احتساب أوصاف الدوال ومعلَماتها ضمن الحد الأقصى لعدد الرموز المميزة التي يمكنك إدخالها. إذا كنت تواجه مشاكل بسبب الحد الأقصى لعدد الرموز المميزة، ننصحك بالحد من عدد الدوال أو طول الأوصاف، أو بتقسيم المهام المعقّدة إلى مجموعات دوال أصغر وأكثر تركيزًا.

الملاحظات والقيود

  • يتوافق هذا التنسيق مع مجموعة فرعية من مخطط OpenAPI فقط.
  • أنواع المَعلمات المتوافقة في Python محدودة.
  • لا تتوفّر ميزة استدعاء الدوال تلقائيًا إلا في حزمة تطوير البرامج (SDK) الخاصة بلغة Python.