codecamp

OpenAI Responses WebSocket 模式

Responses API 的 WebSocket 模式适合运行时间长、工具调用频繁的工作流。除降低延迟外,stream_id 支持多路复用:一条连接到 /v1/responses 的持久连接,可运行并行对话,也可把既有对话分叉到新流。每轮只发送新输入项和 previous_response_id 即可继续。

此模式兼容零数据保留(ZDR)与 store=false。

为什么使用 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.94.0,Java 添加 Maven 依赖 com.openai:openai-java:4.98.0。这些 Go、Java 版本原生支持 Responses WebSocket。

每轮从客户端发送 response.create。载荷与普通 Responses 创建请求体相同,但不使用 stream、background 等传输相关字段。

来源示例 1(javascript):

程序文字译释265:查找fizz_buzz()函数。

程序文字译释266:响应完成前连接已关闭。

// [中文] 示例 1:连接并创建响应;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:ws.send、ws.close;异步调用及事件接收顺序保留。
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();
}

来源示例 2(python):

沿用程序文字译释265。

## [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
from openai import OpenAI

client = OpenAI()

with client.responses.connect() as connection:
    connection.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=[],
    )
    for event in connection:
        if event.type == "response.completed":
            print(event.response.output_text)
            break
        if event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(event.to_json())
    else:
        raise RuntimeError("Connection closed before the response finished.")

来源示例 3(go):

沿用程序文字译释265。

程序文字译释267:响应以指定状态结束。

// [中文] 示例 3:连接并创建响应;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 沿原示例执行这些方法:client.Responses.Connect;异步调用及事件接收顺序保留。
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
    log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
    Model: "gpt-6-astra",
    Store: openai.Bool(false),
    Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
        OfString: openai.String("Find fizz_buzz()"),
    },
    StreamID: openai.String("main"),
    Tools:    []responses.ToolUnionParam{},
}); err != nil {
    log.Fatal(err)
}
response, err := conn.FinalResponse(ctx)
if err != nil {
    log.Fatal(err)
}
if response.Status != responses.ResponseStatusCompleted {
    log.Fatalf("Response ended with status %s", response.Status)
}
fmt.Println(response.OutputText())

来源示例 4(java):

程序文字译释55:响应以所示状态结束。

沿用程序文字译释265。

// [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
// [中文] 本段为配置或调用片段,需结合外层程序与已建立连接使用;不作为独立完整程序宣称编译通过。
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.*;
import java.util.*;

var client = OpenAIOkHttpClient.fromEnv();

try (var conn = client.responses().connect()) {
  conn.send(
      ResponsesClientEvent.ofResponseCreate(
          ResponsesClientEvent.ResponseCreate.builder()
              .model("gpt-6-astra")
              .store(false)
              .input("Find fizz_buzz()")
              .streamId("main")
              .tools(List.of())
              .build()));
  var response = conn.finalResponse();
  if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
    throw new IllegalStateException(
        "Response ended with status " + response.status().orElse(null));
  response.output().stream()
      .flatMap(item -> item.message().stream())
      .flatMap(message -> message.content().stream())
      .flatMap(content -> content.outputText().stream())
      .forEach(text -> System.out.println(text.text()));
} finally {
  client.close();
}

来源示例 5(ruby):

沿用程序文字译释265。

程序文字译释268:响应失败,后接事件JSON。

程序文字译释269:响应结束前连接已关闭。

## [中文] 示例 5:连接并创建响应;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
require "async"
require "openai"

def wait_for_response(connection)
  while (event = connection.receive)
    case event.type.to_s
    when "response.completed" then return event.response
    when "response.failed", "response.incomplete", "error"
      raise "Response failed: #{event.to_json}"
    end
  end
  raise "Connection closed before the response finished"
end

client = OpenAI::Client.new
Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      connection.response.create(
        stream_id: "main", model: "gpt-6-astra", store: false,
        input: [
          {
            role: "user",
            content: "Find fizz_buzz()"
          }
        ], tools: []
      )
      puts(wait_for_response(connection).output_text)
    end
  end
end

可选发送 generate: false 的 response.create 预热请求状态,适合预先知道下一轮工具、指令或消息的情况。它不返回模型输出,而是准备状态,让后续生成更快。预热返回响应 ID,可用 previous_response_id 链接,包括链中较后的轮次。增量续接见下文。

用增量输入继续

