OpenAI API 流式輸出（streaming）怎麼寫：stream=True、response.output_text.delta 事件、Python 和 Node 示例

本文根據 OpenAI 官方《Streaming API responses》和 Quickstart 整理，資料核對於 2026-11-05。代碼裏的模型名取自官方當天示例，請以官方模型頁為準。本站（bigolab.com）不是 OpenAI 官方網站。API 是按用量計費的獨立服務，與 ChatGPT 訂閱分開計算，Key 的獲取見 /guides/openai-api-key。

適用於誰

• 用 OpenAI API 做聊天介面、寫作工具，希望文字邊生成邊顯示的開發者；
• 已經能發出第一個請求（見 /guides/openai-api-python-quickstart），想了解流式事件到底是什麼的人；
• 用 Node.js / TypeScript 的前端或全棧開發者。

結論先說

1. 預設不是流式的。 官方說，普通請求會等整個輸出生成完才一次性返回，輸出長的時候要等。
2. 流式的寫法：在 Responses 請求裏加 stream=True（Node 裏是 stream: true），得到的不是一個結果，而是一串事件。
3. 事件是帶類型的，用 event.type 區分。寫文本時常看四個：response.created、response.output_text.delta、response.completed、error。
4. 文字增量在 response.output_text.delta 裏，用 event.delta 取。
5. 流式讓內容審核更難。 官方明確提醒，生產應用裏流式輸出會讓部分內容更難評估，審核分數也要等完整輸出生成後才有。

圖：本站根據 OpenAI 官方《Streaming API responses》 整理的示意圖

一、事件長什麼樣

官方說，Responses API 用語義事件來流式返回，每種事件有預先定義的結構。其中有的只出現一次，有的會隨着生成多次出現：

• response.created：響應開始創建，出現一次；
• response.output_text.delta：一小段新文字，出現很多次；
• response.completed：整個響應完成，出現一次；
• error：出錯。

完整事件列表見官方 API 參考裏的 streaming 部分，正文不全部列出。

二、Python 示例

先安裝並設定密鑰（Windows 的設定方式見 /guides/openai-api-key）：

pip install openai

python
from openai import OpenAI

client = OpenAI()  # 從環境變量 OPENAI_API_KEY 讀取密鑰

stream = client.responses.create(
    model="gpt-6-astra",  # 以官方模型頁當天為準
    input="用三句話介紹什麼是流式輸出。",
    stream=True,
)

full_text = ""
for event in stream:
    if event.type == "response.output_text.delta":
        full_text += event.delta
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n--- 完成 ---")
    elif event.type == "error":
        print("\n出錯：", event.message)

print("完整文本長度：", len(full_text))

flush=True 讓文字立即顯示在終端裏。full_text 把增量拼起來，方便流結束後儲存或再處理。

三、Node.js 示例

新建一個 stream.mjs 文件（.mjs 可以直接使用 import 和頂層 await）：

npm install openai

javascript
import OpenAI from "openai";

const client = new OpenAI(); // 從環境變量 OPENAI_API_KEY 讀取密鑰

const stream = await client.responses.create({
  model: "gpt-6-astra", // 以官方模型頁當天為準
  input: "用三句話介紹什麼是流式輸出。",
  stream: true,
});

let fullText = "";
for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    fullText += event.delta;
    process.stdout.write(event.delta);
  } else if (event.type === "response.completed") {
    console.log("\n--- 完成 ---");
  } else if (event.type === "error") {
    console.error(event.message);
  }
}
console.log("完整文本長度：", fullText.length);

運行：node stream.mjs。官方示例裏的判斷結構與上面一致。

四、常見的幾個坑

圖：本站根據 OpenAI 官方《Streaming API responses》 整理的示意圖，排查表為本站補充

• 什麼也沒顯示：檢查有沒有真的加 stream=True；再檢查有沒有隻打印 response.completed 之類的事件，漏掉了 response.output_text.delta；
• 文字還是一次性出來：終端沒有立即刷新（Python 要 flush=True），或者中間的代理、網關把響應緩衝了；
• 中途斷掉：把已收到的文本先儲存，再按業務決定要不要重試。重試會重新計費，429 等限流問題見 /guides/openai-api-429-error；
• 要儲存完整答案：像示例那樣拼接增量，或者在 response.completed 事件裏讀完整響應；
• 想知道用了多少 token：用量見 /guides/openai-api-pricing-billing，價格以官方頁面當前顯示為準。

五、要給用戶看，怎麼轉給瀏覽器

官方流式頁講的是 API 和伺服器之間的流。網頁前端怎麼拿到，官方這一頁沒有展開。本站的一般性建議：密鑰只放在你自己的伺服器上，不要寫進網頁或手機 App；伺服器收到 OpenAI 的事件後，用你自己的方式（例如伺服器發送事件或 WebSocket）轉給前端，只轉發文字增量就夠了。

官方提到的另外兩個方向：想要持久的 WebSocket 連接並用 previous_response_id 增量輸入，看官方的 Responses WebSocket 模式；流式的函數調用和結構化輸出，官方另有專門的指南。

六、關於審核風險

官方在流式頁專門有一節“Moderation risk”：生產應用裏流式輸出會讓內容審核更困難，因為部分輸出更難評估，這可能影響獲批的使用。如果在生成請求時請求審核分數，分數會在完整輸出可用後才到，不會跟着增量事件一起出現。

所以做面向公眾的產品時，要把審核放進設計裏，比如先在伺服器收齊、檢查，再決定怎麼展示，具體做法以官方審核指南為準。

什麼時候值得用流式

• 適合：聊天介面、寫作助手、需要讓用戶儘早看到開頭的長回答。官方的理由就是：模型還在繼續生成時，你已經可以開始顯示或處理開頭部分；
• 不一定需要：後台批處理、只需要最終結果的腳本、要先整體校驗再使用的輸出。這些場景用普通請求更簡單，代碼也更短；
• 需要先想清楚：出錯後怎麼辦。非流式請求要麼成功要麼失敗，流式請求可能已經給用戶顯示了一半文字才斷開，介面上要有“生成中斷、重試”的處理，這是本站的一般性建議。

常見問題

Q：舊資料裏的 Chat Completions 流式寫法還能用嗎？

官方流式頁對 Chat Completions 單獨有一段：流式返回的是 chunk.choices[0].delta，取的是 delta 裏的內容，和 Responses 的 event.delta 不是一回事。新項目建議優先用 Responses，兩者區別見 /guides/openai-responses-api。

Q：流式會比非流式貴嗎？

官方流式頁沒有這樣說明，計費看的是用量，以官方價格頁為準，見 /guides/openai-api-price-official-table。

Q：模型名報錯怎麼辦？

示例模型名會更新，先到官方模型頁確認你的帳號可用的模型。

參考資料

• OpenAI 官方：Streaming API responses — https://platform.openai.com/docs/guides/streaming-responses
• OpenAI 官方：Quickstart — https://developers.openai.com/api/docs/quickstart