Chiamate parallele
In questa pagina
Più strumenti in una singola risposta
Una delle funzionalità più potenti delle chiamate di funzione di Grok è la capacità di restituire più chiamate di strumenti in un’unica risposta. Invece di effettuare un round trip per ogni funzione, il modello identifica tutte le informazioni necessarie e genera ogni chiamata in parallelo.
Il parametro parallel_tool_calls
Le chiamate parallele sono abilitate per impostazione predefinita. Il parametro parallel_tool_calls controlla questo comportamento:
# Abilitato per impostazione predefinita (nessuna necessità di specificarlo)
response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
parallel_tool_calls=True # Questo è il valore predefinito
)
Quando un utente chiede: «Qual è il meteo a Parigi e Lione?», il modello restituisce due tool_calls nella stessa risposta:
{
"tool_calls": [
{
"id": "call_001",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"Paris\"}"
}
},
{
"id": "call_002",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"Lyon\"}"
}
}
]
}
Gestione delle chiamate parallele
Il tuo codice deve gestire un array di tool_calls, non solo uno:
import json
import asyncio
message = response.choices[0].message
if message.tool_calls:
# Esegui tutte le funzioni
tool_results = []
for tool_call in message.tool_calls:
args = json.loads(tool_call.function.arguments)
result = execute_function(tool_call.function.name, args)
tool_results.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(result)
})
# Invia TUTTI i risultati al modello
messages = [
{"role": "user", "content": "Qual è il meteo a Parigi e Lione?"},
message,
*tool_results # Tutti i risultati
]
final = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
Punto critico: devi restituire tutti i risultati degli strumenti, non solo il primo. Ogni risultato è collegato al suo corrispondente tool_call_id.
Vera esecuzione parallela sul client
Il modello restituisce le chiamate in parallelo, ma il tuo codice deve eseguirle in parallelo. In Python, usa asyncio o concurrent.futures:
import concurrent.futures
def execute_parallel(tool_calls):
results = []
with concurrent.futures.ThreadPoolExecutor() as executor:
futures = {}
for tc in tool_calls:
args = json.loads(tc.function.arguments)
future = executor.submit(execute_function, tc.function.name, args)
futures[future] = tc.id
for future in concurrent.futures.as_completed(futures):
call_id = futures[future]
result = future.result()
results.append({
"role": "tool",
"tool_call_id": call_id,
"content": json.dumps(result)
})
return results
L’esecuzione parallela riduce significativamente la latenza totale. Se ogni chiamata API richiede 200 ms, due chiamate sequenziali equivalgono a 400 ms, mentre due chiamate parallele richiedono circa 200 ms.
Disabilitazione delle chiamate parallele
In alcuni casi, vorrai chiamate sequenziali:
response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
parallel_tool_calls=False
)
Disabilita il parallelismo ogni volta che l’indipendenza delle chiamate non è garantita. Il caso più evidente è la dipendenza dai dati: se il risultato di uno strumento alimenta gli argomenti del successivo, come cercare un ID cliente prima di recuperare i suoi ordini, l’esecuzione in parallelo causerà al meglio un errore e, nel peggiore dei casi, produrrà un risultato errato in modo silenzioso. L’ordine della logica di business impone lo stesso vincolo: creare un utente prima di assegnargli un ruolo è imprescindibile e solo la modalità sequenziale lo garantisce. Due motivi pratici completano il quadro: un’API esterna soggetta a limiti di richieste concorrenti non gestirà bene un’esplosione di chiamate parallele e, durante lo sviluppo, la modalità sequenziale rende il tracciamento delle chiamate infinitamente più leggibile: una chiamata, un risultato, un log, in ordine.
Chiamate parallele con strumenti diversi
Il modello può anche chiamare strumenti diversi in parallelo:
# Richiesta: "Prenota un tavolo e dimmi il meteo per stasera"
# Il modello restituisce:
# - tool_call_1 : book_table(restaurant="Le Petit Bistrot", time="20:00")
# - tool_call_2 : get_weather(city="Paris", time="tonight")
Questo è particolarmente utile per assistenti versatili che devono raccogliere informazioni da fonti diverse.
Gestione degli errori in parallelo
Quando una chiamata fallisce ma altre hanno successo, restituisci comunque tutti i risultati. Il modello gestisce i singoli errori:
results = []
for tc in message.tool_calls:
try:
result = execute_function(tc.function.name, args)
results.append({
"role": "tool",
"tool_call_id": tc.id,
"content": json.dumps(result)
})
except Exception as e:
results.append({
"role": "tool",
"tool_call_id": tc.id,
"content": json.dumps({"error": str(e)})
})
Punti chiave
- Le chiamate parallele sono abilitate per impostazione predefinita (
parallel_tool_calls: true) - Il modello restituisce più
tool_callsin un’unica risposta - Devi restituire tutti i risultati, ciascuno collegato al suo
tool_call_id - Implementa l’esecuzione parallela lato client per ridurre la latenza
- Disabilita il parallelismo quando esistono dipendenze tra le chiamate
- Gestisci gli errori individualmente: non bloccare tutto per un singolo fallimento