Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Streaming ottimizzato

Lezione 5 di 20 Aggiornata il 28 luglio 2026 Avanzato
In questa pagina
  1. Cosa cambia realmente con lo streaming
  2. Consumare lo stream lato client
  3. Inoltrare lo stream al browser
  4. Mantenere la connessione nel tempo
  5. Punti chiave

Cosa cambia realmente con lo streaming

Lo streaming non rende il modello più veloce: rende l’attesa sopportabile. Per una risposta che richiede cinque secondi per essere generata, un utente senza streaming fissa uno schermo vuoto per cinque secondi prima di ricevere un blocco di testo. Con lo streaming, vede le prime parole dopo poche centinaia di millisecondi e legge mentre il modello scrive. La durata totale è identica, ma la percezione è completamente diversa. Ecco perché, in produzione, saltare lo streaming è quasi sempre un errore di progettazione piuttosto che una scelta consapevole.

Tuttavia, il flusso deve attraversare tutta la tua catena. Uno stream generato correttamente dall’API ma accumulato dal tuo server applicativo o memorizzato nel buffer dal tuo reverse proxy raggiunge l’utente in un unico blocco: hai pagato il prezzo della complessità dello streaming senza raccoglierne i benefici. Questa lezione segue quindi il percorso completo, dalla chiamata API al browser.

Consumare lo stream lato client

Con le Responses API, impostare stream=True trasforma la risposta in una sequenza di eventi tipizzati che iteri man mano che arrivano. Ogni frammento di testo arriva in un evento response.output_text.delta; la fine dello stream è segnalata da response.completed, che contiene l’oggetto risposta completo, utile per recuperare l’utilizzo dei token.

import openai

client = openai.OpenAI()

def generate_streaming(prompt: str):
    """Generazione in streaming con le Responses API."""
    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)
        elif event.type == "response.completed":
            print()  # Nuova riga alla fine
            return event.response

Il flag flush=True non è cosmetico: senza di esso, Python bufferizza l’output da solo e ti ritrovi con il comportamento a blocco che cercavi di evitare. Questo dettaglio si ripete a ogni livello della catena ed è la principale difficoltà dello streaming.

Il meccanismo copre anche le chiamate di funzione. Gli argomenti degli strumenti vengono costruiti progressivamente e puoi visualizzarli mentre vengono generati per segnalare all’utente che una ricerca è in fase di formulazione, invece di lasciarlo fissare un’interfaccia bloccata mentre il modello prepara la sua chiamata.

tools = [
    {
        "type": "function",
        "name": "search_product",
        "description": "Searches for a product in the catalog.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "category": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

def streaming_with_tools(prompt: str):
    stream = client.responses.create(
        model="gpt-5.6-terra",
        input=prompt,
        tools=tools,
        stream=True,
    )

    for event in stream:
        match event.type:
            case "response.output_text.delta":
                print(event.delta, end="", flush=True)
            case "response.function_call_arguments.delta":
                # Argomenti della funzione attualmente in generazione
                print(f"[arg: {event.delta}]", end="")
            case "response.function_call_arguments.done":
                print(f"\n[Chiamata di funzione completata]")

Inoltrare lo stream al browser

Il tuo frontend non parla direttamente con le API di OpenAI: parla con il tuo server, che deve quindi inoltrare lo stream. Gli Server-Sent Events (SSE) sono il formato naturale per questo: una risposta HTTP che rimane aperta, dove ogni riga data: trasporta un frammento JSON. L’esempio seguente inoltra il testo man mano che arriva, per poi emettere un messaggio finale contenente il conteggio dei token, permettendoti di fatturare o registrare log senza una seconda chiamata.

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

app = FastAPI()
client = openai.OpenAI()

@app.post("/api/chat")
async def chat_streaming(request: dict):
    prompt = request["message"]

    async def generate():
        stream = client.responses.create(
            model="gpt-5.6-terra",
            input=prompt,
            stream=True,
        )

        for event in stream:
            if event.type == "response.output_text.delta":
                data = json.dumps({"text": event.delta})
                yield f"data: {data}\n\n"
            elif event.type == "response.completed":
                usage = event.response.usage
                data = json.dumps({
                    "end": True,
                    "input_tokens": usage.input_tokens,
                    "output_tokens": usage.output_tokens,
                })
                yield f"data: {data}\n\n"

    return StreamingResponse(
        generate(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",  # Importante per nginx
        },
    )

Poi c’è il reverse proxy, il solito sospettato quando «lo streaming non funziona in produzione anche se funzionava in locale». Di default, nginx accumula la risposta del backend prima di trasmetterla. La configurazione seguente disabilita questo comportamento solo per la rotta specifica.

location /api/chat {
    proxy_pass http://127.0.0.1:8000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection "";
    chunked_transfer_encoding on;
}

Mantenere la connessione nel tempo

Uno stream aperto per diverse decine di secondi è più esposto di una chiamata breve: un calo di rete, un limite di quota raggiunto e la generazione si interrompe a metà frase. La tua strategia di retry deve distinguere tra questi due casi, perché richiedono approcci diversi. Un errore di connessione dovrebbe essere ritentato con un backoff esponenziale, dando tempo alla rete di riprendersi senza martellare l’API; un superamento della quota dovrebbe essere ritentato dopo un’attesa fissa, poiché la finestra del rate limit si resetta a intervalli regolari.

import openai

def resilient_streaming(prompt: str, max_attempts: int = 3):
    """Streaming con gestione errori e retry."""
    for attempt in range(max_attempts):
        try:
            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
                    yield event.delta

            return  # Successo, uscita

        except openai.APIConnectionError:
            if attempt < max_attempts - 1:
                import time
                time.sleep(2 ** attempt)  # Backoff esponenziale
            else:
                raise
        except openai.RateLimitError:
            import time
            time.sleep(5)  # Attesa fissa per rate limit

Un ultimo ritocco migliora il comfort di lettura. Emettere ogni token produce un testo a scatti, specialmente se la tua interfaccia applica un’animazione o se il risultato va al text-to-speech. Accumulare fino alla fine di una frase dà un ritmo più vicino alla lettura umana, al costo di un leggero ritardo aggiuntivo sul primo frammento.

def streaming_by_sentence(prompt: str):
    """Accumula e restituisce per frase completa."""
    buffer = ""

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

    for event in stream:
        if event.type == "response.output_text.delta":
            buffer += event.delta
            # Cerca la fine della frase
            for separator in [".\n", "!\n", "?\n", ". ", "! ", "? "]:
                if separator in buffer:
                    parts = buffer.split(separator, 1)
                    yield parts[0] + separator.rstrip()
                    buffer = parts[1] if len(parts) > 1 else ""

    if buffer.strip():
        yield buffer.strip()

Nota l’if buffer.strip() finale: senza di esso, una risposta che non termina con una punteggiatura forte perderebbe le ultime parole. Questo tipo di svista passa inosservato nei test e si manifesta in produzione su risposte troncate da max_output_tokens.

Punti chiave

  • Usa sempre lo streaming in produzione per ridurre la latenza percepita
  • Configura nginx con proxy_buffering off per gli SSE
  • Gestisci gli errori con retry e backoff esponenziale
  • Accumula per frase per una visualizzazione più naturale