Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Streaming e Strumenti

Lezione 9 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Streaming con Function Calling
  2. La Regola Fondamentale
  3. Implementare lo Streaming con gli Strumenti
  4. Ricostruire le Chiamate di Strumento nello Streaming
  5. Architettura per lo Streaming con Strumenti
  6. Latenza ed Esperienza Utente
  7. Server-Sent Events (SSE) per Applicazioni Web
  8. Punti chiave

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:

  1. Visualizzazione in tempo reale: mostra il testo man mano che arriva
  2. 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:

  1. L’utente pone la sua domanda
  2. Il modello inizia a pensare (nessun token visibile)
  3. Il modello decide di chiamare uno strumento (ricevi la tool_call)
  4. Pausa — esegui la funzione
  5. Invii il risultato
  6. 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