La chiamata di funzione ti consente di definire funzioni personalizzate e fornire agli LLM la capacità di chiamarle per recuperare informazioni in tempo reale o interagire con sistemi esterni come database SQL o strumenti di assistenza clienti.
Per maggiori informazioni concettuali sulla chiamata di funzione, consulta Introduzione alla chiamata di funzione.
Utilizzare la chiamata di funzione
Gli esempi riportati di seguito mostrano come utilizzare la chiamata di funzioni.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.
Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL.
Per ulteriori informazioni, vedi Autenticazione e credenziali.
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: il nome del modello che vuoi utilizzare,
ad esempio
qwen/qwen3-next-80b-a3b-instruct-maas. - CONTENT: Il prompt dell'utente da inviare al modello.
- FUNCTION_NAME: il nome della funzione da chiamare.
- FUNCTION_DESCRIPTION: una descrizione della funzione.
- PARAMETERS_OBJECT: un dizionario che definisce i parametri della funzione, ad esempio:
{"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}
REST
Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. Il seguente esempio invia una richiesta all'endpoint del modello del publisher.
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
- LOCATION: una regione che supporta modelli aperti.
- MODEL: il nome del modello che vuoi utilizzare,
ad esempio
qwen/qwen3-next-80b-a3b-instruct-maas. - CONTENT: Il prompt dell'utente da inviare al modello.
- FUNCTION_NAME: il nome della funzione da chiamare.
- FUNCTION_DESCRIPTION: una descrizione della funzione.
- PARAMETERS_OBJECT: un oggetto schema JSON che definisce i parametri della funzione, ad esempio:
{"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
Corpo JSON della richiesta:
{
"model": "MODEL",
"messages": [
{
"role": "user",
"content": "CONTENT"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "FUNCTION_NAME",
"description": "FUNCTION_DESCRIPTION",
"parameters": PARAMETERS_OBJECT
}
}
],
"tool_choice": "auto"
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
ed esegui questo comando:
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
Salva il corpo della richiesta in un file denominato request.json,
ed esegui questo comando:
$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
Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.
Esempio
Di seguito è riportato l'output completo che potresti ottenere dopo aver utilizzato la funzione
get_current_weather per recuperare informazioni meteorologiche.
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" }'
{ "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 } }
Indicazioni specifiche per il modello
Le sezioni seguenti forniscono indicazioni specifiche per modello per la chiamata di funzioni.
DeepSeek
I modelli DeepSeek non funzionano altrettanto bene con la chiamata di funzioni se utilizzi un prompt di sistema. Per prestazioni ottimali, ometti il prompt di sistema quando utilizzi la chiamata di funzione con i modelli DeepSeek.
Llama
meta/llama3-405b-instruct-maas non supporta tool_choice = 'required'.
OpenAI
Quando utilizzi openai/gpt-oss-120b-instruct-maas e
openai/gpt-oss-20b-instruct-maas, inserisci le definizioni degli strumenti nel
prompt di sistema per prestazioni ottimali. Ad esempio:
{"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?"}, ... ]}
Questi modelli non supportano tool_choice = 'required' o la chiamata di strumenti denominati.
Qwen
I modelli Qwen funzionano meglio quando tool_choice è impostato esplicitamente su auto o
none. Se tool_choice non è impostato, il modello potrebbe non funzionare
correttamente.
Passaggi successivi
- Scopri di più sull'output strutturato.
- Scopri di più su Pensiero.
- Scopri di più sulle previsioni batch.