AI API 串流指南:SSE、首個輸出與逾時

正確處理 Chat 與 Responses 事件、解析 SSE、量測首個有效輸出、分階段設定逾時並診斷 499,打造可靠的 AI API 串流。

AI API 串流指南:SSE、首個輸出與逾時

AI API 串流會在模型生成期間逐步送出輸出,而不是等待完整的回應本文。它能提升使用者感受到的回應速度,但不會自動降低模型延遲,還多了一份用戶端必須正確解析的協定契約。

第一條原則是:解析器必須與端點相符。Chat Completions 使用串流傳送的區塊(chunk),Responses 則使用具型別的回應事件。用戶端如果預期的事件結構不對,即使收到 HTTP 200,畫面上仍可能什麼都沒有。

從不緩衝的請求開始

對 Chat Completions 模型,可用 curl -N 停用 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": "請用三點說明 SSE。"}],
    "stream": true
  }'

對相容 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": "請用三點說明 SSE。",
    "stream": true
  }'

請使用模型與定價中列出的完整模型 ID。建議先在停用串流的情況下測試同一個請求一次,藉此把請求驗證與串流解析分開處理。

把事件串流當成協定處理

Server-Sent Events 是有固定框架的記錄,而不是任意的 JSON 片段。正式環境的用戶端需要:

  • 讓回應本文在 HTTP 函式庫、代理與 UI 層都保持不緩衝;
  • 累積零散的網路讀取資料,直到取得完整事件;
  • 解析所選端點使用的事件類型;
  • 處理文字增量、推理或工具事件、完成事件與錯誤事件;
  • 不要假設每個有用的回應都包含可見文字;
  • 保留取消狀態與最終的用量資訊;
  • 收到終止事件後關閉串流,而不是無限期等待。

可行時,請使用原生支援所選協定的 SDK。自行開發的解析器應該以片段化的框架、單次讀取包含多個事件、只有工具的輸出,以及正常的終止事件進行測試。

不只量測首 Token 延遲

對 Agent 流量而言,「首 Token 延遲」(TTFT)往往太過籠統。請分開量測以下項目:

量測項目 代表意義
連線與驗證 連到閘道並驗證金鑰所需的時間
服務商回應標頭 所選路由開始回應前的時間
首個有效輸出 第一個有用的文字、推理或工具事件
首段可見文字 使用者實際能看到的第一段文字
輸出輸送量 輸出開始後的可見生成速度
總回應時間 直到完成、失敗或取消為止的時間

工具呼叫可能在出現任何可見文字之前就產生有效輸出。因此,首個有效輸出是較穩妥的營運指標,而首段可見文字則適合用來衡量使用者體驗。

Modelflare 使用日誌會保留請求層級的時間證據,讓這些階段可以與模型、群組、狀態、Token 和費用一起比較。

依階段設計逾時

只設定一個很短的全域逾時,會造成難以判讀的失敗。串流用戶端應該分別考量幾種時間預算:

  1. 連線逾時:無法建立 HTTP 連線。
  2. 標頭或首次輸出逾時:請求被接受後,遲遲沒有回應或有效事件。
  3. 閒置逾時:串流已開始,但異常長的一段時間內沒有新事件送達。
  4. 整體截止時間:整個操作超過了工作負載的業務上限。

推理量大或由工具驅動的請求,在出現可見文字前等待的時間,本來就可能比簡短的對話回應更長。請依實際觀察到的工作負載行為設定時間預算,並在使用者不再需要結果時主動取消。

了解取消與 499 記錄

如果用戶端、反向代理、瀏覽器分頁或呼叫端的截止時間關閉了下游連線,閘道可能會將該請求記錄為用戶端取消。請求記錄中的 499 標示,是下游連線在完成前就結束的證據;它本身並不能證明所選的模型或管道發生故障。

調查取消情況時,請比較:

  • 用戶端的截止時間與中止(abort)訊號;
  • 代理的緩衝設定與閒置逾時;
  • 首個有效輸出前的時間;
  • 是否有任何事件送達用戶端;
  • 所選的模型與群組;
  • 請求 ID 與取消的時間戳記。

診斷沒有可見文字的串流

請依下列順序進行:

  1. 以 "stream": false 重送請求。
  2. 確認模型支援所選的端點。
  3. 在 UI 轉換之前擷取原始事件。
  4. 檢查回應是否包含工具呼叫或推理事件,而非文字。
  5. 確認沒有中介層在緩衝回應本文。
  6. 確認解析器能處理該端點的終止事件。
  7. 在使用日誌中檢查狀態、首次輸出、總時間與取消情況。

如果非串流請求正常,且原始串流事件也有送達,問題通常出在用戶端的解析或顯示,而不是驗證或模型存取。如果連原始事件都沒有送達,請接著參閱 AI API 錯誤指南。

正式環境串流檢查清單

  • 明確讓解析器對應 Chat Completions 或 Responses。
  • 在 HTTP 用戶端與每一層可控制的代理中停用緩衝。
  • 測試應用程式會用到的文字、推理、只有工具與錯誤事件。
  • 區分首個有效輸出與首段可見文字。
  • 使用符合各階段需求的逾時,並設計明確的中止訊號。
  • 除非操作具備安全的冪等性設計,否則請把重試視為新的請求。
  • 保留請求 ID、狀態、所選模型、群組與時間資料,以便診斷。
  • 參考 Responses API 與 Chat Completions 比較確認端點的選擇。

常見問題

串流會讓模型生成得更快嗎?

不一定。串流只是讓輸出更早出現;生成速度與第一個事件出現前的時間,仍取決於模型、路由、上下文、推理與工具。

為什麼 curl 正常,應用程式卻什麼都沒顯示?

應用程式或中介層可能緩衝了回應本文,或解析器預期的是 Chat Completions 區塊,實際收到的卻是 Responses 事件。在更換模型或路由之前,請先在應用程式邊界擷取原始框架。

串流中斷後,用戶端應該重試嗎?

只有在重複執行該操作是安全的情況下才應重試。中斷的串流可能已經讓服務商完成部分工作或觸發工具活動。在重複副作用會造成影響的情境中,請使用有上限的重試,並在應用程式層實作冪等性。