响应仍在运行时要追加用户指令,使用轮次中途引导,保留已完成工作并在续接中纳入新指令。普通轮次间续接与工具结果采用以下模式:

  • previous_response_id 设为上一响应 ID。
  • input 只包含新增项,例如工具输出和下一条用户消息。

来源示例 6(javascript):

沿用程序文字译释266。

程序文字译释270:返回本地演示测试结果。

程序文字译释271:找到失败的测试并建议修复。

程序文字译释272:预期get_test_results函数调用。

程序文字译释273:现在优化它。

// [中文] 示例 6:用增量输入继续;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:ws.send、ws.close;异步调用及事件接收顺序保留。
// [中文] 返回函数结果时保留对应 call_id;响应继续事件与结果项目是两个独立步骤。
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

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

const tools = [
  {
    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) {
  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();
}

来源示例 7(python):

沿用程序文字译释266。

沿用程序文字译释271。

沿用程序文字译释273。

程序文字译释274:读取演示测试结果。

程序文字译释275:预期无参数get_test_results调用。

## [中文] 示例 7:用增量输入继续;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
## [中文] 返回函数结果时保留对应 call_id;响应继续事件与结果项目是两个独立步骤。
import json

from openai import OpenAI
from openai.resources.responses.responses import ResponsesConnection
from openai.types.responses import FunctionToolParam, Response

client = OpenAI()
model = "gpt-6-astra"
tools: list[FunctionToolParam] = [
    {
        "type": "function",
        "name": "get_test_results",
        "description": "Read the demo test results.",
        "parameters": {
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": False,
        },
        "strict": True,
    }
]


def get_test_results():
    # Demo data. Replace this function with your test runner.
    return {
        "test": "test_fizz_buzz",
        "failure": 'Expected "FizzBuzz" for 15, got "Fizz".',
    }


def wait_for_response(connection: ResponsesConnection) -> Response:
    for event in connection:
        if event.type == "response.completed":
            return event.response
        if event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(event.to_json())
    raise RuntimeError("Connection closed before the response finished.")


with client.responses.connect() as connection:
    connection.response.create(
        stream_id="main",
        model=model,
        store=False,
        input="Find the failing test and suggest a fix.",
        tools=tools,
        tool_choice={"type": "function", "name": "get_test_results"},
        parallel_tool_calls=False,
    )
    response = wait_for_response(connection)
    call = next(item for item in response.output if item.type == "function_call")
    if call.name != "get_test_results" or json.loads(call.arguments) != {}:
        raise ValueError("Expected a get_test_results call with no arguments")

    # Continue on the same connection using the actual response and tool-call IDs.
    connection.response.create(
        stream_id="main",
        model=model,
        store=False,
        previous_response_id=response.id,
        input=[
            {
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(get_test_results()),
            },
            {"role": "user", "content": "Now optimize it."},
        ],
        tools=tools,
        tool_choice="none",
    )
    print(wait_for_response(connection).output_text)

来源示例 8(go):

沿用程序文字译释267。

沿用程序文字译释270。

沿用程序文字译释271。

沿用程序文字译释273。

程序文字译释276:预期get_test_results函数调用。

// [中文] 示例 8:用增量输入继续;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 沿原示例执行这些方法:client.Responses.Connect;异步调用及事件接收顺序保留。
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
tools := []responses.ToolUnionParam{
    {
        OfFunction: &responses.FunctionToolParam{
            Name:        "get_test_results",
            Description: openai.String("Return a local demo test result."),
            Parameters: map[string]any{
                "type":                 "object",
                "properties":           map[string]any{},
                "additionalProperties": false,
            },
            Strict: openai.Bool(true),
        },
    },
}
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
    log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
    Model: "gpt-6-astra",
    Store: openai.Bool(false),
    Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
        OfString: openai.String("Find the failing test and suggest a fix."),
    },
    StreamID:          openai.String("main"),
    Tools:             tools,
    ParallelToolCalls: openai.Bool(false),
    ToolChoice: responses.ResponsesClientEventResponseCreateToolChoiceUnionParam{
        OfFunctionTool: &responses.ToolChoiceFunctionParam{
            Name: "get_test_results",
        },
    },
}); err != nil {
    log.Fatal(err)
}
first, err := conn.FinalResponse(ctx)
if err != nil {
    log.Fatal(err)
}
if first.Status != responses.ResponseStatusCompleted {
    log.Fatalf("Response ended with status %s", first.Status)
}
var callID string
for _, item := range first.Output {
    if item.Type == "function_call" && item.Name == "get_test_results" {
        callID = item.CallID
        break
    }
}
if callID == "" {
    log.Fatal("Expected a get_test_results function call")
}
// The result is a local demo fixture; carry the real response and call IDs.
result := `{"test":"test_fizz_buzz","failure":"Expected FizzBuzz for 15, got Fizz."}`
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
    Model:              "gpt-6-astra",
    StreamID:           openai.String("main"),
    Store:              openai.Bool(false),
    PreviousResponseID: openai.String(first.ID),
    Tools:              tools,
    ToolChoice: responses.ResponsesClientEventResponseCreateToolChoiceUnionParam{
        OfToolChoiceMode: openai.Opt(responses.ToolChoiceOptionsNone),
    },
    Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
        OfResponse: &responses.ResponseInputParam{
            {
                OfFunctionCallOutput: &responses.ResponseInputItemFunctionCallOutputParam{
                    CallID: openai.String(callID),
                    Output: responses.ResponseInputItemFunctionCallOutputOutputUnionParam{
                        OfString: openai.String(result),
                    },
                },
            },
            responses.ResponseInputItemParamOfMessage("Now optimize it.", responses.EasyInputMessageRoleUser),
        },
    },
}); err != nil {
    log.Fatal(err)
}
response, err := conn.FinalResponse(ctx)
if err != nil {
    log.Fatal(err)
}
if response.Status != responses.ResponseStatusCompleted {
    log.Fatalf("Response ended with status %s", response.Status)
}
fmt.Println(response.OutputText())

