如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

WebSocket 模式

透過單一持續開啟的 WebSocket 連線平行執行多個對話、從回應鏈建立分支,並以增量方式傳送輸入,降低智慧體工作流程的延遲。

Responses API 支援 WebSocket 模式,適合執行時間長且需要頻繁呼叫工具的工作流程。除了降低延遲,還可以透過 stream_id 在 WebSocket 連線上進行多工處理:只要持續開啟一條連至 /v1/responses 的連線,就能平行執行多個對話,也能從現有對話建立分支,在新的串流上繼續。接續每一輪時,只需傳送新增的輸入項目和 previous_response_id。

WebSocket 模式支援零資料保留(ZDR),也支援 store=false。

為什麼使用 WebSocket 模式

當工作流程需要模型與工具反覆往返時,WebSocket 模式最能發揮效益,例如智慧體式程式碼編寫,或反覆呼叫工具的編排迴圈。

由於連線會保持開啟,而且每一輪只傳送新增的輸入,WebSocket 模式能減少接續每一輪的額外開銷,降低整條長回應鏈的端對端延遲。在包含 20 次以上工具呼叫的執行過程中,我們觀察到端對端執行速度最多可提升約 40%。

建立連線與回應

依使用的語言安裝 WebSocket 相依套件。Python 請執行 pip install "openai[realtime]>=3.8.0",JavaScript 請執行 npm install openai@^7.10.0 ws,Ruby 請執行 gem install openai async-websocket。

若使用 Go,請執行 go get github.com/openai/openai-go/v3@v3.98.0。 若使用 Java,請加入 Maven 相依套件 com.openai:openai-java:4.101.0,並使用 Java 17 或更新版本執行這些範例。 上述 Go 和 Java SDK 版本皆原生支援 Responses WebSocket。

在 WebSocket 模式中,每一輪都由用戶端傳送 response.create 事件來啟動。事件承載的資料與一般的 Responses 建立請求主體 相同,但不使用 stream 和 background 等傳輸方式專用的欄位。

import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();

const ws = new ResponsesWS(client);
try {
  ws.send({
    type: "response.create",
    stream_id: "main",
    model: "gpt-6-astra",
    store: false,
    input: [
      {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "Find fizz_buzz()" }],
      },
    ],
    tools: [],
  });
  let completed = false;
  for await (const event of ws) {
    if (event.type === "error") throw event.error;
    if (event.type !== "message") continue;
    const message = event.message;
    if (message.type === "response.output_text.delta") {
      process.stdout.write(message.delta);
    } else if (message.type === "response.completed") {
      completed = true;
      break;
    } else if (
      message.type === "response.failed" ||
      message.type === "response.incomplete"
    ) {
      throw new Error(JSON.stringify(message));
    }
  }
  if (!completed)
    throw new Error("Connection closed before the response finished.");
} finally {
  ws.close();
}

用戶端也可以傳送 response.create 並指定 generate: false,預先準備請求狀態。如果你已經知道接下來某一輪要傳送哪些工具、指令或自訂訊息,就可以採用這個做法。指定 generate: false 時,服務不會傳回模型輸出,但會準備好請求狀態,讓下一輪更快開始產生回應。預先準備狀態的請求會傳回一個回應 ID。你可以將 previous_response_id 設為這個 ID,從該回應接續,也可以在回應鏈後續的回合這麼做。下一節說明如何使用 previous_response_id 和增量輸入接續工作階段。

使用增量輸入接續對話

若要在回應仍在產生時加入使用者指令,請使用回合中引導。這項功能會保留已完成的工作,並在接續執行時納入新指令。若要在回合之間接續對話或傳送工具結果,請依照下列範例使用 response.create。

若要接續執行,請再傳送一個 response.create 事件,並設定下列欄位:

  • 將 previous_response_id 設為前一個回應的 ID。
  • 在 input 中只放入新增的項目,例如工具輸出和下一則使用者訊息。
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();
const model = "gpt-6-astra";

const tools: OpenAI.Responses.Tool[] = [
  {
    type: "function",
    name: "get_test_results",
    description: "Return a local demo test result.",
    parameters: { type: "object", properties: {}, additionalProperties: false },
    strict: true,
  },
];

async function waitForResponse(ws: ResponsesWS) {
  for await (const event of ws) {
    if (event.type === "error") throw event.error;
    if (event.type !== "message") continue;
    const message = event.message;
    if (message.type === "response.output_text.delta") {
      process.stdout.write(message.delta);
    } else if (message.type === "response.completed") {
      return message.response;
    } else if (
      message.type === "response.failed" ||
      message.type === "response.incomplete"
    ) {
      throw new Error(JSON.stringify(message));
    }
  }
  throw new Error("Connection closed before the response finished.");
}

