Streaming AI API: SSE và timeout

Streaming AI API gửi event trong lúc mô hình tạo output thay vì chờ toàn bộ response body. Nó cải thiện cảm nhận phản hồi nhưng không nhất thiết giảm độ trễ mô hình, đồng thời ứng dụng phải phân tích đúng giao thức của endpoint.

Chat Completions truyền completion chunk, còn Responses dùng response event có kiểu. Ứng dụng có thể nhận HTTP 200 nhưng không hiển thị gì nếu chờ sai cấu trúc.

Bắt đầu không buffering

curl -N -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_RESPONSES_MODEL","input":"Explain SSE.","stream":true}'

Trước tiên thử cùng yêu cầu khi tắt streaming để tách lỗi xác thực request khỏi parsing. Dùng ID trong Mô hình & Giá.

Xử lý SSE như một giao thức

Server-Sent Events là các record có ranh giới, không phải mảnh JSON tùy ý. Ứng dụng phải tránh buffering ở HTTP, proxy và UI; ghép các lần đọc một phần; xử lý text, reasoning, tool, completion và error; giữ cancellation cùng usage cuối; rồi đóng sau terminal event.

Đo theo từng giai đoạn

Chỉ số	Ý nghĩa
Kết nối và xác thực	Tới gateway và kiểm tra khóa
Header upstream	Tuyến được chọn bắt đầu phản hồi
Output hiệu quả đầu tiên	Text, reasoning hoặc tool event hữu ích đầu tiên
Text nhìn thấy đầu tiên	Nội dung đầu tiên người dùng thấy
Tổng thời gian	Hoàn thành, lỗi hoặc hủy

Tool call có thể là output hữu ích trước khi có text. Vận hành nên đo output hiệu quả đầu tiên; UX đo thêm text nhìn thấy đầu tiên.

Thiết kế timeout theo giai đoạn

Tách timeout kết nối, header hoặc output đầu tiên, stream idle và deadline tổng. Yêu cầu reasoning hoặc công cụ có thể chậm xuất hiện text. Đặt ngân sách từ workload thật, không dùng một timeout toàn cục quá ngắn.

Nếu ứng dụng, trình duyệt hoặc proxy đóng sớm, Modelflare có thể ghi 499. Đây là bằng chứng hủy downstream, không tự chứng minh mô hình hoặc channel lỗi. So sánh Abort, timeout proxy, output đầu, mô hình, nhóm và thời điểm.

Khi không thấy text

1. Lặp lại với "stream": false.
2. Xác nhận mô hình hỗ trợ endpoint.
3. Bắt event thô trước UI.
4. Tìm tool hoặc reasoning event không có text.
5. Loại trừ buffering trung gian.
6. Kiểm tra terminal event trong parser.
7. So sánh trạng thái, thời gian và cancellation.

Nếu non-streaming hoạt động và event thô tới nơi, lỗi thường nằm ở parsing hoặc rendering. Nếu không có event, xem hướng dẫn lỗi. Để chọn định dạng, xem Responses API và Chat Completions.

So sánh hai endpoint mà không buffering

Ngoài ví dụ Responses phía trên, hãy kiểm tra Chat Completions bằng đúng định dạng của nó:

curl -N -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "Giải thích SSE bằng ba ý."}],
    "stream": true
  }'

Bộ phân tích phải:

• không buffering trong thư viện HTTP, proxy và giao diện;
• ghép các lần đọc một phần cho đến khi có sự kiện hoàn chỉnh;
• phân tích loại sự kiện của endpoint đã chọn;
• phân biệt văn bản, suy luận, công cụ, hoàn tất và lỗi;
• chấp nhận phản hồi hữu ích dù không có văn bản nhìn thấy;
• giữ trạng thái hủy và số liệu sử dụng cuối;
• đóng luồng sau sự kiện kết thúc.

Danh sách kiểm tra truyền luồng production

• Gắn rõ bộ phân tích với Chat Completions hoặc Responses.
• Kiểm tra văn bản, suy luận, chỉ công cụ, lỗi và hoàn tất bình thường.
• Đo riêng sự kiện đầu, đầu ra hữu ích đầu tiên và văn bản nhìn thấy đầu tiên.
• Đặt giới hạn cho kết nối, đầu ra đầu tiên, thời gian rỗi và toàn bộ thao tác.
• Dùng tín hiệu hủy có chủ đích.
• Xem mỗi lần thử lại là yêu cầu mới nếu chưa có tính lũy đẳng an toàn.
• Giữ ID, trạng thái, mô hình, nhóm và thời gian để chẩn đoán.
• Xác nhận không có lớp trung gian nào buffering lại luồng.

Câu hỏi thường gặp

Truyền luồng có làm mô hình sinh nhanh hơn không?

Không nhất thiết. Nó chỉ hiển thị đầu ra sớm hơn; thời gian đến sự kiện đầu và tốc độ sau đó vẫn phụ thuộc mô hình, tuyến, ngữ cảnh, suy luận và công cụ.

Vì sao curl chạy được nhưng ứng dụng không hiện gì?

Ứng dụng hoặc lớp trung gian có thể buffering, hoặc bộ phân tích Chat Completions đang đọc sự kiện Responses. Hãy bắt sự kiện thô trước khi đổi mô hình.

Có nên thử lại một luồng bị ngắt không?

Chỉ khi thao tác có thể lặp lại an toàn. Công việc upstream hoặc công cụ có thể đã chạy; giới hạn số lần và yêu cầu tính lũy đẳng khi có tác dụng phụ.