来源示例 9(java):

沿用程序文字译释55。

沿用程序文字译释270。

沿用程序文字译释271。

沿用程序文字译释273。

程序文字译释277:预期get_test_results调用。

程序文字译释278:测试test_fizz_buzz失败:输入15预期FizzBuzz,实际得到Fizz。

// [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
// [中文] 本段为配置或调用片段,需结合外层程序与已建立连接使用;不作为独立完整程序宣称编译通过。
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.*;
import java.util.*;

var client = OpenAIOkHttpClient.fromEnv();

var tool =
    FunctionTool.builder()
        .name("get_test_results")
        .description("Return a local demo test result.")
        .strict(true)
        .parameters(
            FunctionTool.Parameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty("properties", JsonValue.from(Map.of()))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .build();
try (var conn = client.responses().connect()) {
  conn.send(
      ResponsesClientEvent.ofResponseCreate(
          ResponsesClientEvent.ResponseCreate.builder()
              .model("gpt-6-astra")
              .store(false)
              .input("Find the failing test and suggest a fix.")
              .streamId("main")
              .addTool(tool)
              .parallelToolCalls(false)
              .toolChoice(ToolChoiceFunction.builder().name("get_test_results").build())
              .build()));
  var first = conn.finalResponse();
  if (first.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
    throw new IllegalStateException(
        "Response ended with status " + first.status().orElse(null));
  var call =
      first.output().stream()
          .flatMap(item -> item.functionCall().stream())
          .filter(item -> item.name().equals("get_test_results"))
          .findFirst()
          .orElseThrow(() -> new IllegalStateException("Expected get_test_results call"));
  // Use the real response and call IDs with a local demo result.
  var result =
      "{\"test\":\"test_fizz_buzz\",\"failure\":\"Expected FizzBuzz for 15, got Fizz.\"}";
  conn.send(
      ResponsesClientEvent.ofResponseCreate(
          ResponsesClientEvent.ResponseCreate.builder()
              .model("gpt-6-astra")
              .streamId("main")
              .store(false)
              .previousResponseId(first.id())
              .addTool(tool)
              .toolChoice(ToolChoiceOptions.NONE)
              .inputOfResponse(
                  List.of(
                      ResponseInputItem.ofFunctionCallOutput(
                          ResponseInputItem.FunctionCallOutput.builder()
                              .callId(call.callId())
                              .output(result)
                              .build()),
                      ResponseInputItem.ofEasyInputMessage(
                          EasyInputMessage.builder()
                              .role(EasyInputMessage.Role.USER)
                              .content("Now optimize it.")
                              .build())))
              .build()));
  var response = conn.finalResponse();
  if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty())
    throw new IllegalStateException(
        "Response ended with status " + response.status().orElse(null));
  response.output().stream()
      .flatMap(item -> item.message().stream())
      .flatMap(message -> message.content().stream())
      .flatMap(content -> content.outputText().stream())
      .forEach(text -> System.out.println(text.text()));
} finally {
  client.close();
}

来源示例 10(ruby):

沿用程序文字译释268。

沿用程序文字译释269。

沿用程序文字译释271。

沿用程序文字译释273。

沿用程序文字译释274。

沿用程序文字译释275。

## [中文] 示例 10:用增量输入继续;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
## [中文] 返回函数结果时保留对应 call_id;响应继续事件与结果项目是两个独立步骤。
require "async"
require "openai"
require "json"

def wait_for_response(connection)
  while (event = connection.receive)
    case event.type.to_s
    when "response.completed" then return event.response
    when "response.failed", "response.incomplete", "error"
      raise "Response failed: #{event.to_json}"
    end
  end
  raise "Connection closed before the response finished"
end

tools = [
  {
    type: "function",
    name: "get_test_results",
    description: "Read the demo test results.",
    parameters: {
      type: "object",
      properties: {},
      required: [],
      additionalProperties: false
    },
    strict: true
  }
]

client = OpenAI::Client.new
Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      connection.response.create(
        stream_id: "main", model: "gpt-6-astra", store: false,
        input: "Find the failing test and suggest a fix.", tools: tools,
        tool_choice: {
          type: "function",
          name: "get_test_results"
        }, parallel_tool_calls: false
      )
      response = wait_for_response(connection)
      call = response.output.grep(OpenAI::Responses::ResponseFunctionToolCall).first
      unless call && call.name == "get_test_results" && JSON.parse(call.arguments) == {}
        raise "Expected a get_test_results call with no arguments"
      end

      # Demo data. Replace this with your test runner.
      result = {
        test: "test_fizz_buzz",
        failure: 'Expected "FizzBuzz" for 15, got "Fizz".'
      }
      connection.response.create(
        stream_id: "main", model: "gpt-6-astra", store: false,
        previous_response_id: response.id,
        input: [
          {
            type: "function_call_output",
            call_id: call.call_id,
            output: JSON.generate(result)
          },
          {
            role: "user",
            content: "Now optimize it."
          }
        ],
        tools: tools, tool_choice: "none"
      )
      puts(wait_for_response(connection).output_text)
    end
  end
end

续接如何工作

链式语义与 HTTP 相同,但在活动套接字上增加低延迟路径。

活动连接以连接本地的内存缓存保存近期响应状态。使用 stream_id 时,每个通道保留最近缓存的响应,从该通道最新响应继续可复用状态,因此较快。状态只留内存、不写磁盘,可兼容 store=false 和 ZDR。

previous_response_id 不在内存缓存时:

  • store=true:如有持久状态,可恢复较旧 ID,续接仍可能成功,但失去内存延迟收益。
  • store=false,包括 ZDR:没有持久化回退,返回 previous_response_not_found。

同一通道续接返回 4xx 或 5xx 时,会从连接缓存移除引用的响应。跨通道分叉失败则保留共享父响应,源通道仍可继续。

压缩与创建新响应

使用压缩时,两种续接模式不同。

服务端压缩(context_management)

启用含 compact_threshold 的 context_management 后,压缩发生在正常 /responses 生成中。WebSocket 仍发送最新 previous_response_id 和新增输入项即可。

独立 /responses/compact

独立 /responses/compact 返回新的压缩输入窗口,不返回响应 ID。压缩后,在 WebSocket 上以压缩窗口和下一个用户或工具项作为 input 创建新响应。

省略 previous_response_id 或设为 null 开始新链。压缩输出原样传入,不要裁剪返回窗口。

来源示例 11(javascript):

沿用程序文字译释266。

程序文字译释279:从这里继续。

// [中文] 示例 11:独立 /responses/compact;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:client.responses.compact、ws.send、ws.close;异步调用及事件接收顺序保留。
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();
}

