𝐗𝐀𝐈 𝐑𝐨𝐮𝐭𝐞𝐫

XAI Router 已支持 OpenAI WebSocket Mode：与官方语义对齐说明

Posted February 24, 2026 by XAI 技术团队 ‐ 5 min read

本文是 XAI Router WebSocket 能力的工程说明。 截至 2026-02-24，XAI Router 已完成对 OpenAI WebSocket 相关能力的统一支持，重点覆盖：

  1. POST /v1/responses 对应的 WebSocket mode（wss://.../v1/responses）
  2. wss://.../v1/realtime 实时会话
  3. 与现有 HTTP 转发体系共存，不改变原有 HTTP API 行为

先看 OpenAI 官方语义（WebSocket Mode）

根据 OpenAI 官方文档，Responses 的 WebSocket mode 关键点是：

  1. 保持持久连接到 /v1/responses
  2. 每一轮通过 response.create 发起
  3. 使用 previous_response_id + 增量 input 持续对话
  4. 单连接为顺序执行：一次仅允许一个 in-flight response（不支持 multiplexing）
  5. 连接时长上限 60 分钟，超时后需要重连

XAI Router 对齐策略

1) 路径兼容

XAI Router 同时支持这两组路径，便于不同客户端接入：

  • /v1/responses 与 /responses
  • /v1/realtime 与 /realtime

2) 官方语义对齐

在 /v1/responses WebSocket 模式下，XAI Router 采用与官方一致的顺序语义：

  • 连接内允许多次 response.create
  • 但严格“一个在途请求完成后再发下一个”
  • 并发发送多个 response.create 会被拒绝

这与 OpenAI 官方文档中“单连接顺序执行、无 multiplexing”保持一致。

3) 状态与续接

previous_response_id、增量 input、store=false 等字段均按事件透传路径处理； XAI Router 不改写这类会话语义字段，只在必要位置做模型映射、鉴权、限流与计费。

架构实现（统一框架）

本次实现不是单点补丁，而是将 WebSocket 统一到同一框架：

  1. ws_framework：统一会话、转发、超时、错误处理、连接收敛
  2. openai-responses-ws 适配器：处理 response.create 生命周期、turn 绑定、usage 采集
  3. openai-realtime-ws 适配器：处理 realtime 事件流与会话计费

同时将原有 /v1/realtime 迁移到同一框架内，减少分叉逻辑，降低后续维护复杂度。

XAI Router OpenAI WebSocket 对齐架构图

上图对应统一 WebSocket 框架的核心思路：在保持 OpenAI 官方语义的前提下，把 Responses 与 Realtime 都收敛到同一会话与转发模型。

最小调用示例（Responses WebSocket）

下面示例通过 XAI Router 使用 gpt-5.2 发起一轮 response.create：

from websocket import create_connection
import json
import os

ws = create_connection(
    "wss://api.xairouter.com/v1/responses",
    header=[
        f"Authorization: Bearer {os.environ['XAI_API_KEY']}",
    ],
)

ws.send(json.dumps({
    "type": "response.create",
    "model": "gpt-5.2",
    "store": False,
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [{"type": "input_text", "text": "请用一句话总结 websocket mode。"}]
        }
    ],
    "tools": []
}))

while True:
    event = json.loads(ws.recv())
    print(event.get("type"))
    if event.get("type") in ("response.completed", "response.failed", "response.incomplete"):
        break

ws.close()

性能与稳定性说明

在保持功能不变前提下，XAI Router 对 WS 路径做了几项工程化优化：

  1. 高频事件先做轻量字段预判，再进入完整 JSON 解析
  2. 复用统一转发框架，减少重复逻辑与状态分叉
  3. 连接异常日志做降噪，保留握手阶段关键错误，减少无意义噪音

实际效果是：在不影响原 HTTP 主流程的前提下，WS 路径更可维护、行为更稳定。

结语

如果你正在做多轮工具调用、Agent 编排或低延迟长链路任务， /v1/responses 的 WebSocket mode 会比“每轮 HTTP 重建上下文”更合适。

XAI Router 的目标不是“再包一层”，而是： 在保持 OpenAI 官方语义的同时，把多 key、鉴权、限流、计费、路由和稳定性做到工程可用。

参考来源