OpenAI Python SDK 迁移至 HTTPX2
OpenAI Python SDK 现在对同步和异步 HTTP 客户端均使用 HTTPX2。此更改确保了 SDK 是基于稳定的 API 构建的，从而避免了即将发布的 HTTPX 1.0 版本中预期的破坏性变更。虽然 HTTPX2 会随 openai 包自动安装，但旧版的 httpx 包不再是传递依赖。
TLS 证书验证与信任库
对于大多数用户而言，最关键的变化是 TLS 证书验证方式的转变。HTTPX2 默认使用操作系统的信任库，而之前的 HTTPX 实现则依赖于 certifi CA 束。
这种转变可能会在以下环境中导致证书验证失败：
- 缺乏系统 CA 证书的最小化容器镜像。
- 使用企业级 TLS 检查代理的环境。
- 此前依赖于修改或自定义
certifi束的部署。
为了解决这些问题，用户应将所需的 CA 证书安装到操作系统的信任库中，或使用环境变量配置显式的证书束：
SSL_CERT_FILE=/path/to/ca-bundle.pemSSL_CERT_DIR=/path/to/ca-directory
为了进行细粒度控制，可以通过 verify 参数使用 DefaultHttpx2Client 或 DefaultAsyncHttpx2Client 传递 ssl.SSLContext。
对默认和自定义 HTTP 客户端的影响
默认客户端用法
对于在不提供自定义 http_client 的情况下构造 OpenAI 或 AsyncOpenAI 客户端的用户，现有的 API 调用、流式传输、身份验证和超时设置在无需额外配置的情况下仍可正常工作。
自定义客户端配置
提供自定义 HTTP 客户端的用户现在必须使用 HTTPX2 客户端和配置对象。SDK 提供了一些辅助类来维持连接池和超时的推荐默认值：
DefaultHttpx2Client: 用于同步客户端。DefaultAsyncHttpx2Client: 用于异步客户端。
同时也支持直接构造的 httpx2.Client 和 httpx2.AsyncClient 实例。虽然旧版的名称 DefaultHttpxClient 和 DefaultAsyncHttpxClient 仍然有效，但它们现在在底层通过实例化 HTTPX2 客户端来实现。
API 映射与对象替换
在迁移自定义实现时，请将旧版的 httpx 对象替换为对应的 httpx2 等价物：
| Previous Object | HTTPX2 Object |
|---|---|
httpx.Client |
httpx2.Client |
httpx.AsyncClient |
httpx2.AsyncClient |
httpx.Timeout |
httpx2.Timeout |
httpx.URL |
httpx2.URL |
httpx.Limits |
httpx2.Limits |
httpx.HTTPTransport |
httpx2.HTTPTransport |
httpx.AsyncHTTPTransport |
httpx2.AsyncHTTPTransport |
httpx.MockTransport |
httpx2.MockTransport |
原始响应与异常处理
当使用原生的 HTTPX2 客户端时，面向传输层的对象——例如由 with_raw_response 返回的对象——是 httpx2.Response 和 httpx2.Request 的实例。
应用程序代码应继续捕获 SDK 级别的异常（例如 openai.APITimeoutError 和 openai.APIConnectionError）。然而，这些异常的底层传输层原因现在将是 HTTPX2 异常，而非 HTTPX 异常。
测试与请求模拟
Mock 必须现在拦截 HTTPX2 请求并返回 HTTPX2 响应。如果测试套件依赖于 RESPX，用户必须更新到与 HTTPX2 兼容的版本或 fork 该库，因为仅修复旧版 HTTPX 的版本无法拦截 SDK 默认的 HTTPX2 客户端。
兼容性与旧版逃生口
对于无法立即从仅使用 HTTPX 的传输层或模拟库迁移的应用程序，SDK 提供了一个仅限运行时的逃生口。通过显式安装 httpx 并注入一个旧版客户端，用户可以维持现有功能：
from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))
请注意，这种方法会无法通过静态类型检查（mypy, Pyright），并且需要使用 cast(Any, ...) 或 type-ignores。这种旧版支持是一种临时的迁移辅助手段，并且可能会被停止使用。
社区洞察
行业同行已经指出，这种转变并非 OpenAI 独有的；Anthropic 也实施了类似的变更。主要的驱动因素是 httpx 依赖项在接近 1.0 版本发布时表现出的不稳定性，因为预计 1.0 版本会引入重大的破坏性变更。
The httpx2 project is essentially a fork that promises not to break the existing API, which makes it a more stable dependency to build against.
其他开发者也为高性能需求提出了替代方案，例如基于 Rust 的 pyqwest，尽管 SDK 目前的实现是标准化在 HTTPX2 上的。
Sources
相关
- 项目
- Dispatch
- Dispatch
- 项目