来源示例 12(python):

沿用程序文字译释279。

## [中文] 显式请求创建或继续响应,使用本段实际设置的模态、上下文与工具字段;发送请求不等同于收到完成事件。
from typing import cast

from openai import OpenAI
from openai.types.responses import ResponseInputParam

## Compact your current window (HTTP call).
compacted = client.responses.compact(
    model="gpt-6-astra",
    input=long_input_items_array,
)
next_input = cast(
    ResponseInputParam,
    [item.to_dict() for item in compacted.output],
)
next_input.append(
    {
        "type": "message",
        "role": "user",
        "content": [{"type": "input_text", "text": "Continue from here."}],
    }
)

## Start a new response on the WebSocket using the compacted window.
with client.responses.connect() as connection:
    connection.response.create(
        stream_id="main",
        model="gpt-6-astra",
        store=False,
        input=next_input,
        tools=[],
    )
    for event in connection:
        if event.type == "response.completed":
            print(event.response.output_text)
            break
        if event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(event.to_json())
    else:
        raise RuntimeError("Connection closed before the response finished.")

来源示例 13(ruby):

沿用程序文字译释268。

沿用程序文字译释269。

沿用程序文字译释279。

程序文字译释280:寻找失败的测试。

## [中文] 示例 13:独立 /responses/compact;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:client.responses.compact、client.responses.connect、connection.response.create;异步调用及事件接收顺序保留。
require "async"
require "openai"