const ws = new ResponsesWS(client);
try {
  ws.send({
    type: "response.create",
    stream_id: "main",
    model,
    store: false,
    input: "Find the failing test and suggest a fix.",
    tools,
    tool_choice: { type: "function", name: "get_test_results" },
    parallel_tool_calls: false,
  });
  const first = await waitForResponse(ws);
  const call = first.output.find((item) => item.type === "function_call");
  if (!call || call.name !== "get_test_results") {
    throw new Error("Expected a get_test_results function call.");
  }
  const result = {
    test: "test_fizz_buzz",
    failure: 'Expected "FizzBuzz" for 15, got "Fizz".',
  };

  // Continue on the same socket with the actual response and tool-call IDs.
  ws.send({
    type: "response.create",
    stream_id: "main",
    model,
    store: false,
    previous_response_id: first.id,
    input: [
      {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(result),
      },
      { role: "user", content: "Now optimize it." },
    ],
    tools,
    tool_choice: "none",
  });
  await waitForResponse(ws);
} finally {
  ws.close();
}

接續回應的運作方式

WebSocket 模式使用 previous_response_id 串接回應的方式與 HTTP 模式相同,但可以透過仍開啟的連線,以較低的延遲接續回應。

WebSocket 連線開啟期間,服務會將近期回應的狀態保存在該連線專屬的記憶體快取中。使用 stream_id 時,每個通道都會快取自己的最新回應。從該回應接續時,服務可以重用這條連線上的狀態,加快接續速度。服務只在記憶體中保留先前的回應狀態,不會將其寫入磁碟,因此 WebSocket 模式可搭配 store=false 和零資料保留(ZDR)使用。

如果記憶體快取中找不到 previous_response_id,服務的行為取決於你是否儲存回應:

  • 使用 store=true 時,如果仍有已儲存的狀態,服務可能會從中載入較舊回應 ID 對應的狀態。此時仍可能接續回應,但無法享有記憶體快取帶來的低延遲。
  • 使用 store=false(含 ZDR)時,沒有已儲存的狀態可供還原。如果快取中沒有該 ID,請求會傳回 previous_response_not_found。

如果在同一通道上接續回應時傳回 4xx 或 5xx,服務會從該連線的快取中移除 previous_response_id 所指的回應。如果跨通道建立分支時傳回錯誤,服務會保留共用的父回應,讓來源通道可以繼續執行。

壓縮上下文與建立新回應

使用壓縮時,有兩種不同的接續方式:

伺服器端壓縮(context_management)

啟用伺服器端壓縮後(在 context_management 中指定 compact_threshold),壓縮會在 /responses 正常產生回應的過程中進行。在 WebSocket 模式下,照常接續即可:傳送下一個 response.create 事件,帶上最新的 previous_response_id,並只提供新增的輸入項目。

獨立的 /responses/compact

獨立的 /responses/compact 端點 會傳回壓縮後的新輸入視窗,而非回應 ID。壓縮完成後,請將該視窗連同下一批使用者或工具項目放入 input,在 WebSocket 連線上建立新回應。

省略 previous_response_id 或將其設為 null,即可開始新的回應鏈。請原樣傳入壓縮後的輸出,不要刪減傳回的視窗內容。

import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

// Compact your current window with an HTTP request.
const compacted = await client.responses.compact({
  model: "gpt-6-astra",
  input: longInputItems,
});
const nextInput = toResponseInputItems(compacted.output);
nextInput.push({
  type: "message",
  role: "user",
  content: [{ type: "input_text", text: "Continue from here." }],
});

// Start a new response on the WebSocket using the compacted window.
const ws = new ResponsesWS(client);
try {
  ws.send({
    type: "response.create",
    stream_id: "main",
    model: "gpt-6-astra",
    store: false,
    input: nextInput,
    tools: [],
  });
  let completed = false;
  for await (const event of ws) {
    if (event.type === "error") throw event.error;
    if (event.type !== "message") continue;
    const message = event.message;
    if (message.type === "response.output_text.delta") {
      process.stdout.write(message.delta);
    } else if (message.type === "response.completed") {
      completed = true;
      break;
    } else if (
      message.type === "response.failed" ||
      message.type === "response.incomplete"
    ) {
      throw new Error(JSON.stringify(message));
    }
  }
  if (!completed)
    throw new Error("Connection closed before the response finished.");
} finally {
  ws.close();
}

平行執行多個對話

