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

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 和費用一起比較。
依階段設計逾時
只設定一個很短的全域逾時,會造成難以判讀的失敗。串流用戶端應該分別考量幾種時間預算:
- 連線逾時:無法建立 HTTP 連線。
- 標頭或首次輸出逾時:請求被接受後,遲遲沒有回應或有效事件。
- 閒置逾時:串流已開始,但異常長的一段時間內沒有新事件送達。
- 整體截止時間:整個操作超過了工作負載的業務上限。
推理量大或由工具驅動的請求,在出現可見文字前等待的時間,本來就可能比簡短的對話回應更長。請依實際觀察到的工作負載行為設定時間預算,並在使用者不再需要結果時主動取消。
了解取消與 499 記錄
如果用戶端、反向代理、瀏覽器分頁或呼叫端的截止時間關閉了下游連線,閘道可能會將該請求記錄為用戶端取消。請求記錄中的 499 標示,是下游連線在完成前就結束的證據;它本身並不能證明所選的模型或管道發生故障。
調查取消情況時,請比較:
- 用戶端的截止時間與中止(abort)訊號;
- 代理的緩衝設定與閒置逾時;
- 首個有效輸出前的時間;
- 是否有任何事件送達用戶端;
- 所選的模型與群組;
- 請求 ID 與取消的時間戳記。
診斷沒有可見文字的串流
請依下列順序進行:
- 以 "stream": false 重送請求。
- 確認模型支援所選的端點。
- 在 UI 轉換之前擷取原始事件。
- 檢查回應是否包含工具呼叫或推理事件,而非文字。
- 確認沒有中介層在緩衝回應本文。
- 確認解析器能處理該端點的終止事件。
- 在使用日誌中檢查狀態、首次輸出、總時間與取消情況。
如果非串流請求正常,且原始串流事件也有送達,問題通常出在用戶端的解析或顯示,而不是驗證或模型存取。如果連原始事件都沒有送達,請接著參閱 AI API 錯誤指南。
正式環境串流檢查清單
- 明確讓解析器對應 Chat Completions 或 Responses。
- 在 HTTP 用戶端與每一層可控制的代理中停用緩衝。
- 測試應用程式會用到的文字、推理、只有工具與錯誤事件。
- 區分首個有效輸出與首段可見文字。
- 使用符合各階段需求的逾時,並設計明確的中止訊號。
- 除非操作具備安全的冪等性設計,否則請把重試視為新的請求。
- 保留請求 ID、狀態、所選模型、群組與時間資料,以便診斷。
- 參考 Responses API 與 Chat Completions 比較確認端點的選擇。
常見問題
串流會讓模型生成得更快嗎?
不一定。串流只是讓輸出更早出現;生成速度與第一個事件出現前的時間,仍取決於模型、路由、上下文、推理與工具。
為什麼 curl 正常,應用程式卻什麼都沒顯示?
應用程式或中介層可能緩衝了回應本文,或解析器預期的是 Chat Completions 區塊,實際收到的卻是 Responses 事件。在更換模型或路由之前,請先在應用程式邊界擷取原始框架。
串流中斷後,用戶端應該重試嗎?
只有在重複執行該操作是安全的情況下才應重試。中斷的串流可能已經讓服務商完成部分工作或觸發工具活動。在重複副作用會造成影響的情境中,請使用有上限的重試,並在應用程式層實作冪等性。