OpenAI SDK v3.36.1 发布：修复 WebSocket 与浏览器调用问题

OpenAI 官方 SDK 于 10 月 22 日发布 v3.36.1 版本。这是一个以问题修复为主的补丁版本，覆盖 API、示例代码、文档说明和内部运行时重构四个方向。对于正在使用该 SDK 构建实时语音、浏览器端调用或大文件上传能力的开发者来说，这个版本解决了几个实际使用中会遇到的痛点。

核心修复：WebSocket 与浏览器调用

按调用生效的 WebSocket 查询配置

本次最值得关注的修复是 API 模块中的 honor per-call WebSocket query settings（#4138）。在此之前，WebSocket 连接的查询参数配置可能无法在单次调用中正确生效，导致开发者传入的 query 设置被忽略或被全局配置覆盖。对于实时语音、流式对话等依赖 WebSocket 的场景，这意味着连接行为与预期不一致，排查起来相当隐蔽。修复后，每次调用传入的 WebSocket 查询参数会被正确尊重，多租户或按请求定制连接参数的使用方式变得更加可靠。

WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议，与普通 HTTP 请求每次都要重新建连不同，它通过一次 HTTP 升级握手后保持长连接，客户端与服务端可以随时互相推送数据。这一特性使其成为实时语音、流式文本生成等低延迟场景的常用通道。SDK 在建立 WebSocket 连接时，通常会把查询参数附加在握手 URL 上，用于传递模型名、会话标识、鉴权令牌或自定义路由信息。所谓「按调用生效」，是指这些参数应当以单次调用传入的值为准，而不应被客户端实例级的全局默认值覆盖。如果合并逻辑写错，全局配置就会悄悄压过调用方显式传入的参数，表现为连接打到了错误的端点或会话，而错误往往要等到服务端行为异常时才暴露，因此这类修复对多租户场景尤为关键。

浏览器调用前先校验驱动状态

示例代码部分修复了两个问题。其一是 validate browser calls before reading driver state（#4142）：在浏览器环境中调用相关能力时，代码会先读取驱动状态再进行校验，顺序反了。这会导致在驱动尚未就绪时读取状态，抛出难以理解的错误。调整为先校验、后读取后，错误信息更贴近真实原因，示例的可运行性也随之提升。

另一个示例修复是 stop microphone capture between recordings（#4143）。连续录音场景下，麦克风采集没有在两次录制之间正确停止，可能造成资源占用或音频数据串扰。对于照抄示例做语音应用的开发者，这类问题会直接表现为录音异常。

文档与重构：为分块上传和向量库轮询铺路

服务账号 API Key 删除说明更清晰

文档层面，本次对服务账号 API Key 的删除流程做了说明澄清（#4151）。服务账号密钥管理是企业级集成中的高频操作，删除语义不清晰容易引发误操作。这条改动本身不涉及代码行为，但降低了运维侧的理解成本。

手写运行时的准备工作

重构部分包含两项：prepare handwritten chunked upload runtime（#4146）与 prepare handwritten vector-store polling runtime（#4148）。两者都是"准备工作"性质的改动，尚未改变对外行为，但释放了一个信号：SDK 正在把手写的分块上传逻辑和向量库轮询逻辑整理为独立运行时。分块上传关系到大规模文件写入的稳定性，向量库轮询则影响 RAG 场景下的索引同步效率。这类重构通常是为后续功能扩展或性能优化做铺垫，值得关注后续版本是否跟进。

向量库轮询是 RAG（检索增强生成）流程中的常见环节：文档上传到向量库后，索引构建是异步进行的，应用需要周期性查询索引状态，直到其变为可用再发起检索。轮询逻辑看似简单，却涉及退避策略、超时上限、并发请求去重等细节。分块上传则指把大文件切分为多个片段分别传输，再在服务端合并，它需要处理分片顺序、断点续传、失败重试和完整性校验。这两块逻辑此前往往以手写代码散落在 SDK 内部，难以复用和测试。把它们整理为独立运行时，意味着后续可以统一控制重试与并发策略，也便于在不影响公共 API 的前提下替换实现，这正是「准备工作」类提交的实际含义。

如何理解这个版本

从版本号看，3.36.1 是补丁级更新，没有新增 API 或破坏性变更，升级风险较低。它的价值集中在"让已有能力按预期工作"：WebSocket 查询配置终于按调用生效，浏览器示例的报错更可诊断，连续录音不再互相干扰。如果你的项目涉及实时语音或浏览器端调用，建议尽快升级；如果只用基础的文本补全接口，升级的紧迫性不高，但也没有明显阻力。

需要提醒的是，本次发布信息来自 GitHub Release 页面，内容以提交记录和修复条目为主，官方未附带迁移说明。升级前建议在测试环境验证 WebSocket 相关调用路径，确认查询参数的传递行为符合预期。