Lỗi streaming LLM — SSE bị ngắt, stream bị treo và thiếu usage

Tái hiện bằng curl -N đi thẳng đến API

Bỏ qua mọi proxy. Nếu SSE thô chạy tốt trong toàn bộ quá trình tạo, vấn đề nằm ở đường dẫn của ứng dụng — thêm lại từng hop một:

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

Sửa hop làm hỏng stream

nginx: proxy_buffering off + proxy_read_timeout 300s cho route. Serverless: kiểm tra giới hạn response streaming của nền tảng. Proxy doanh nghiệp: một số proxy hoàn toàn không hỗ trợ SSE — trong trường hợp đó, chuyển về non-streaming.

Xử lý đúng phần cuối

Dữ liệu thanh toán dạng stream đến sau cùng: chunk cuối mang usage (khi được yêu cầu) trước [DONE]. Cộng dồn các delta, đọc usage từ chunk cuối và xem việc đóng sớm (không có finish_reason) là có thể thử lại.

“SSE stream ended without [DONE]” — câu trả lời đã đầy đủ chưa?

Thông báo đó là bước kiểm tra của chính client, không phải lỗi API gửi đến: kết nối đã đóng trước dòng data: [DONE] mà một stream tương thích với OpenAI dùng để kết thúc. Có ba nguyên nhân: một hop ở giữa đã đóng kết nối (do proxy timeout và buffering như trên); server gặp lỗi giữa câu trả lời và đóng mà không có frame kết thúc; hoặc câu trả lời đã hoàn tất nhưng chỉ sentinel bị mất. Chunk cuối cùng bạn nhận được quyết định trường hợp nào: có finish_reason nghĩa là văn bản đầy đủ, còn không có finish_reason nghĩa là văn bản bị ngắt và nên được thử lại. Đừng giao việc kiểm tra đó cho SDK — OpenAI Python SDK lặng lẽ kết thúc vòng lặp khi kết nối đóng mà không có [DONE], và chỉ ném lỗi khi một chunk chứa đối tượng error. Hãy đặt bước kiểm tra trong code của bạn:

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 rỗng: 200, sau đó không có gì

Đôi khi stream mở với HTTP 200 rồi kết thúc mà không có một content chunk nào — không có văn bản, không có tool call, đôi khi thậm chí không có role chunk. Gần như luôn có nghĩa là upstream đã lỗi sau khi header được gửi: provider quá tải, gateway có upstream riêng từ chối yêu cầu, hoặc proxy làm rơi body. Hãy xử lý như stream bị ngắt và thử lại với backoff, đồng thời ghi log raw body của một response lỗi, vì nguyên nhân thường là một error event bên trong stream mà SDK đã bỏ qua. Claude Code xử lý cùng điều kiện này bằng cách thử lại request mà không streaming.

Tại sao usage trong các response dạng stream của tôi lại là null?

Trên các API OpenAI-wire, usage không được đưa vào stream trừ khi bạn truyền stream_options: {"include_usage": true}; khi đó usage xuất hiện trong chunk cuối. Native stream của Anthropic báo usage trong các event message_start/message_delta.

Làm cách nào để phát hiện stream bị ngắt thay vì đã hoàn tất?

Stream hoàn tất sẽ kết thúc bằng finish_reason (hoặc message_stop của Anthropic), sau đó là [DONE]. Kết nối đóng mà không có các dấu hiệu đó nghĩa là stream đã bị ngắt — hãy xem đó là lỗi có thể thử lại, không phải câu trả lời ngắn.

“SSE stream ended without [DONE]” có nghĩa là gì?

Client của bạn đã đọc stream đến cuối kết nối nhưng không thấy dòng data: [DONE] đóng một stream tương thích với OpenAI. API không gửi thông báo đó; client hoặc agent của bạn đã viết nó. Nếu chunk cuối có finish_reason, câu trả lời đã hoàn tất và chỉ phần đóng kết nối bị mất. Nếu không có, câu trả lời đã bị proxy, timeout hoặc lỗi phía server ngắt giữa chừng, và request nên được thử lại.

“stream ended without finish_reason” có nghĩa là gì?

Client đã đọc stream đến cuối nhưng không chunk nào có finish_reason — trường mà stream tương thích với OpenAI dùng để cho biết câu trả lời đã hoàn tất (stop, length, tool_calls). Không có trường này, phần văn bản bạn có chỉ là một mảnh, dù câu cuối trông tự nhiên đến đâu. Hãy thử lại request; nếu lặp lại, hãy tìm proxy timeout hoặc buffering giữa bạn và API.

Tại sao API LLM lại trả về stream rỗng?

Vì lỗi xảy ra sau khi HTTP header đã được gửi: provider quá tải, upstream của gateway từ chối request hoặc proxy làm rơi body. Dòng trạng thái vẫn là 200 nên việc kiểm tra status sẽ không phát hiện. Hãy xem stream không có content chunk là request thất bại, thử lại với backoff và ghi log một response thô để tìm error event bên trong.

Có an toàn không nếu bỏ qua [DONE] bị thiếu khi tôi đã có văn bản?

Chỉ an toàn khi chunk cuối có finish_reason. Nếu không có, văn bản bạn có là một mảnh có thể kết thúc giữa câu hoặc giữa tool-call, với các đối số JSON chưa hoàn chỉnh. Hãy thử lại thay vì lưu nó làm câu trả lời.