Streaming: Ricevi le risposte in tempo reale
In questa pagina
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=Trueper un’esperienza in tempo reale - Filtra gli eventi per
event.typeper gestire correttamente ogni tipo di dato response.output_text.deltacontiene i frammenti di testoresponse.completedsegnala la fine e include le metriche di utilizzo- Usa
AsyncOpenAIper lo streaming nelle applicazioni asincrone - Gestisci sempre gli errori, anche in modalità streaming