def wait_for_response(connection)
  while (event = connection.receive)
    case event.type.to_s
    when "response.completed" then return event.response
    when "response.failed", "response.incomplete", "error"
      raise "Response failed: #{event.to_json}"
    end
  end
  raise "Connection closed before the response finished"
end

client = OpenAI::Client.new
compacted = client.responses.compact(
  model: "gpt-6-astra",
  input: [
    {
      role: :user,
      content: "Find the failing test."
    }
  ]
)
next_input = compacted.output.map(&:to_h)
next_input << {
  role: :user,
  content: "Continue from here."
}

Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      connection.response.create(
        stream_id: "main", model: "gpt-6-astra", store: false,
        input: next_input, tools: []
      )
      puts(wait_for_response(connection).output_text)
    end
  end
end

并行运行对话

通过 stream_id 在同一连接维持并行对话。连续发送不同 stream_id 的独立 response.create,服务器可并发运行。事件可能交错,保持单一读取循环并按 ID 路由。

stream_id 是一条连接上有序通道的名称,应与 previous_response_id 区分:

  • stream_id 控制事件去向,以及哪些请求先进先出。
  • previous_response_id 控制对话继承关系。

这种分离支持以下两种用法:

来源示例 14(text):

本例中文译文与说明:

一条 WebSocket 连接:planner 流起草部署计划,researcher 流列出部署风险。

one WebSocket connection
├─ stream_id="planner"   draft a deployment plan
└─ stream_id="research"  list deployment risks

同 ID 请求先进先出、不重叠;不同 ID 可并发。

每连接限制

  • 命名与默认通道合计最多 16 个活动中的响应。更多 response.create 仍可接受,排队等活动响应结束。
  • 最多接受 32 个不同的命名 stream_id,隐式默认通道不计入。达到限制后复用 ID 或新建连接。

将对话分叉到新流

把已完成响应 ID 作为 previous_response_id,配合新 stream_id。父响应仍可用时,新流继承上下文,原流可继续;分叉启动后,两条不同 ID 分支可并发。

store=false,包括 ZDR,要求父响应仍在连接缓存。如果分叉排队时源通道已推进或失败,父响应可能在分叉启动前被移除,导致 previous_response_not_found。应等分叉通道发出 response.in_progress 再推进源通道,或将 ID 设为 null 并重放完整上下文重试。

来源示例 15(text):

本例中文译文与说明:

主分支按resp_1、resp_2、resp_3推进,critic分支从既有父响应分叉,按resp_4、resp_5继续,展示对话继承关系。

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

仅复用 stream_id、不提供 previous_response_id,会开始新响应,不会自动继续对话。

关键调用:

来源示例 16(text):

本例中文译文与说明:

同一连接的四项任务提示分别为:起草部署计划、列出部署风险、寻找计划缺口、补充回滚步骤。前两次send_create启动planner与researcher独立对话,之后通过新stream_id与已完成响应的previous_response_id分叉或续接。stream_id决定通道,previous_response_id决定对话继承。

## One socket, two independent conversations.
send_create(connection, "planner", "Draft a deployment plan.")
send_create(connection, "research", "List deployment risks.")