使用 stream_id 參數,就能在同一條連線上維持多個平行對話。請接連傳送彼此獨立的 response.create 事件,並分別指定不同的 stream_id 值。伺服器可以在同一條連線上同時執行這些請求。由於各個對話的事件可能交錯抵達,請使用單一迴圈讀取事件,再依 stream_id 分派每個事件。

stream_id 用來識別同一條 WebSocket 連線上依序處理請求的通道。請區分 stream_id 和 previous_response_id 的用途:

  • stream_id 決定事件要送往哪個通道,以及哪些請求要依先進先出的順序執行。
  • previous_response_id 決定對話要從哪個回應接續。

兩者分工後,就能在同一條連線上平行執行獨立對話,也能從既有對話建立分支。

一條 WebSocket 連線
├─ stream_id="planner"   擬定部署計畫
└─ stream_id="research"  列出部署風險

具有相同 stream_id 的請求會依先進先出的順序執行,執行時間不會重疊。具有不同 stream_id 值的請求則可以同時執行。

每條連線的限制

  • 在同一條連線上,具名通道與預設通道合計最多可同時有 16 個進行中的回應。連線仍會接受更多 response.create 事件,並將其排入佇列,直到有進行中的回應完成。
  • 每條連線最多接受 32 個不同的具名 stream_id 值。隱含的預設通道不計入具名串流的上限。達到上限後,請重用現有的 stream_id 或開啟新連線。

從對話建立分支並在新串流上執行

若要從已完成的回應建立分支,請將該回應的 ID 作為 previous_response_id,連同新的 stream_id 一起傳送。只要該回應仍可供使用,新串流就能繼承其上下文,原本的串流也可以繼續執行。分支啟動後,兩個分支使用不同的串流 ID,因此可以同時執行。

使用 store=false(含 ZDR)時,只有在該連線的快取中仍有父回應的情況下,才能跨通道建立分支。如果建立分支的請求仍在佇列中等候,而來源通道在此期間進入下一輪或發生錯誤,父回應可能會在分支啟動前從快取中移除,此時建立分支的請求會傳回 previous_response_not_found。請等到分支通道發出 response.in_progress 事件,再讓來源通道進入下一輪。你也可以在重試時將 previous_response_id 設為 null,並重新傳送完整的輸入上下文。

main:   resp_1 ──▶ resp_2 ──▶ resp_3
                       ╲
critic:                 resp_4 ──▶ resp_5

重用 stream_id 但未提供 previous_response_id 時,會建立新的回應,不會接續原本的對話。

主要呼叫如下:

# 在同一條連線上執行兩個獨立的對話。
send_create(connection, "planner", "擬定部署計畫。")
send_create(connection, "research", "列出部署風險。")

# 從 planner 的回應建立分支,再接續原本的分支,讓兩者平行執行。
send_create(
    connection,
    "critic",
    "找出這份計畫的疏漏。",
    previous_response_id=planner_response_id,
)
wait_for_in_progress(connection, "critic")
send_create(
    connection,
    "planner",
    "補上回復至先前版本的步驟。",
    previous_response_id=planner_response_id,
)

完整範例

平行執行多個對話,再從其中一個建立分支
import OpenAI from "openai";
import type { ResponsesStreamMessage } from "openai/resources/responses/internal-base.mjs";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();

const latestResponseIdByLane = new Map();

function sendCreate(
  ws: ResponsesWS,
  streamId: string,
  text: string,
  previousResponseId = latestResponseIdByLane.get(streamId)
) {
  ws.send({
    type: "response.create",
    stream_id: streamId,
    model: "gpt-6-astra",
    store: false,
    input: [
      {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text }],
      },
    ],
    previous_response_id: previousResponseId,
  });
}

async function readMessage(
  events: AsyncIterableIterator<ResponsesStreamMessage>
) {
  while (true) {
    const { value: event, done } = await events.next();
    if (done)
      throw new Error("Connection closed before all responses finished.");
    if (event.type === "error") throw event.error;
    if (event.type !== "message") continue;
    const message = event.message;
    if (
      message.type === "response.failed" ||
      message.type === "response.incomplete"
    ) {
      throw new Error(
        `Lane ${message.stream_id} failed: ${JSON.stringify(message)}`
      );
    }
    return message;
  }
}

async function drainUntilComplete(
  events: AsyncIterableIterator<ResponsesStreamMessage>,
  expectedStreamIds: Iterable<unknown> | null | undefined
) {
  const remaining = new Set(expectedStreamIds);
  while (remaining.size > 0) {
    const message = await readMessage(events);
    const streamId = message.stream_id;
    if (!streamId || !remaining.has(streamId)) continue;
    if (message.type === "response.completed") {
      latestResponseIdByLane.set(streamId, message.response.id);
      remaining.delete(streamId);
    }
  }
}

