Kesalahan streaming LLM—pemutusan SSE, stream yang macet, dan penggunaan yang hilang

Reproduksi dengan curl -N langsung ke API

Lewati semua proxy. Jika SSE mentah mengalir dengan baik selama seluruh generasi, jalur aplikasi Anda yang bermasalah—tambahkan kembali hop satu per satu:

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."}]}'

Perbaiki hop yang menyebabkannya terputus

nginx: proxy_buffering off + proxy_read_timeout 300s untuk rute tersebut. Serverless: periksa batas streaming respons platform. Proxy perusahaan: beberapa tidak dapat menangani SSE sama sekali—gunakan non-streaming sebagai fallback di sana.

Tangani bagian akhir dengan benar

Data penagihan streaming tiba terakhir: chunk terakhir membawa penggunaan (jika diminta) sebelum [DONE]. Agregasikan delta, baca penggunaan dari chunk terakhir, dan perlakukan penutupan awal (tanpa finish_reason) sebagai kondisi yang dapat dicoba ulang.

“SSE stream ended without [DONE]”—apakah jawabannya lengkap?

Pesan itu adalah pemeriksaan milik klien Anda sendiri, bukan kesalahan yang dikirim API: koneksi ditutup sebelum baris data: [DONE] yang mengakhiri stream kompatibel OpenAI. Tiga hal dapat menyebabkannya: hop di antaranya menutup koneksi (batas waktu proxy dan buffering yang dijelaskan di atas); server gagal di tengah jawaban dan menutup koneksi tanpa frame terminal; atau jawaban sebenarnya lengkap dan hanya sentinel yang hilang. Chunk terakhir yang Anda terima menentukan penyebabnya: finish_reason di sana berarti teks lengkap, sedangkan tanpa finish_reason berarti teks terpotong dan harus dicoba lagi. Jangan serahkan pemeriksaan ini kepada SDK—OpenAI Python SDK mengakhiri loop secara diam-diam ketika koneksi ditutup tanpa [DONE], dan hanya menimbulkan error ketika chunk membawa objek kesalahan. Letakkan pemeriksaan dalam kode Anda sendiri:

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))

Stream kosong: 200, lalu tidak ada apa-apa

Terkadang stream terbuka dengan HTTP 200 lalu berakhir tanpa satu pun chunk konten—tanpa teks, tanpa pemanggilan alat, terkadang bahkan tanpa chunk role. Hampir selalu berarti upstream gagal setelah header dikirim: provider kelebihan beban, gateway yang upstream-nya sendiri menolak permintaan, atau proxy yang membuang body. Perlakukan sebagai stream terputus dan coba lagi dengan backoff, serta catat body mentah dari satu respons yang gagal, karena penyebabnya sering berupa event kesalahan di dalam stream yang dilewati SDK Anda. Claude Code merespons kondisi yang sama dengan mencoba ulang permintaan tanpa streaming.

Mengapa usage bernilai null pada respons streaming saya?

Pada API OpenAI-wire, usage tidak disertakan dalam stream kecuali Anda meneruskan stream_options: {"include_usage": true}; usage kemudian muncul pada chunk terakhir. Stream native Anthropic melaporkan usage dalam event message_start/message_delta.

Bagaimana cara mendeteksi stream yang terputus dibandingkan stream yang selesai?

Stream yang selesai berakhir dengan finish_reason (atau message_stop milik Anthropic), lalu [DONE]. Koneksi yang tertutup tanpa penanda tersebut berarti terputus — perlakukan sebagai kegagalan yang dapat dicoba ulang, bukan jawaban singkat.

Apa arti “SSE stream ended without [DONE]”?

Klien Anda membaca stream sampai akhir koneksi dan tidak pernah melihat baris data: [DONE] yang menutup stream yang kompatibel dengan OpenAI. API tidak mengirim pesan tersebut; klien atau agen Anda yang menuliskannya. Jika chunk terakhir membawa finish_reason, jawaban sudah lengkap dan hanya penutup koneksinya yang hilang. Jika tidak, jawaban terputus oleh proxy, timeout, atau kegagalan sisi server, dan permintaan harus dicoba lagi.

Apa arti “stream ended without finish_reason”?

Klien membaca stream hingga selesai dan tidak ada chunk yang membawa finish_reason — field yang digunakan stream kompatibel dengan OpenAI untuk menyatakan bahwa jawaban selesai (stop, length, tool_calls). Tanpanya, teks yang Anda miliki hanyalah fragmen, betapapun alami kalimat terakhirnya. Coba lagi permintaannya; jika terulang, periksa timeout proxy atau buffering antara Anda dan API.

Mengapa API LLM dapat mengembalikan stream kosong?

Karena kegagalan terjadi setelah header HTTP dikirim: penyedia mengalami beban berlebih, upstream gateway menolak permintaan, atau proxy menjatuhkan body. Baris status tetap menunjukkan 200, sehingga pemeriksaan status tidak mendeteksinya. Perlakukan stream tanpa chunk konten sebagai permintaan yang gagal, coba lagi dengan backoff, dan catat satu respons mentah untuk menemukan event error di dalamnya.

Apakah aman mengabaikan [DONE] yang hilang jika saya sudah memiliki teks?

Hanya jika chunk terakhir membawa finish_reason. Tanpanya, teks yang Anda miliki adalah fragmen yang dapat berakhir di tengah kalimat atau di tengah tool-call, dengan argumen JSON yang belum lengkap. Coba lagi alih-alih menyimpannya sebagai jawaban.