## Fork the planner response, then continue the original branch in parallel.
send_create(
    connection,
    "critic",
    "Find gaps in this plan.",
    previous_response_id=planner_response_id,
)
wait_for_in_progress(connection, "critic")
send_create(
    connection,
    "planner",
    "Add rollback steps.",
    previous_response_id=planner_response_id,
)

完整示例

并行运行多个对话,再分叉其中一个:

来源示例 17(javascript):

程序文字译释285:全部响应完成前连接已关闭。

程序文字译释286:为无状态API服务起草部署计划。

程序文字译释287:列出无状态API服务常见部署风险。

程序文字译释288:寻找此部署计划中的缺口。

程序文字译释289:为计划添加回滚和监控步骤。

// [中文] 示例 17:完整示例;以下保留本语言原始示例。
// [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
// [中文] 本段构造的事件类型:response.create;不要将构造载荷等同于收到成功确认。
// [中文] 沿原示例执行这些方法:ws.send、ws.stream、ws.close;异步调用及事件接收顺序保留。
import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();

const latestResponseIdByLane = new Map();

function sendCreate(
  ws,
  streamId,
  text,
  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) {
  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, expectedStreamIds) {
  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, streamId) {
  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();
}

来源示例 18(python):

沿用程序文字译释285。

沿用程序文字译释286。

沿用程序文字译释287。

沿用程序文字译释288。

沿用程序文字译释289。

程序文字译释290:连接错误,后接事件JSON。

程序文字译释291:分叉启动前连接已关闭。

## [中文] 示例 18:完整示例;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:connection.response.create、client.responses.connect;异步调用及事件接收顺序保留。
from openai import OpenAI
from openai.resources.responses.responses import ResponsesConnection

client = OpenAI()
latest_response_id_by_lane: dict[str, str] = {}


def send_create(
    connection: ResponsesConnection,
    stream_id: str,
    text: str,
    previous_response_id: str | None = None,
):
    if previous_response_id is None:
        previous_response_id = latest_response_id_by_lane.get(stream_id)
    connection.response.create(
        stream_id=stream_id,
        model="gpt-6-astra",
        store=False,
        input=[
            {
                "type": "message",
                "role": "user",
                "content": [{"type": "input_text", "text": text}],
            }
        ],
        previous_response_id=previous_response_id,
    )


def drain_until_complete(
    connection: ResponsesConnection, expected_stream_ids: set[str]
):
    completed: set[str] = set()
    for event in connection:
        stream_id = event.stream_id
        if event.type == "error" and stream_id is None:
            raise RuntimeError(f"Connection error: {event.to_json()}")
        if stream_id is None or stream_id not in expected_stream_ids:
            continue

        if event.type == "response.completed":
            latest_response_id_by_lane[stream_id] = event.response.id
            completed.add(stream_id)
            if completed == expected_stream_ids:
                return
        elif event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(f"Lane {stream_id} failed: {event.to_json()}")
    raise RuntimeError("Connection closed before all responses finished.")


def wait_for_in_progress(connection: ResponsesConnection, expected_stream_id: str):
    for event in connection:
        if event.type == "error" and event.stream_id is None:
            raise RuntimeError(f"Connection error: {event.to_json()}")
        if event.stream_id != expected_stream_id:
            continue
        if event.type == "response.in_progress":
            return
        if event.type in {"response.failed", "response.incomplete", "error"}:
            raise RuntimeError(f"Lane {expected_stream_id} failed: {event.to_json()}")
    raise RuntimeError("Connection closed before the fork started.")


with client.responses.connect() as connection:
    # 1. Run two independent conversations in parallel.
    send_create(
        connection, "planner", "Draft a deployment plan for a stateless API service."
    )
    send_create(
        connection,
        "research",
        "List common deployment risks for a stateless API service.",
    )
    drain_until_complete(connection, {"planner", "research"})

    # 2. Fork the planner conversation and continue the original branch in parallel.
    planner_response_id = latest_response_id_by_lane["planner"]
    send_create(
        connection,
        "critic",
        "Find gaps in this deployment plan.",
        previous_response_id=planner_response_id,
    )
    # Let the fork bind its parent before advancing the original lane.
    wait_for_in_progress(connection, "critic")
    send_create(
        connection,
        "planner",
        "Add rollback and monitoring steps to the plan.",
        previous_response_id=planner_response_id,
    )
    drain_until_complete(connection, {"critic", "planner"})

