Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Streaming SSE

Lezione 10 di 14 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Ricevi le risposte in tempo reale
  2. Come funziona lo streaming
  3. Streaming in Python con l’SDK OpenAI
  4. Streaming con l’endpoint /v1/responses
  5. Streaming con cURL
  6. Quando usare lo streaming
  7. Gestione degli errori nello streaming
  8. Punti chiave

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=True attiva lo streaming
  • La risposta è un iteratore di oggetti chunk (frammenti)
  • Ogni chunk contiene un delta con il nuovo contenuto
  • end="" evita le interruzioni di riga tra i frammenti
  • flush=True forza 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=True per 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 -N per disattivare il buffering
  • Riserva lo streaming ai casi in cui la visualizzazione progressiva aggiunge valore