OpenAI Python SDK 开始迁移 HTTPX2：定制 HTTP 客户端要改了

OpenAI Python SDK 3.0.0 已经开始将底层 HTTP 客户端从 httpx 迁移到 httpx2，这次变化对普通调用者影响不大，但对配置了自定义网络层的开发者来说，可能是一次必须处理的兼容性升级。

HTTPX2 是 Pydantic 团队维护的 HTTPX API 兼容分支，目标是在保留 HTTPX 使用方式的同时，为 Pydantic 生态和新一代 Python SDK 提供更稳定的底层依赖。OpenAI 目前已经在迁移文档中明确说明：SDK 会自动安装 httpx2，但不再自动安装此前的 httpx 包。

这不是一次模型能力更新，也不会直接改变 Responses API、流式输出、重试或认证逻辑。它改变的是 SDK 与网络请求层之间的连接方式。对于只使用 OpenAI() 或 AsyncOpenAI() 默认配置的应用，升级通常可以直接完成；对于自己接管 HTTP 客户端的应用，升级前则需要逐项检查依赖、类型和 Transport 配置。

先说结论：大多数应用无感，基础设施代码不能盲升

OpenAI Python SDK 的默认 HTTP 客户端迁移到 HTTPX2 后，标准调用链路仍然保持兼容。官方迁移说明指出，在不传入自定义 http_client 的情况下，已有的 API 调用、解析后的响应模型、流式接口、认证、重试以及数值类型的超时配置都继续工作。

这意味着，典型的业务代码不需要因为 HTTPX2 迁移而重写。应用如果只是初始化客户端、调用模型、读取结构化响应或消费 SSE 流式事件，升级 SDK 后首先要做的是运行现有测试，而不是立刻改业务逻辑。

真正需要关注的是那些把 SDK 当作网络组件使用的项目。典型场景包括：

• 通过 http_client 注入自定义同步或异步客户端；
• 使用自定义 Transport 控制连接池、代理、TLS 或 Unix Domain Socket；
• 依赖 HTTPX 的 Timeout、Limits、Proxy 等具体类型；
• 通过事件钩子记录请求、响应、耗时或链路追踪信息；
• 在测试中使用 Mock Transport 或拦截请求；
• 通过自定义认证处理器注入请求头、签名或短期凭证；
• 为企业网络配置代理、证书、客户端证书或特殊 DNS；
• 在同一套基础设施中同时维护 OpenAI、Anthropic 或其他使用 HTTPX 的 SDK。

这些代码的问题不一定会在安装阶段暴露。最常见的情况是，依赖安装成功，但在创建客户端、发起第一条请求或进入流式分支时，出现类型不匹配、参数不被识别、Transport 无法挂载等运行时错误。

HTTPX2 到底是什么，为什么会影响自定义客户端

HTTPX2 是一个与 HTTPX API 兼容的 HTTP 客户端分支，但“API 兼容”不等于“包名、类型身份和内部实现完全相同”。这是理解本次迁移的关键。

Python 的类型和依赖关系通常同时包含两层含义：一层是对象有没有相同的方法，另一层是它究竟来自哪个包。一个客户端即使拥有与 httpx.Client 相同的 request() 方法，也不代表它可以在所有需要 HTTPX2 类型的位置被安全接受。

可以把它类比成两辆外观和驾驶方式相近的汽车：普通司机只关心方向盘、刹车和油门，因此切换后几乎没有感觉；车队管理系统却可能依赖车辆型号、诊断协议和零件编号，此时“操作方式相似”并不足以保证兼容。

OpenAI SDK 的默认路径由 SDK 自己创建和管理 HTTPX2 客户端，因此应用不需要知道底层实例来自哪个包。问题出现在应用显式传入一个由旧 httpx 创建的客户端时，此时开发者实际上接管了 SDK 的网络层，SDK 与自定义对象之间的包级兼容性就变成了应用的一部分。

受影响程度可以按这张表判断

不同使用方式面对的迁移成本并不相同，是否传入自定义 HTTP 客户端是最重要的判断条件。

| 使用方式 | 是否需要修改代码 | 主要风险 | 建议 | |---|---:|---|---| | 使用 OpenAI() 默认客户端 | 通常不需要 | 依赖锁文件变化、间接依赖冲突 | 直接升级并运行回归测试 | | 使用 AsyncOpenAI() 默认客户端 | 通常不需要 | 异步依赖冲突、事件循环测试差异 | 重点验证流式和并发请求 | | 传入旧 httpx.Client | 需要检查并通常需要修改 | 客户端类型和 Transport 不兼容 | 按迁移指南改为 HTTPX2 版本 | | 传入旧 httpx.AsyncClient | 需要检查并通常需要修改 | 异步 Transport、关闭生命周期不兼容 | 检查异步上下文和连接释放 | | 使用自定义代理或 Transport | 高概率需要修改 | 构造参数、类型、连接池行为变化 | 逐项核对 HTTPX2 对应接口 | | 使用事件钩子 | 需要验证 | 请求/响应对象类型变化 | 检查钩子签名和日志序列化 | | 使用 Mock Transport | 需要验证 | 测试桩无法被 SDK 接受 | 在 CI 中覆盖真实初始化路径 | | 仅使用 SDK 的模型和流式接口 | 通常不需要 | 主要是底层依赖安装问题 | 不要为了迁移改动业务调用逻辑 |

这里有一个容易被忽略的细节：开发者可能没有直接写出 http_client，但项目中的封装层、依赖注入容器或企业网络组件已经替应用传入了自定义客户端。排查时不能只搜索业务仓库里的 OpenAI(，还要搜索 http_client、httpx.Client、httpx.AsyncClient、MockTransport、event_hooks、transport 和 verify 等关键词。

这次迁移不会改变哪些行为

HTTPX2 迁移不会自动改变 OpenAI 模型的输入输出协议。Responses API 的请求结构、解析后的响应对象、工具调用字段以及流式 SSE 事件仍由 OpenAI Python SDK 的上层接口负责，底层 HTTP 客户端并不决定这些字段的业务含义。

HTTPX2 迁移也不会自动提高模型推理速度。它可能影响连接管理、代理、TLS、重试外围逻辑和请求可观测性，但不能把网络库升级误解成模型性能升级。模型生成速度、首 token 延迟和总响应时间仍然受模型、区域、请求长度、服务端排队以及网络路径共同影响。

数值型超时配置仍然是兼容的。迁移文档给出的默认客户端示例中，开发者可以继续以秒为单位设置数值超时，例如把客户端超时设置为 30.0。但这不等于所有旧的超时对象都能原样传入。只要项目显式构造了来自旧 httpx 包的超时对象，就应该检查它是否需要改成 HTTPX2 对应类型。

流式输出同样不需要因为底层客户端变化而重写消费逻辑。OpenAI SDK 仍然负责 Server-Sent Events，也就是 SSE 流式事件的解析和生命周期管理。需要重点测试的是自定义 Transport、连接关闭以及异常重试是否会在流式场景下表现一致，因为流式请求通常比普通 JSON 请求更长，也更容易暴露连接池和超时配置问题。

自定义客户端的迁移重点

1. 先处理依赖来源，而不是只改 import

最先要确认的是，项目究竟依赖了哪个 HTTP 包，以及这个包是直接依赖还是间接依赖。OpenAI Python SDK 3.0.0 会自动安装 httpx2，但不会再因为安装 OpenAI SDK 而自动安装旧的 httpx。

如果业务项目仍然直接使用 httpx，它不会因为 OpenAI SDK 迁移就自动消失。项目可以同时安装两个包，但开发者必须清楚：给 OpenAI SDK 传入的自定义客户端应当遵循 HTTPX2 迁移要求，而其他业务模块是否继续使用旧 HTTPX，则需要单独评估。

更稳妥的做法是检查锁文件和依赖树，确认最终环境中实际安装的版本，而不是只看 pyproject.toml 或某个直接依赖声明。尤其是在 Poetry、uv、PDM、pip-tools 或企业内部基础镜像中，旧版 HTTPX 可能被其他库带入，最终形成两套相似但不完全相同的网络客户端实现。

2. 代理配置不能只看参数名

代理是本次迁移中最容易受到影响的场景之一。开发者往往会在初始化客户端时设置代理、连接池和证书，然后把这个客户端传入 SDK。即使代理 URL 没变，HTTPX2 对代理相关构造参数、Transport 绑定方式或异步实现的要求也可能不同。

迁移时应该验证四件事：代理是否真正生效、HTTPS 请求是否可以建立、流式连接是否会被代理提前关闭、代理异常是否仍能被应用识别。只测试一个普通请求是不够的，因为普通响应和长连接流式响应经过代理时，可能走不同的缓冲和超时路径。

对于需要区分多个上游服务的应用，还应避免把带有特殊证书、认证或代理配置的客户端无条件复用到其他域名。网络配置是绑定在 Transport 和客户端生命周期上的，不是一个可以随意跨服务复制的普通参数。

3. Transport 和连接池是高风险区域

Transport 是 HTTP 客户端负责建立和复用网络连接的底层组件，自定义 Transport 通常用于代理、测试、TLS、连接池和特殊网络协议。

这类代码最容易受到包级兼容影响，因为 Transport 不只是一个具有几个方法的简单对象，它还可能依赖请求对象、响应对象、连接池和异步调度器的内部约定。旧 httpx 创建的 Transport 即使名称和方法保持一致，也不应默认认为可以直接交给 HTTPX2 客户端使用。

生产环境需要重点验证连接复用和关闭行为。建议至少覆盖以下测试：连续发送多次请求时连接是否复用；并发请求是否超过预期连接数；请求超时后连接是否正确释放；客户端关闭后是否仍有后台任务；进程退出时是否出现未关闭资源警告。

4. 事件钩子和可观测性代码要重新跑一遍

事件钩子是开发者插入请求日志、耗时统计、Trace ID 和错误采集逻辑的扩展点。迁移到 HTTPX2 后，即使钩子注册方式保持相似，钩子收到的请求、响应和异常对象也可能来自新的包。

如果日志系统直接读取对象属性，通常问题不大；如果日志系统依赖具体类名、模块路径、私有属性或自定义序列化规则，就需要进行兼容性检查。特别要注意不要在日志中记录完整提示词、响应内容或认证信息，底层网络层更容易接触到这些敏感数据。

5. Mock 测试不能只测业务结果

Mock Transport 是用来在不访问真实网络的情况下模拟 HTTP 请求和响应的测试组件。旧测试如果直接把 httpx.MockTransport 注入 OpenAI SDK，升级后可能在测试初始化阶段失败，也可能在请求发送时失败。

迁移测试应当分成两层：第一层测试请求是否按照预期生成，包括 URL、方法、请求头和序列化内容；第二层测试 SDK 是否能在 HTTPX2 客户端下完成响应解析、错误转换和流式事件消费。这样可以把“网络客户端不兼容”和“业务请求构造错误”区分开，避免所有失败都表现成一个模糊的请求异常。

与其他 Python SDK 的影响边界

HTTPX2 不是 OpenAI 专属的新协议，而是 Pydantic 团队维护的 HTTPX API 兼容分支。其他 Python SDK 如果也采用这一分支，可能会共享类似的依赖和迁移注意事项；但不能据此推断所有 SDK 都会自动兼容同一套自定义客户端。

开发者需要按 SDK 边界管理 HTTP 客户端。一个项目同时使用 OpenAI、Anthropic 或其他模型服务 SDK 时，最稳妥的方式不是把一个全局客户端实例注入所有 SDK，而是为每个上游服务明确管理客户端、Transport、证书和基础 URL。这样可以降低不同 SDK 升级时的联动风险，也能避免某个服务的认证或 TLS 配置被意外带到另一个服务。

如果应用确实需要统一网络策略，应该统一的是代理规则、超时规范、日志字段和连接池容量，而不是强行复用同一个具体客户端对象。前者是架构约定，后者会把不同依赖的内部类型耦合在一起。

升级前后的排查清单

这次迁移适合按“依赖、初始化、请求、流式、异常、关闭”六个环节验证：

1. 依赖：检查锁文件中是否出现 httpx2，确认旧 httpx 是否仍被其他模块直接使用。
2. 初始化：验证同步和异步客户端能否正常创建，尤其是自定义 http_client 路径。
3. 请求：验证普通请求的 URL、认证头、超时、代理和 TLS 证书配置。
4. 流式：验证 SSE 事件消费、长连接超时、客户端中断和连接释放。
5. 异常：验证网络错误、超时、4xx、5xx 以及重试逻辑是否仍被正确分类。
6. 关闭：验证同步客户端、异步客户端和应用退出时的资源释放。

团队还应该把 SDK 升级放入真实的 CI 矩阵，而不是只在开发者本机运行一条成功请求。至少需要覆盖 Python 项目实际支持的最低版本、同步和异步两条路径，以及生产中使用的代理或证书配置。

OpenAI Python SDK 3.0.0 值不值得立刻升级

如果应用只使用默认客户端，OpenAI Python SDK 3.0.0 的迁移成本较低，升级重点是锁定依赖并完成回归测试。对于新项目，没有理由继续围绕旧 httpx 设计新的 OpenAI 网络层封装。

如果应用大量依赖自定义 Transport、代理或企业证书，是否立即升级取决于测试覆盖和发布节奏。没有完整网络层测试的生产系统，不建议仅凭“HTTPX API 兼容”就直接替换依赖；应该先在隔离环境中验证初始化、普通请求、流式请求和异常路径。

这次变化释放出的信号也很明确：OpenAI 正在把 Python SDK 的网络层依赖从通用 HTTPX 生态逐步收拢到 HTTPX2。对普通开发者而言，这是一次几乎透明的底层升级；对维护 SDK 封装、网关接入、企业代理和测试基础设施的团队而言，它提醒大家不要把底层 HTTP 客户端当成永远稳定的实现细节。

**一句话判断：默认配置可以跟着升级，自定义网络层必须按迁移指南重做兼容性验证。**真正需要改的通常不是模型调用逻辑，而是那些被长期隐藏在客户端初始化代码里的代理、Transport、认证、事件钩子和 Mock 依赖。

参考来源

• OpenAI Python SDK：Migrating to HTTPX2：OpenAI 官方迁移说明，涵盖默认客户端、自定义客户端以及底层 HTTP 配置的兼容性变化。
• OpenAI Python SDK GitHub 仓库：查看 SDK 版本、源码变更和后续迁移信息。