GPT-6 Astra 串流指南：回應 API 事件、工具與錯誤處理

串流技術透過在GPT-6 Astra運作時即時傳遞事件，來改善使用者感知的延遲。這並不能讓底層運算免費，也無法消除失敗情況。正式環境的客戶端必須能組合增量輸出、呈現工具進度、區分終端狀態，並在連線中斷時進行復原。

從輸入事件開始

設定 stream: true 並迭代 SDK 的類型化事件串流。

const stream = await client.responses.create({
  model: "gpt-6-astra",
  input: "用五個步驟解釋遷移計畫。",
  stream: true
});

for await (const event of stream) {
  switch (event.type) {
    .output_text.delta
      process.stdout.write(event.delta);
      break;
    .completed
      console.log("\n完成");
      break;
    .failed
      console.error("失敗", event.response.error);
      break;
    case "error":
      console.error(event.message);
      break;
  }
}

常見的文字生命週期事件包括 response.created、response.output_text.delta、response.completed 和 error。完整的事件聯合還包含輸出項目、內容部分、註解、拒絕、失敗及其他事件。請安全地處理未知的事件類型，以免新加入的事件導致舊版客戶端崩潰。

建立組譯器，而非文字附加迴圈

回應可包含多個輸出項目與內容部分。請依據回應、輸出項目及內容部分來索引狀態，而非將每個增量附加至單一全域字串。在可取得的情況下，使用文件化的識別碼或序列資料進行去重，並僅呈現已提交的本地狀態。

註解與引用可能獨立於正文送達。請保留其偏移位置或關聯性，而非在合併時予以移除。若有最終回應物件，應以其為準據。

終端狀態不可互換

.completed 表示成功完成。response.failed 帶有失敗訊息。response.incomplete 可能反映 token 限制或其他原因，並可能包含有用的部分輸出。傳輸層級的 error 可能在沒有正常回應終端事件的情況下發生。

切勿僅因 socket 關閉就將請求標記為成功。應在 response.created 到達時立即持久化回應 ID，然後再另行儲存終端狀態。

誠實記錄串流工具活動

工具呼叫引入多個階段：模型規劃、參數生成、伺服器或用戶端執行、工具結果，以及恢復生成。您的使用者介面僅在對應事件或狀態存在時，才應顯示「搜尋中」或「等待核准」。請勿虛構進度百分比。

對於用戶端執行的函式，在解析前應先組裝完整引數，除非 API 合約明確支援增量消費。驗證這些引數，執行一次，並使用呼叫 ID 回傳結果。串流重複事件不得觸發重複的副作用。

背壓與 UI 效能

Token 大小的增量更新可能比瀏覽器渲染速度更快。短暫緩衝後，以受控的節奏更新 UI。這能減少版面計算工作，同時不會明顯影響感知延遲。若框架支援，請限制記憶體緩衝區並暫停後續處理。

將原始事件日誌與視圖模型分離。事件日誌支援除錯；視圖模型將差異合併為穩定的使用者可見內容。在記錄前，對敏感工具負載進行編輯。

斷線、超時與取消

斷線時，將操作歸類為未知，直到恢復狀態為止。模型回應可能已在伺服器端繼續進行，且外部工具可能已採取行動。避免自動重播寫入操作。

使用請求截止時間與閒置串流計時器，但需區分「無文字增量」與「無活動」；長時間的工具呼叫仍可能正常運作。取消應傳遞至您自己的可取消工具，但無法保證已完成效果的復原。

若您繼續進行回應狀態，請保留最後提交的回應與工具結果。WebSocket 特定的復原可能回報 previous_response_not_found；官方錯誤指南建議在無法解析狀態時，使用完整輸入上下文及 previous_response_id: null 重新嘗試。

可觀測性

記錄到 response.created 的時間、第一個文字增量、第一個工具事件和終端事件；總持續時間；事件計數；終端狀態；斷線；重試；以及使用者取消。將所有事件與一個應用程式請求 ID 和 OpenAI 回應 ID 關聯起來。

測試格式錯誤的訂單、重複配送、未知事件、工具逾時、可見文字後的延遲失敗，以及寫入後連線中斷。串流正確性即為狀態機正確性。

瀏覽器與伺服器實作模式

在許多產品中，應用伺服器應持有 OpenAI 的連線，並將經過淨化的事件串流轉發給瀏覽器。這樣做可以避免 API 憑證暴露於客戶端，集中授權管理，並讓伺服器隱藏內部工具參數。瀏覽器僅接收渲染所需的事件：狀態、安全的文字增量、引用、核准提示與終端結果。

保留粗略的檢查點而非每個字元。儲存每個差異會產生過多的寫入；僅在完成時儲存則會在斷線時遺失過多內容。較短的間隔或內容區塊邊界通常是更好的折衷方案。重新連線時，傳送最新的已提交檢視，並根據您的傳輸設計從下一個已知事件繼續。

審核與安全需要串流政策。部分文字在最終回應產生前就會送達使用者，因此僅在完成時才執行的下游審查可能為時已晚。請根據風險選擇預先生成控制、增量防護措施、緩衝處理或限制串流。高風險工作流程可能需刻意犧牲部分即時性以換取審查。

最後，請確保分析不會重複計算在瀏覽器重新整理後繼續的回應。OpenAI 回應 ID 和您穩定的應用程式請求 ID 應將每個區段整合為一個邏輯任務。

常見問題

串流會降低代幣成本嗎？

不。它改變的是傳遞方式，而非生成的 token 數量。

我可以立即顯示部分輸出嗎？

可以，但請將其標記為進行中，並準備好面對拒絕、不完整或失敗的結果。

連接中斷時我應該重試嗎？

先進行復原或對帳，尤其是工具可能引發副作用時。盲目重播可能導致操作重複。

SSE 與 WebSocket 事件處理是否相同？

它們共用 Responses 概念，但傳輸與續接行為有所不同。請依照所選模式的操作指南進行。

結論

可靠的 GPT-6 Astra 串流需要型別事件處理、結構化組裝器、明確的終端狀態、冪等工具執行、背壓機制與復原能力。最佳化使用者對進度的感知，同時避免將部分文字或已關閉的連線誤判為成功。