OpenAI Python SDK v3.36.0 发布：Vertex AI 接入 Responses API，WebSocket 稳定性大幅补强

OpenAI 官方 Python SDK 发布 v3.36.0 版本，本次更新围绕企业级部署与实时通信两条主线展开：一方面为 Responses API 增加 Vertex AI 支持，另一方面集中修复 Realtime WebSocket 连接在恢复、取消与清理场景下的多个边界问题。从 commit 编号与 PR 数量看，这更像一次面向生产环境的「稳定性打磨」，而非新能力的大规模铺开。

核心功能更新：Vertex AI 与 API 类型扩展

本次最受关注的变更是为 Responses API 增加 Vertex AI 支持（#4139）。这意味着使用 Google Cloud Vertex AI 作为模型托管渠道的团队，可以在 Python SDK 中走通 Responses 接口的完整生命周期，而不必再依赖额外的适配层。commit 信息中还特别提到「preserve Vertex API root for response lifecycle」（#4140），说明团队在修复中一并处理了 Vertex 端点根路径在响应生命周期内被覆盖的问题——这类细节往往只有真实接入方才会踩到。

在 API 类型层面，v3.36.0 增加了 30 分钟缓存写入的用量计数（#4111）和压缩触发 ID（#4122），后者对使用上下文压缩能力的开发者有直接价值。此外还新增了自定义语音的授权管理（#4135），并预备了原生同步 WebSocket 选项类型（#4118）。

Vertex AI 是 Google Cloud 提供的一站式机器学习平台，除了训练与部署自有模型外，也托管了 Gemini 等第三方模型，并提供与 OpenAI 兼容的推理端点。此前开发者若想通过 OpenAI Python SDK 调用托管在 Vertex AI 上的模型，往往需要自行改写 base_url、拼接项目与区域路径，或借助中间代理层完成协议转换。此次 Responses API 直接支持 Vertex AI，意味着 SDK 内部已能识别该渠道的端点结构与鉴权方式，开发者只需按官方约定传入项目 ID、区域等参数即可复用同一套 Responses 调用代码，显著降低了多云模型接入的改造成本。

Responses API 是 OpenAI 相对 Chat Completions 更新的接口形态，它以「响应」为核心对象，原生支持工具调用、内置工具（如网页搜索、文件检索）、多轮状态延续与服务端会话管理，一次请求即可返回结构化的输出条目序列。相比 Chat Completions 以消息数组为中心的设计，Responses API 更贴近 Agent 式工作流，也承载了上下文压缩、缓存计费等新能力。因此本次为其补充 Vertex AI 支持，不只是增加一个渠道，而是让企业可以在自选的云平台上使用这套更现代的交互模型。

Realtime 与 WebSocket：一批「难复现」问题的集中修复

Bug Fixes 列表几乎被 WebSocket 相关条目占满，这透露出 Realtime 能力在生产使用中仍有不少边缘场景需要兜底。具体包括：失败 WebSocket 建连的清理、原生选项的尊重、中断时结束同步 WebSocket 恢复、终端清理期间尊重带超时的 Translation 接收、跨恢复与取消场景保留 WebSocket close 状态，以及为 legacy beta socket 尊重原生选项（#4121、#4129、#4132、#4117、#4120）。

另外两处修复值得单独提及：一是在严格模式下接受规范化的 batch 响应（#4106），二是 Pydantic v1 校验期间保留已声明的别名（#4119）。后者对仍在使用 Pydantic v1 的存量代码库意义明确，属于典型的不破坏兼容性的渐进式修复。

Realtime API 是 OpenAI 面向低延迟语音与多模态交互的接口，与常规 HTTP 请求不同，它基于 WebSocket 建立长连接，由服务端持续推送事件（如音频分片、转写结果、打断信号），客户端也通过同一连接发送事件。这种双向、有状态的长连接使得连接建立失败、会话中断后恢复、取消操作与终端清理等场景都涉及复杂的状态机，一旦某个状态未被正确保留或释放，就会出现 close 状态丢失、连接泄漏或恢复流程卡死等难以复现的问题——这正是本次修复集中在恢复、取消与清理三类边界场景的原因。

文档与杂项：Python 代码生成迁移进入规划阶段

Chores 与 Documentation 部分透露出 SDK 内部工程化的下一步：团队记录了 Python 生成代码的迁移计划（#4114、#4116），并恢复了 Castiron 上报脚本、支持可信上报器中的下一个 checkpoint。对普通使用者而言这些改动无感知，但对长期维护 SDK 一致性的团队来说，是生成代码与手写代码边界重新划分的前置动作。

Pydantic 是 Python 生态中广泛使用的数据校验库，OpenAI SDK 借助它完成请求参数与响应体的类型校验。Pydantic v2 在性能与 API 上有较大重构，而 v1 仍被大量存量项目依赖，SDK 需要同时兼容两个大版本。字段别名（alias）是 Pydantic 的常用特性，允许 Python 属性名与线上 JSON 字段名不一致，例如把 max_tokens 这类不符合 Python 命名习惯的字段映射到规范属性上。若校验过程中别名信息丢失，序列化后的请求体字段名就会出错，导致服务端拒绝请求。本次「Pydantic v1 校验期间保留已声明别名」的修复，正是针对这一兼容性细节。

升级建议

如果你的项目满足以下任一条件，建议尽快升级：正在通过 Vertex AI 调用 Responses API；使用 Realtime WebSocket 且遇到过连接恢复后 close 状态丢失、或取消操作后连接未正确释放的问题；仍依赖 Pydantic v1 做请求校验。如果你的使用场景集中在标准 Chat Completions 且不涉及实时连接，本次升级的收益相对有限，可以跟随常规依赖更新节奏处理。