来源示例 19(ruby):

沿用程序文字译释268。

沿用程序文字译释286。

沿用程序文字译释287。

沿用程序文字译释288。

程序文字译释292:所有响应完成前连接已关闭。

程序文字译释293:补充回滚与监控步骤。

## [中文] 示例 19:完整示例;以下保留本语言原始示例。
## [中文] 原代码明确设置的模型值:gpt-6-astra;各值的作用按其所在配置对象区分。
## [中文] 沿原示例执行这些方法:connection.response.create、client.responses.connect;异步调用及事件接收顺序保留。
require "async"
require "openai"
require "json"

def send_create(connection, stream_id, text, previous_response_id = nil)
  payload = {
    stream_id: stream_id,
    model: "gpt-6-astra",
    store: false,
    input: [
      {
        role: "user",
        content: text
      }
    ]
  }
  payload[:previous_response_id] = previous_response_id if previous_response_id
  connection.response.create(**payload)
end

def read_event(connection)
  event = connection.receive or raise "Connection closed before all responses finished"
  if ["response.failed", "response.incomplete", "error"].include?(event.type.to_s)
    raise "Response failed: #{event.to_json}"
  end

  event
end

def drain_responses(connection, lanes, latest_ids)
  remaining = lanes.dup
  until remaining.empty?
    event = read_event(connection)
    next unless event.type.to_s == "response.completed"

    lane = event.stream_id
    next unless remaining.include?(lane)

    latest_ids[lane] = event.response.id
    remaining.delete(lane)
  end
end

client = OpenAI::Client.new
Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      latest_ids = {}
      send_create(connection, "planner", "Draft a deployment plan for a stateless API service.")
      send_create(connection, "research", "List common deployment risks for a stateless API service.")
      drain_responses(connection, ["planner", "research"], latest_ids)
      parent_id = latest_ids.fetch("planner")
      send_create(connection, "critic", "Find gaps in this deployment plan.", parent_id)
      # Let the fork load its parent before advancing the original lane's cache.
      loop do
        event = read_event(connection)
        break if event.type.to_s == "response.in_progress" && event.stream_id == "critic"
      end
      send_create(connection, "planner", "Add rollback and monitoring steps.", parent_id)
      drain_responses(connection, ["critic", "planner"], latest_ids)
      puts(JSON.generate(latest_ids))
    end
  end
end

stream_id 必须为 1–256 个字符,只能包含字母、数字、下划线 _、连字符 - 和句点 .。仅在 WebSocket response.create 使用,不放入 HTTP POST /v1/responses。

命名流的服务端事件会带相同 stream_id,包括终结事件与请求级错误。

省略时使用隐式默认通道,其事件不带 stream_id,但排序和并发规则相同。空字符串无效,选择默认通道应省略字段。

连接行为与限制

  • 单个响应内部沿用 Responses 流式事件模型,不同通道事件可交错。
  • 同 stream_id 请求先进先出、不重叠;不同 ID 可并发。
  • 连接最长 60 分钟,到限后重新连接。

重连与恢复

连接关闭或达到 60 分钟后,所有通道的连接本地缓存都消失。新建 WebSocket,再逐通道恢复:

  1. 先前响应已 store=true 保存且有有效 ID,使用 previous_response_id 加新增输入继续。
  2. 无法继续,例如 store=false、ZDR 或 previous_response_not_found,将 ID 设为 null 或省略,发送该通道下一轮需要的完整上下文。
  3. 如经 /responses/compact 压缩,以返回窗口为基础 input,再追加最新用户或工具项。

需要处理的错误

服务器能关联命名通道时,错误事件包含 stream_id。请求级错误后,其他通道可继续。

previous_response_not_found:

来源示例 20(json):

程序文字译释294:找不到ID为resp_abc的先前响应。

{
  "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:

来源示例 21(json):

程序文字译释295:stream_id必须是非空字符串,最多256字符,只含字母、数字、下划线、连字符与句点。

{
  "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:

来源示例 22(json):

程序文字译释296:连接已达到32个不同命名流的上限,请复用现有stream_id或新建WebSocket连接。

{
  "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:

来源示例 23(json):

程序文字译释297:Responses WebSocket连接达到60分钟上限,请新建连接继续。

{
  "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
}

相关指南

OpenAI WebSocket 连接
OpenAI 架构
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }