Streaming API AI: SSE, đầu ra đầu tiên, thời gian chờ

Xây dựng streaming API AI ổn định với event Chat và Responses đúng chuẩn, phân tích SSE, số đo đầu ra hữu ích đầu tiên, thời gian chờ theo giai đoạn và chẩn đoán 499.

Streaming API AI: SSE, đầu ra đầu tiên, thời gian chờ

Streaming API AI gửi đầu ra dần dần trong lúc mô hình đang tạo nội dung thay vì chờ toàn bộ nội dung phản hồi. Cách này có thể giúp phản hồi có cảm giác nhanh hơn, nhưng không tự động giảm độ trễ của mô hình, đồng thời bổ sung một hợp đồng giao thức mà ứng dụng khách phải phân tích đúng.

Quy tắc đầu tiên là dùng trình phân tích khớp với endpoint. Chat Completions dùng các chunk completion được stream, còn Responses dùng các event phản hồi có kiểu. Ứng dụng khách có thể nhận HTTP 200 mà vẫn không hiển thị gì nếu chờ sai cấu trúc event.

Bắt đầu với một yêu cầu không buffer

Với mô hình Chat Completions, curl -N tắt buffer đầu ra của curl:

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": "Explain SSE in three points."}],
    "stream": true
  }'

Với mô hình tương thích Responses:

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 in three points.",
    "stream": true
  }'

Hãy dùng chính xác ID mô hình trong Mô hình & bảng giá. Trước tiên, hãy thử cùng yêu cầu đó một lần với streaming tắt; cách này tách bước kiểm tra tính hợp lệ của yêu cầu khỏi bước phân tích stream.

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

Server-Sent Events là các bản ghi có khung, không phải những mảnh JSON tùy ý. Một ứng dụng khách production cần:

  • giữ nội dung phản hồi không bị buffer qua thư viện HTTP, proxy và lớp giao diện;
  • gom các lần đọc mạng chưa đầy đủ cho đến khi có một event hoàn chỉnh;
  • phân tích loại event mà endpoint đã chọn sử dụng;
  • xử lý delta văn bản, event suy luận hoặc công cụ, event hoàn tất và event lỗi;
  • không giả định rằng mọi phản hồi hữu ích đều chứa văn bản hiển thị;
  • giữ lại thông tin hủy và thông tin mức sử dụng cuối cùng;
  • đóng stream sau event kết thúc thay vì chờ mãi.

Khi có thể, hãy dùng SDK hỗ trợ sẵn giao thức đã chọn. Trình phân tích tự viết cần được kiểm thử với khung bị phân mảnh, nhiều event trong một lần đọc, đầu ra chỉ có công cụ và một event kết thúc hợp lệ.

Đo nhiều hơn thời gian đến token đầu tiên

“Thời gian đến token đầu tiên” thường quá mơ hồ đối với lưu lượng agent. Hãy tách riêng các số đo sau:

Số đo Ý nghĩa
Kết nối và xác thực Thời gian để đến gateway và xác thực khóa
Header phản hồi từ nhà cung cấp dịch vụ Thời gian đến khi tuyến đã chọn bắt đầu phản hồi
Đầu ra hữu ích đầu tiên Văn bản, suy luận hoặc event công cụ hữu ích đầu tiên
Văn bản hiển thị đầu tiên Văn bản đầu tiên người dùng thực sự nhìn thấy
Tốc độ đầu ra Tốc độ tạo nội dung hiển thị sau khi đầu ra bắt đầu
Tổng thời gian phản hồi Thời gian đến khi hoàn tất, gặp lỗi hoặc bị hủy

Một lệnh gọi công cụ có thể tạo ra đầu ra hữu ích trước khi có bất kỳ văn bản hiển thị nào. Vì vậy, đầu ra hữu ích đầu tiên là số đo vận hành an toàn hơn, còn văn bản hiển thị đầu tiên hữu ích cho trải nghiệm người dùng.

Nhật ký sử dụng của Modelflare lưu bằng chứng thời gian theo từng yêu cầu để có thể so sánh các giai đoạn này với mô hình, nhóm, trạng thái, token và chi phí.

Thiết kế thời gian chờ theo giai đoạn

Một thời gian chờ tổng ngắn sẽ tạo ra những lỗi khó xác định nguyên nhân. Ứng dụng khách streaming nên tính đến nhiều ngân sách thời gian:

  1. Thời gian chờ kết nối: không thiết lập được kết nối HTTP.
  2. Thời gian chờ header hoặc đầu ra đầu tiên: không có phản hồi hoặc event hữu ích nào sau khi yêu cầu đã được chấp nhận.
  3. Thời gian chờ khi không hoạt động: stream đã bắt đầu nhưng không có event mới trong một khoảng thời gian dài bất thường.
  4. Hạn chót tổng thể: toàn bộ thao tác vượt quá giới hạn nghiệp vụ của tác vụ.

Các yêu cầu nặng về suy luận hoặc dựa nhiều vào công cụ có thể phải chờ lâu hơn trước khi có văn bản hiển thị so với một lượt chat ngắn, và điều đó là bình thường. Hãy chọn ngân sách thời gian dựa trên hành vi đã quan sát được của tác vụ, và chủ động hủy khi người dùng không còn cần kết quả.

Hiểu việc hủy yêu cầu và bản ghi 499

Nếu ứng dụng khách, reverse proxy, tab trình duyệt hoặc hạn chót của phía gọi đóng kết nối phía ứng dụng khách, gateway có thể ghi nhận yêu cầu là bị ứng dụng khách hủy. Nhãn 499 trong bản ghi yêu cầu là bằng chứng cho thấy kết nối phía ứng dụng khách đã kết thúc trước khi hoàn tất; bản thân nó không chứng minh rằng mô hình hoặc kênh đã chọn gặp lỗi.

Khi điều tra việc hủy, hãy so sánh:

  • hạn chót và tín hiệu hủy (abort signal) của ứng dụng khách;
  • cơ chế buffer và thời gian chờ khi không hoạt động của proxy;
  • thời gian đến đầu ra hữu ích đầu tiên;
  • liệu có event nào đã đến ứng dụng khách hay chưa;
  • mô hình và nhóm đã chọn;
  • ID yêu cầu và thời điểm hủy.

Chẩn đoán stream không trả về văn bản hiển thị

Hãy làm theo thứ tự sau:

  1. Lặp lại yêu cầu với "stream": false.
  2. Xác nhận mô hình hỗ trợ endpoint đã chọn.
  3. Ghi lại event thô trước khi giao diện biến đổi chúng.
  4. Kiểm tra xem phản hồi có chứa lệnh gọi công cụ hoặc event suy luận thay vì văn bản hay không.
  5. Xác minh rằng không có lớp trung gian nào đang buffer nội dung phản hồi.
  6. Xác nhận trình phân tích xử lý được event kết thúc của endpoint.
  7. Xem lại trạng thái, đầu ra đầu tiên, tổng thời gian và việc hủy trong nhật ký sử dụng.

Nếu chế độ không streaming hoạt động và event streaming thô vẫn đến, lỗi thường nằm ở khâu phân tích hoặc hiển thị của ứng dụng khách chứ không phải ở xác thực hay quyền truy cập mô hình. Nếu không có event thô nào đến, hãy tiếp tục với Hướng dẫn lỗi API AI.

Danh sách kiểm tra streaming cho production

  • Chỉ định rõ trình phân tích dành cho Chat Completions hoặc Responses.
  • Tắt buffer trong HTTP client và mọi lớp proxy bạn kiểm soát.
  • Kiểm tra các event văn bản, suy luận, chỉ có công cụ và lỗi mà ứng dụng sử dụng.
  • Phân biệt đầu ra hữu ích đầu tiên với văn bản hiển thị đầu tiên.
  • Dùng thời gian chờ phù hợp với từng giai đoạn và tín hiệu hủy có chủ đích.
  • Coi mỗi lần thử lại là một yêu cầu mới, trừ khi thao tác có thiết kế idempotent an toàn.
  • Lưu ID yêu cầu, trạng thái, mô hình đã chọn, nhóm và thời gian để chẩn đoán.
  • So sánh lựa chọn endpoint trong Responses API hay Chat Completions.

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

Streaming có giúp mô hình tạo nội dung nhanh hơn không?

Không nhất thiết. Streaming đưa đầu ra đến sớm hơn; tốc độ tạo nội dung và thời gian trước event đầu tiên vẫn phụ thuộc vào 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 thị gì?

Ứng dụng hoặc một lớp trung gian có thể đang buffer nội dung phản hồi, hoặc trình phân tích đang chờ chunk Chat Completions trong khi nhận được event Responses. Hãy ghi lại các khung thô tại ranh giới ứng dụng trước khi đổi mô hình hoặc tuyến.

Ứng dụng khách có nên thử lại sau khi stream bị ngắt không?

Chỉ khi việc lặp lại thao tác là an toàn. Một stream bị ngắt có thể đã khiến nhà cung cấp dịch vụ xử lý hoặc công cụ thực thi. Hãy dùng số lần thử lại có giới hạn và cơ chế idempotent ở cấp ứng dụng khi tác dụng phụ trùng lặp gây ảnh hưởng.