Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Streaming: Ricevi le risposte in tempo reale

Lezione 8 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Streaming: Ricevi le risposte in tempo reale
  2. Perché usare lo streaming
  3. Eventi tipizzati, non un flusso indifferenziato
  4. Streaming e chiamata di funzioni
  5. Il caso asincrono
  6. Errori a metà flusso
  7. Punti chiave

Streaming: Ricevi le risposte in tempo reale

Lo streaming ti permette di ricevere la risposta token per token invece di attendere il completamento dell’intera generazione. Non si tratta solo di un abbellimento dell’interfaccia: è ciò che distingue un chatbot che sembra lento da uno che sembra scattante, anche quando le prestazioni del server sono identiche.

Perché usare lo streaming

Senza streaming, gli utenti a volte fissano uno schermo vuoto per dieci o trenta secondi prima che l’intera risposta appaia tutta insieme. Con lo streaming, le prime parole compaiono in meno di un secondo e la lettura inizia mentre la generazione prosegue. La durata totale è la stessa; la percezione no. Abilitarlo richiede un solo parametro, stream=True, che trasforma il valore di ritorno di create() in un iteratore di eventi.

from openai import OpenAI
client = OpenAI()

# SENZA streaming — attendi tutto
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a paragraph about artificial intelligence."
)
print(response.output_text)  # Appare tutto insieme dopo l'attesa

# CON streaming — token per token
stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a paragraph about artificial intelligence.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()  # Nuova riga alla fine

Eventi tipizzati, non un flusso indifferenziato

Il flusso non trasporta solo testo. Ti notifica quando la risposta viene creata, quando ogni elemento di output viene aggiunto, quando arrivano i frammenti e quando si verifica il completamento: l’evento finale include le metriche di utilizzo. Filtri in base a event.type per sapere cosa stai gestendo. Questa struttura ti permette, ad esempio, di visualizzare un indicatore di caricamento non appena viene attivato response.created e di conteggiare i token alla fine senza una seconda chiamata API.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Hello!",
    stream=True
)

for event in stream:
    match event.type:
        case "response.created":
            print(f"[Response created] ID: {event.response.id}")
        case "response.output_item.added":
            print(f"[New output item]")
        case "response.output_text.delta":
            print(f"[Text] {event.delta}", end="")
        case "response.output_text.done":
            print(f"\n[Text complete]")
        case "response.completed":
            print(f"[Done] Tokens: {event.response.usage.total_tokens}")

# Output:
# [Response created] ID: resp_abc123
# [New output item]
# [Text] Hello[Text] ! [Text] How[Text] can[Text] I...
# [Text complete]
# [Done] Tokens: 25

In un’applicazione reale, vorrai quasi sempre fare due cose contemporaneamente: visualizzare i frammenti e ricostruire il testo completo per poterlo archiviare o restituirlo al chiamante. La regola è semplice: accumula mentre iteri, perché una volta consumato il flusso, non può essere riavvolto.

def stream_and_collect(prompt: str) -> str:
    """Esegue lo streaming della risposta raccogliendola contemporaneamente."""
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True
    )

    full_text = ""
    for event in stream:
        if event.type == "response.output_text.delta":
            full_text += event.delta
            print(event.delta, end="", flush=True)

    print()  # Nuova riga
    return full_text

result = stream_and_collect("List 3 European capitals.")
print(f"\nCollected text ({len(result)} characters)")

Streaming e chiamata di funzioni

Anche le chiamate di funzione vengono trasmesse in streaming, con i propri eventi: gli argomenti arrivano in frammenti tramite response.function_call_arguments.delta, e response.function_call_arguments.done segnala che il JSON è completo. Questo ha un’importante conseguenza pratica: non tentare mai di deserializzare gli argomenti prima dell’evento done, altrimenti avrai solo un JSON troncato.

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="What time is it in Tokyo?",
    tools=[{
        "type": "function",
        "name": "get_time",
        "description": "Get the time in a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }],
    stream=True
)

for event in stream:
    match event.type:
        case "response.output_text.delta":
            print(event.delta, end="")
        case "response.function_call_arguments.delta":
            print(f"[Args] {event.delta}", end="")
        case "response.function_call_arguments.done":
            print(f"\n[Function call complete]")

# Output:
# [Args] {"city": "Tokyo"}
# [Function call complete]

Il caso asincrono

Non appena la tua applicazione serve più utenti contemporaneamente, passa ad AsyncOpenAI: il client sincrono bloccherebbe il loop degli eventi per l’intera generazione, costringendo le altre richieste ad attendere. La sintassi differisce solo per due parole chiave: await sulla creazione e async for sull’iterazione.

from openai import AsyncOpenAI
import asyncio

async_client = AsyncOpenAI()

async def stream_async(prompt: str):
    """Streaming asincrono della risposta."""
    stream = await async_client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        stream=True
    )

    async for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    print()

asyncio.run(stream_async("Tell a short joke."))

Sul web, lo streaming è inutile se si ferma al tuo server: devi estenderlo al browser. FastAPI lo abilita con StreamingResponse, alimentato da un generatore che inoltra i frammenti man mano che arrivano.

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from openai import OpenAI

app = FastAPI()
client = OpenAI()

@app.get("/chat")
async def chat(question: str):
    def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=question,
            stream=True
        )
        for event in stream:
            if event.type == "response.output_text.delta":
                yield event.delta

    return StreamingResponse(generate(), media_type="text/plain")

Errori a metà flusso

Un dettaglio merita la tua attenzione: nello streaming, un errore può verificarsi dopo che alcuni frammenti sono già stati visualizzati. L’utente vede quindi una risposta che inizia ma viene interrotta. Pertanto, avvolgi l’iterazione stessa, non solo la creazione del flusso, in modo da poter segnalare pulitamente l’interruzione invece di lasciare una frase a metà.

from openai import APIError

def stream_with_errors(prompt: str):
    """Streaming con gestione robusta degli errori."""
    try:
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt,
            stream=True
        )

        for event in stream:
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)
        print()

    except APIError as e:
        print(f"\nAPI error during streaming: {e.message}")
    except Exception as e:
        print(f"\nUnexpected error: {e}")

stream_with_errors("Explain streaming in 2 sentences.")

Punti chiave

  • Abilita lo streaming con stream=True per un’esperienza in tempo reale
  • Filtra gli eventi per event.type per gestire correttamente ogni tipo di dato
  • response.output_text.delta contiene i frammenti di testo
  • response.completed segnala la fine e include le metriche di utilizzo
  • Usa AsyncOpenAI per lo streaming nelle applicazioni asincrone
  • Gestisci sempre gli errori, anche in modalità streaming