Streaming SSE
In questa pagina
Ricevi le risposte in tempo reale
Di default, l’API attende che la risposta sia stata generata interamente prima di restituirla. Con lo streaming, ricevi i token man mano che vengono generati. Questa tecnica riduce l’attesa percepita dall’utente e ti permette di visualizzare le risposte progressivamente, esattamente come fa l’interfaccia di Grok.
Come funziona lo streaming
Lo streaming utilizza il protocollo Server-Sent Events (SSE). Invece di una singola risposta HTTP, il server invia un flusso continuo di eventi. Ogni evento contiene un frammento della risposta e il client li assembla per ricostruire il testo completo.
Il parametro stream: true attiva questa modalità per qualsiasi endpoint di generazione.
Streaming in Python con l’SDK OpenAI
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
stream = client.chat.completions.create(
model="grok-4.5",
messages=[
{"role": "user", "content": "Explain the SOLID principles in programming."}
],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print() # Final line break
Come funziona il codice
stream=Trueattiva lo streaming- La risposta è un iteratore di oggetti
chunk(frammenti) - Ogni chunk contiene un
deltacon il nuovo contenuto end=""evita le interruzioni di riga tra i frammentiflush=Trueforza la visualizzazione immediata
Streaming con l’endpoint /v1/responses
stream = client.responses.create(
model="grok-4.5",
input="Describe the steps to deploy a web application.",
stream=True
)
for event in stream:
if hasattr(event, 'type') and event.type == 'response.output_text.delta':
print(event.delta, end="", flush=True)
print()
L’endpoint /v1/responses utilizza eventi tipizzati. Il tipo response.output_text.delta contiene i frammenti di testo.
Streaming con cURL
cURL supporta nativamente lo streaming SSE. Aggiungi "stream": true al corpo della richiesta:
curl -N https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.5",
"messages": [{"role": "user", "content": "Hello"}],
"stream": true
}'
L’opzione -N disattiva il buffering di cURL, così gli eventi vengono visualizzati non appena arrivano.
Ogni riga del flusso SSE inizia con data: seguito da un oggetto JSON. L’ultimo evento è data: [DONE], che segnala la fine della generazione.
Quando usare lo streaming
La decisione si riduce a una domanda: c’è una persona che guarda la risposta mentre arriva? Se sì (un chatbot, un assistente, uno strumento di scrittura), lo streaming è quasi obbligatorio: gli utenti vedono il testo apparire parola per parola invece di fissare uno schermo bloccato e, per una risposta lunga, la differenza tra «prima parola in 300 ms» e «tutto il testo dopo 8 secondi» cambia completamente l’esperienza percepita.
Se nessuno sta guardando, lo streaming non aggiunge nulla e complica il codice. Un job batch che popola un database, una pipeline automatizzata che deve analizzare la risposta completa prima di agire, una chiamata che restituisce solo poche parole: in tutti questi casi, la chiamata classica (una richiesta, una risposta completa) rimane più semplice da scrivere, testare ed eseguire il debug.
Gestione degli errori nello streaming
In modalità streaming, gli errori possono verificarsi nel mezzo del flusso. Il tuo codice deve gestire queste interruzioni:
try:
stream = client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": "Test"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
except Exception as e:
print(f"\nError during streaming: {e}")
Punti chiave
- Aggiungi
stream=Trueper ricevere i token man mano che vengono generati - Il protocollo utilizzato è SSE (Server-Sent Events)
- In Python, itera sui chunk e stampa
delta.content - Con cURL, usa
-Nper disattivare il buffering - Riserva lo streaming ai casi in cui la visualizzazione progressiva aggiunge valore