Streaming e Strumenti
In questa pagina
Streaming con Function Calling
Lo streaming ti permette di ricevere la risposta del modello incrementalmente, token per token. Questo è essenziale per interfacce utente reattive. Ma come interagisce lo streaming con le chiamate di funzione?
La Regola Fondamentale
Le chiamate di funzione vengono restituite in un unico blocco, non trasmesse progressivamente. Questa è una differenza fondamentale rispetto al testo normale, che arriva token per token.
In pratica:
- Il testo della risposta viene trasmesso progressivamente
- Le tool_calls arrivano tutte insieme in un singolo evento
Questo vincolo esiste per un buon motivo: una chiamata di strumento deve essere completa (nome + argomenti JSON validi) per poter essere eseguita. Un JSON parziale sarebbe inutilizzabile.
Implementare lo Streaming con gli Strumenti
stream = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
stream=True
)
collected_tool_calls = []
collected_content = ""
for chunk in stream:
delta = chunk.choices[0].delta
# Testo in streaming
if delta.content:
collected_content += delta.content
print(delta.content, end="", flush=True)
# Chiamate di strumento (arrivano in un unico blocco)
if delta.tool_calls:
for tc in delta.tool_calls:
collected_tool_calls.append(tc)
# Controllo della fine dello stream
if chunk.choices[0].finish_reason == "tool_calls":
# Il modello si aspetta risultati dagli strumenti
break
elif chunk.choices[0].finish_reason == "stop":
# Risposta terminata, nessuno strumento chiamato
break
Ricostruire le Chiamate di Strumento nello Streaming
In alcuni casi, gli argomenti della chiamata di strumento possono arrivare in più frammenti all’interno dello stream. Devi ricostruirli:
tool_calls_buffer = {}
for chunk in stream:
delta = chunk.choices[0].delta
if delta.tool_calls:
for tc_chunk in delta.tool_calls:
idx = tc_chunk.index
if idx not in tool_calls_buffer:
tool_calls_buffer[idx] = {
"id": tc_chunk.id,
"function": {
"name": tc_chunk.function.name or "",
"arguments": ""
}
}
if tc_chunk.function.name:
tool_calls_buffer[idx]["function"]["name"] = tc_chunk.function.name
if tc_chunk.function.arguments:
tool_calls_buffer[idx]["function"]["arguments"] += tc_chunk.function.arguments
Questo approccio di buffering garantisce che tu ricostruisca correttamente ogni chiamata di strumento, anche se i dati arrivano frammentati.
Architettura per lo Streaming con Strumenti
In un’applicazione reale, devi gestire due flussi simultanei:
- Visualizzazione in tempo reale: mostra il testo man mano che arriva
- Accumulo delle chiamate di strumento: raccogli le chiamate per l’esecuzione
async def handle_streaming_response(stream):
content_parts = []
tool_calls = []
current_tool = None
async for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
content_parts.append(delta.content)
yield {"type": "text", "data": delta.content}
if delta.tool_calls:
for tc in delta.tool_calls:
tool_calls.append(tc)
if chunk.choices[0].finish_reason == "tool_calls":
# Esegui gli strumenti e riavvia
results = await execute_tools(tool_calls)
yield {"type": "tool_results", "data": results}
Latenza ed Esperienza Utente
Lo streaming con gli strumenti comporta pause naturali nel flusso:
- L’utente pone la sua domanda
- Il modello inizia a pensare (nessun token visibile)
- Il modello decide di chiamare uno strumento (ricevi la tool_call)
- Pausa — esegui la funzione
- Invii il risultato
- Il modello genera la sua risposta (trasmessa progressivamente)
Per l’esperienza utente, visualizza un indicatore durante il passaggio 4:
🔍 Ricerca del meteo a Parigi in corso...
Questo impedisce all’utente di pensare che l’applicazione si sia bloccata.
Server-Sent Events (SSE) per Applicazioni Web
Se stai costruendo un’API web, usa gli SSE per inoltrare lo stream:
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
@app.get("/chat")
async def chat(message: str):
async def event_stream():
stream = client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": message}],
tools=tools,
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
yield f"data: {chunk.choices[0].delta.content}\n\n"
return StreamingResponse(event_stream(), media_type="text/event-stream")
Punti chiave
- Le chiamate di strumento arrivano in un unico blocco, non trasmesse progressivamente
- Il testo normale continua a essere trasmesso token per token
- Ricostruisci le chiamate di strumento frammentate con un buffer indicizzato per
index - Gestisci due flussi in parallelo: visualizzazione del testo + raccolta delle chiamate di strumento
- Visualizza un indicatore durante l’esecuzione dello strumento per migliorare l’UX
- Usa gli SSE per le applicazioni web