async function waitForInProgress(
  events: AsyncIterableIterator<ResponsesStreamMessage>,
  streamId: string
) {
  while (true) {
    const message = await readMessage(events);
    if (
      message.type === "response.in_progress" &&
      message.stream_id === streamId
    )
      return;
  }
}

const ws = new ResponsesWS(client);
// Keep one iterator so events stay queued while moving between phases.
const events = ws.stream();
try {
  // Run two independent conversations in parallel.
  sendCreate(
    ws,
    "planner",
    "Draft a deployment plan for a stateless API service."
  );
  sendCreate(
    ws,
    "research",
    "List common deployment risks for a stateless API service."
  );
  await drainUntilComplete(events, new Set(["planner", "research"]));

  // Fork the planner conversation and continue its original branch in parallel.
  const plannerResponseId = latestResponseIdByLane.get("planner");
  sendCreate(
    ws,
    "critic",
    "Find gaps in this deployment plan.",
    plannerResponseId
  );
  // Let the fork load its parent before advancing the original lane's cache.
  await waitForInProgress(events, "critic");
  sendCreate(
    ws,
    "planner",
    "Add rollback and monitoring steps to the plan.",
    plannerResponseId
  );
  await drainUntilComplete(events, new Set(["critic", "planner"]));
} finally {
  await events.return?.();
  ws.close();
}

stream_id 的長度必須介於 1 到 256 個字元之間,且只能包含字母、數字、底線(_)、連字號(-)和句點(.)。請只在 WebSocket 的 response.create 事件中使用這個欄位,不要在 HTTP POST /v1/responses 請求中加入它。

對於具名串流,伺服器事件會包含對應的 stream_id,結束事件和個別請求的錯誤事件也不例外。

如果省略 stream_id,請求會使用隱含的預設通道,其事件不會包含 stream_id。除此之外,預設通道的排序與並行規則與具名串流相同。空字串不是有效的 stream_id 值。若要選用預設通道,請省略這個欄位。

連線行為與限制

  • 每個回應中的事件都遵循既有的 Responses 串流事件模型。不同通道的事件可能交錯出現。
  • 具有相同 stream_id 的請求會依先進先出的順序執行,執行時間不會重疊。不同通道上的請求可以同時執行。
  • 每條連線最多可維持 60 分鐘。達到上限時,請重新連線。

重新連線並恢復執行

當連線關閉或達到 60 分鐘上限時,該連線上所有通道的快取都會消失。請開啟新的 WebSocket 連線,並依各通道的情況選用下列方式恢復執行:

  1. 如果先前已儲存回應(store=true),而且有有效的回應 ID,請使用 previous_response_id 和新增的輸入項目接續該通道的對話。
  2. 如果無法接續某個通道的對話(例如使用 store=false 或 ZDR,或收到 previous_response_not_found),請將 previous_response_id 設為 null(或省略該欄位)以建立新回應,並傳送該通道下一輪所需的完整輸入上下文。
  3. 如果已使用 /responses/compact 壓縮上下文,請以傳回的壓縮視窗作為新回應的基礎 input,再附加最新的使用者或工具項目。

需要處理的錯誤

如果伺服器能判定錯誤屬於哪個具名通道,錯誤事件就會包含 stream_id。個別請求發生錯誤後,其他通道仍可繼續執行。

previous_response_not_found

{
  "type": "error",
  "status": 400,
  "stream_id": "main",
  "error": {
    "type": "invalid_request_error",
    "code": "previous_response_not_found",
    "message": "Previous response with id 'resp_abc' not found.",
    "param": "previous_response_id"
  }
}

invalid_stream_id

{
  "type": "error",
  "status": 400,
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_stream_id",
    "message": "The 'stream_id' field must be a non-empty string with at most 256 characters and may only contain letters, numbers, underscores, hyphens, and periods.",
    "param": "stream_id"
  }
}

websocket_stream_limit_reached

{
  "type": "error",
  "status": 400,
  "stream_id": "agent_33",
  "error": {
    "type": "invalid_request_error",
    "code": "websocket_stream_limit_reached",
    "message": "This WebSocket connection has reached its maximum number of distinct stream IDs (32). Reuse an existing stream_id or open a new WebSocket connection.",
    "param": "stream_id"
  }
}

websocket_connection_limit_reached

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "websocket_connection_limit_reached",
    "message": "Responses websocket connection limit reached (60 minutes). Create a new websocket connection to continue."
  },
  "status": 400
}

相關指南