如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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.104.0。 对于 Java,请添加 Maven 依赖 com.openai:openai-java:4.105.0,并使用 Java 17 或更高版本运行这些示例。 这些版本的 Go 和 Java SDK 原生支持 Responses API 的 WebSocket 模式。

在 WebSocket 模式下,客户端通过发送 response.create 事件开始每一轮对话。事件载荷与常规的创建响应请求体一致,但不使用 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.2-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.2-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 模式与 HTTP 模式使用相同的 previous_response_id 规则来串联响应,同时支持在当前打开的套接字上以更低的延迟接续对话。

在活动的 WebSocket 连接上,服务会将近期响应的状态保存在该连接专属的内存缓存中。使用 stream_id 时,每个通道都会缓存其最新响应。从该通道的最新响应接续时,服务可以复用当前连接中缓存的状态,因此接续速度很快。由于服务仅在内存中保留先前响应的状态,不将其写入磁盘,因此您可以在使用 store=false 或启用零数据保留(ZDR)的情况下使用 WebSocket 模式。

如果在内存缓存中找不到 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。压缩完成后,在 WebSocket 连接上创建新响应,将压缩后的窗口用作 input,并追加接下来的用户消息或工具项。

省略 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.2-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.2-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.2-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
}

相关指南