בקשה להפעלת פונקציה במודלים פתוחים

בקשה להפעלת פונקציה מאפשרת לכם להגדיר פונקציות מותאמות אישית ולספק למודלים גדולים של שפה את היכולת להפעיל אותן כדי לאחזר מידע בזמן אמת או לקיים אינטראקציה עם מערכות חיצוניות כמו מסדי נתונים של SQL או כלים לשירות לקוחות.

מידע נוסף על קריאה לפונקציות זמין במאמר מבוא לקריאה לפונקציות.

שימוש בבקשה להפעלת פונקציה

בדוגמאות הבאות אפשר לראות איך משתמשים בהפעלת פונקציות.

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר מדריך למתחילים של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

לפני שמריצים את הדוגמה הזו, צריך להגדיר את משתנה הסביבה OPENAI_BASE_URL. למידע נוסף, ראו אימות ופרטי כניסה.

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="MODEL",
  messages=[
    {"role": "user", "content": "CONTENT"}
  ],
  tools=[
    {
      "type": "function",
      "function": {
        "name": "FUNCTION_NAME",
        "description": "FUNCTION_DESCRIPTION",
        "parameters": PARAMETERS_OBJECT,
      }
    }
  ],
  tool_choice="auto",
)

• ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה qwen/qwen3-next-80b-a3b-instruct-maas.
• ‫CONTENT: ההנחיה למשתמש שנשלחת למודל.
• ‫FUNCTION_NAME: השם של הפונקציה שרוצים להפעיל.
• ‫FUNCTION_DESCRIPTION: תיאור הפונקציה.
• ‫PARAMETERS_OBJECT: מילון שמגדיר את הפרמטרים של הפונקציה, לדוגמה:
  {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• PROJECT_ID: מזהה הפרויקט ב-Google Cloud.
• ‫LOCATION: אזור שתומך במודלים פתוחים.
• ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה qwen/qwen3-next-80b-a3b-instruct-maas.
• ‫CONTENT: ההנחיה למשתמש שנשלחת למודל.
• ‫FUNCTION_NAME: השם של הפונקציה שרוצים להפעיל.
• ‫FUNCTION_DESCRIPTION: תיאור הפונקציה.
• ‫PARAMETERS_OBJECT: אובייקט סכימת JSON שמגדיר את הפרמטרים של הפונקציה, לדוגמה:
  {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

ה-method של ה-HTTP וכתובת ה-URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

גוף בקשת JSON:

{
  "model": "MODEL",
  "messages": [
    {
      "role": "user",
      "content": "CONTENT"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "FUNCTION_NAME",
        "description": "FUNCTION_DESCRIPTION",
        "parameters": PARAMETERS_OBJECT
      }
    }
  ],
  "tool_choice": "auto"
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

אמורים לקבל קוד סטטוס של הצלחה (2xx) ותגובה ריקה.

דוגמה

בהמשך מוצג הפלט המלא שאפשר לצפות לו אחרי שימוש בפונקציה get_current_weather כדי לאחזר מידע מטאורולוגי.

Python

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="qwen/qwen3-next-80b-a3b-instruct-maas",
  messages=[
    {
      "role": "user",
      "content": "Which city has a higher temperature, Boston or new Delhi and by how much in F?"
    },
    {
      "role": "assistant",
      "content": "I'll check the current temperatures for Boston and New Delhi in Fahrenheit and compare them. I'll call the weather function for both cities.",
      "tool_calls": [{"function":{"arguments":"{\"location\":\"Boston, MA\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"},{"function":{"arguments":"{\"location\":\"New Delhi, India\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"}]
    },
    {
      "role": "tool",
      "content": "The temperature in Boston is 75 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    },
    {
      "role": "tool",
      "content": "The temperature in New Delhi is 50 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    }
  ],
  tools=[
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  tool_choice="auto"
)

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/sample-project/locations/us-central1/endpoints/openapi/chat/completions -d \
'{
  "model": "qwen/qwen3-next-80b-a3b-instruct-maas",
  "messages": [
    {
      "role": "user",
      "content": "Which city has a higher temperature, Boston or new Delhi and by how much in F?"
    },
    {
      "role": "assistant",
      "content": "I'll check the current temperatures for Boston and New Delhi in Fahrenheit and compare them. I'll call the weather function for both cities.",
      "tool_calls": [{"function":{"arguments":"{\"location\":\"Boston, MA\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"},{"function":{"arguments":"{\"location\":\"New Delhi, India\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"}]
    },
    {
      "role": "tool",
      "content": "The temperature in Boston is 75 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    },
    {
      "role": "tool",
      "content": "The temperature in New Delhi is 50 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

אחרי קבלת המידע שאוחזר באמצעות קריאה לפונקציה החיצונית `get_current_weather`, המודל יכול לסנתז את המידע משתי התגובות של הכלי ולענות על השאלה של המשתמש. הנה דוגמה לאופן שבו פלט המודל יכול להיראות:

{
 "choices": [
  {
   "finish_reason": "stop",
   "index": 0,
   "logprobs": null,
   "message": {
    "content": "Based on the current weather data:\n\n- **Boston, MA**: 75°F
    \n- **New Delhi, India**: 50°F  \n\n**Comparison**:
    \nBoston is **25°F warmer** than New Delhi.  \n\n**Answer**:
    \nBoston has a higher temperature than New Delhi by 25 degrees Fahrenheit.",
    "role": "assistant"
   }
  }
 ],
 "created": 1750450289,
 "id": "2025-06-20|13:11:29.240295-07|6.230.75.101|-987540014",
 "model": "qwen/qwen3-next-80b-a3b-instruct-maas",
 "object": "chat.completion",
 "system_fingerprint": "",
 "usage": {
  "completion_tokens": 66,
  "prompt_tokens": 217,
  "total_tokens": 283
 }
}

הנחיות ספציפיות למודל

בקטעים הבאים מפורטות הנחיות ספציפיות למודלים לגבי קריאה לפונקציות.

DeepSeek

מודלים של DeepSeek לא פועלים טוב כמו מודלים אחרים בקריאה לפונקציות אם משתמשים בהנחיית מערכת. כדי להשיג ביצועים אופטימליים, כשמשתמשים בקריאות לפונקציות עם מודלים של DeepSeek, צריך להשמיט את הנחיית המערכת.

Llama

התצוגה של meta/llama3-405b-instruct-maas לא תומכת ברזולוציה tool_choice = 'required'.

OpenAI

כשמשתמשים ב-openai/gpt-oss-120b-instruct-maas וב-openai/gpt-oss-20b-instruct-maas, מומלץ למקם את הגדרות הכלים בהנחיית המערכת כדי לקבל ביצועים אופטימליים. לדוגמה:

{"messages": [
    {"role": "system", "content": "You are a helpful assistant with access to the following functions. Use them if required:\n..."},
    {"role": "user", "content": "What's the weather like in Boston?"},
    ...
]}

המודלים האלה לא תומכים ב-tool_choice = 'required' או בהפעלת כלים עם שמות.

Qwen

המודלים של Qwen מניבים את הביצועים הכי טובים כשמגדירים במפורש את tool_choice לערך auto או לערך none. אם המדיניות tool_choice לא מוגדרת, יכול להיות שהמודל לא יפעל בצורה טובה.

המאמרים הבאים

• מידע נוסף על פלט מובנה
• מידע נוסף על Thinking
• מידע על חיזויים רבים בבת אחת