Errori di streaming LLM — interruzioni SSE, stream bloccati e utilizzo mancante

Riproduci con curl -N direttamente sull'API

Bypassa ogni proxy. Se lo SSE grezzo scorre correttamente per tutta la generazione, il problema è nel percorso della tua applicazione — reintroduci i passaggi uno alla volta:

curl -N https://api.kunavo.com/v1/chat/completions \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","stream":true,
       "stream_options":{"include_usage":true},
       "max_tokens":300,
       "messages":[{"role":"user","content":"Count slowly to 20 in words."}]}'

Correggi il passaggio che lo interrompe

nginx: proxy_buffering off + proxy_read_timeout 300s per la route. Serverless: controlla i limiti della piattaforma per lo streaming delle risposte. Proxy aziendali: alcuni non supportano affatto SSE — in quel caso usa il fallback senza streaming.

Gestisci correttamente la parte finale

I dati di fatturazione dello streaming arrivano per ultimi: l'ultimo chunk contiene l'utilizzo (quando richiesto) prima di [DONE]. Aggrega i delta, leggi l'utilizzo dall'ultimo chunk e considera ritentabile una chiusura anticipata (senza finish_reason).

“SSE stream ended without [DONE]” — la risposta era completa?

Quel messaggio è un controllo del tuo client, non un errore inviato dall'API: la connessione si è chiusa prima della riga data: [DONE] con cui termina uno stream compatibile con OpenAI. Le cause sono tre: un passaggio intermedio ha chiuso la connessione (il timeout del proxy e il buffering descritti sopra); il server ha fallito durante la risposta e si è chiuso senza un frame terminale; oppure la risposta era completa e si è perso solo il sentinel. Decide l'ultimo chunk ricevuto: un finish_reason indica che il testo è completo, mentre l'assenza di finish_reason indica che è stato interrotto e va ritentato. Non lasciare questo controllo all'SDK: l'OpenAI Python SDK termina silenziosamente il ciclo quando la connessione si chiude senza [DONE] e genera un errore solo quando un chunk contiene un oggetto di errore. Inserisci il controllo nel tuo codice:

from openai import OpenAI

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

finish_reason, parts = None, []
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Count slowly to 20 in words."}],
    stream=True,
)
for chunk in stream:  # raises openai.APIError on a chunk that carries "error"
    for choice in chunk.choices:
        parts.append(choice.delta.content or "")
        finish_reason = choice.finish_reason or finish_reason

if finish_reason is None:
    raise RuntimeError("stream closed without a finish_reason: cut off, retry it")
print("".join(parts))

Uno stream vuoto: 200, poi nulla

A volte lo stream si apre con HTTP 200 e termina senza un singolo chunk di contenuto: niente testo, nessuna chiamata a uno strumento, talvolta nemmeno il chunk del ruolo. Quasi sempre significa che un upstream ha fallito dopo l'invio degli header: un provider sovraccarico, un gateway il cui upstream ha rifiutato la richiesta o un proxy che ha eliminato il body. Trattalo come uno stream interrotto e ritenta con backoff; registra inoltre il body grezzo di una risposta fallita, perché spesso la causa è un evento di errore interno allo stream che il tuo SDK ha ignorato. Claude Code reagisce alla stessa condizione ritentando la richiesta senza streaming.

Perché usage è null nelle mie risposte in streaming?

Nelle API OpenAI-wire usage non è incluso negli stream a meno che tu non passi stream_options: {"include_usage": true}; quindi arriva nell'ultimo chunk. Lo stream nativo di Anthropic comunica l'utilizzo negli eventi message_start/message_delta.

Come rilevo uno stream interrotto rispetto a uno completato?

Uno stream completato termina con un finish_reason (o con message_stop di Anthropic) e poi [DONE]. Una connessione che si chiude senza questi indicatori è stata interrotta: trattala come un errore ritentabile, non come una risposta breve.

Che cosa significa “SSE stream ended without [DONE]”?

Il client ha letto lo stream fino alla fine della connessione e non ha mai visto la riga data: [DONE] che chiude uno stream compatibile con OpenAI. L'API non ha inviato quel messaggio: lo ha scritto il tuo client o agente. Se l'ultimo chunk conteneva un finish_reason, la risposta è completa e si è persa solo la chiusura. Se non lo conteneva, la risposta è stata interrotta da un proxy, un timeout o un errore lato server e la richiesta va ritentata.

Che cosa significa “stream ended without finish_reason”?

Il client ha letto lo stream fino alla fine e nessun chunk conteneva un finish_reason: il campo usato da uno stream compatibile con OpenAI per indicare che la risposta è completa (stop, length, tool_calls). Senza di esso, il testo disponibile è un frammento, per quanto naturale sembri l'ultima frase. Ritenta la richiesta; se il problema si ripete, cerca un timeout del proxy o buffering tra te e l'API.

Perché un'API LLM dovrebbe restituire uno stream vuoto?

Perché il problema si è verificato dopo l'invio degli header HTTP: il provider era sovraccarico, l'upstream di un gateway ha rifiutato la richiesta oppure un proxy ha eliminato il body. La riga di stato indica comunque 200, quindi i controlli dello stato non lo rilevano. Tratta uno stream senza chunk di contenuto come una richiesta fallita, ritenta con backoff e registra una risposta grezza per individuare l'evento di errore al suo interno.

È sicuro ignorare un [DONE] mancante se ho già del testo?

Solo quando l'ultimo chunk conteneva un finish_reason. Senza di esso, il testo disponibile è un frammento che può terminare a metà frase o a metà chiamata a uno strumento, con gli argomenti JSON incompleti. Ritenta invece di salvarlo come risposta.