OpenAI Python SDK 已全面迁移至 HTTPX2，本文详解其对 TLS 证书、自定义客户端、超时配置、流式响应及测试模拟等层面的影响与迁移指南。

背景：为什么是 HTTPX2？

HTTPX 是 Python 生态中广受欢迎的异步 HTTP 客户端库，而 OpenAI Python SDK 长期以来将其作为底层 HTTP 传输层。然而，随着 HTTPX 项目的演进，其维护者推出了 HTTPX2——一个在架构、TLS 处理和 API 设计上均有重大变更的新一代版本。OpenAI 决定将 SDK 的同步和异步 HTTP 客户端全部切换到 HTTPX2，并且 新 SDK 安装时不再自动附带旧版 httpx 包。

这意味着，如果你此前依赖 openai 包间接获得 httpx，升级后你的代码可能直接因 import httpx 失败而崩溃。本文将从多个维度剖析这次迁移带来的影响，并给出具体的迁移路径。

默认客户端用户：无感升级，但 TLS 信任库变了

如果你使用 SDK 的默认 HTTP 客户端（即构造 OpenAI() 或 AsyncOpenAI() 时未显式传入 http_client），那么你的日常 API 调用、解析后的响应模型、流式 API、认证、重试机制和数值型超时设置 不会发生任何变化：

python
from openai import OpenAI

client = OpenAI(timeout=30.0)
response = client.responses.create(model="gpt-5.5", input="Hello")

安装方式同样简单，无需额外的 HTTPX2 extra 依赖：

bash
pip install openai

但这里有一个隐蔽的破坏性变更：TLS 证书信任库的默认来源改变了。

• 旧版 HTTPX 使用 certifi 提供的 CA 证书包进行服务器证书验证。
• HTTPX2 默认使用 操作系统级信任库，并且 SDK 不再安装 certifi。

这个变化对以下场景会产生实际影响：

1. 极简容器镜像（如 alpine 或精简的 scratch 基础镜像）中可能没有系统 CA 证书，导致所有 HTTPS 请求失败。
2. 企业环境中的 TLS 拦截代理：这类代理通常使用内部 CA 签发证书，如果操作系统信任库中未安装该 CA，则 SDK 会拒绝连接。
3. 依赖自定义或修改过 certifi 包的部署环境。

解决方案

方案一：在操作系统信任库中安装所需的 CA 证书（推荐，适用于生产环境）。

方案二：通过环境变量显式指定证书包或证书目录（注意：这些环境变量仅在 trust_env=True 时生效，而这是默认值）：

bash
export SSL_CERT_FILE=/path/to/ca-bundle.pem
export SSL_CERT_DIR=/path/to/ca-directory

方案三：在自定义客户端上通过 verify 参数传入 ssl.SSLContext 来控制信任链：

python
import ssl
from openai import OpenAI, DefaultHttpx2Client

ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))

异步场景则使用 DefaultAsyncHttpx2Client(verify=ssl_context)。

值得注意的是，SDK 的 aiohttp 传输层也使用相同的 HTTPX2 TLS 设置，因此上述配置对 aiohttp 同样有效。

自定义 HTTP 客户端：必须切换到 HTTPX2 类型

如果你之前向 SDK 注入了自定义的 httpx.Client 或 httpx.AsyncClient，现在必须改用 HTTPX2 的对应类。SDK 提供了两个辅助类来保留其推荐的超时、连接池和重定向默认值：

python
import httpx2
from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client

代理配置

proxy_client = OpenAI(
http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080")
)

自定义传输层和超时

transport_client = OpenAI(
http_client=DefaultHttpx2Client(
transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
timeout=httpx2.Timeout(30.0, connect=5.0),
)
)

异步客户端

async_client = AsyncOpenAI(
http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0))
)

直接构造的 httpx2.Client 和 httpx2.AsyncClient 实例同样受支持，但如果你直接构造，其默认配置将由 HTTPX2 自身决定（而非 SDK 的推荐值），除非你显式覆盖。

兼容性说明：旧的 DefaultHttpxClient 和 DefaultAsyncHttpxClient 名称仍然可用，但它们现在实际构造的是 HTTPX2 客户端。为了代码清晰，建议优先使用带 2 的新名称。

模块级别的配置遵循同样的规则：

python
import openai
openai.http_client = openai.DefaultHttpx2Client()

对象替换对照表

以下是迁移时需要用到的对象替换清单：

旧对象	新对象
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

保持不变的：数值型超时值（如 timeout=30.0）、字符串 URL。

必须更新：自定义传输子类、挂载的传输层、代理集成、连接池监控等，都需要针对 HTTPX2 的传输接口进行重写。

认证与事件钩子

认证处理器和事件钩子现在接收的是 HTTPX2 的请求/响应对象。如果你有自定义的认证类或钩子函数，需要更新其类型注解和实现：

python
import httpx2
from openai import OpenAI, DefaultHttpx2Client

def log_request(request: httpx2.Request) -> None:
print(request.method, request.url)

client = OpenAI(
http_client=DefaultHttpx2Client(event_hooks={"request": [log_request]})
)

如果你继承了 HTTP 认证类或传输接口，请确保继承的是对应的 httpx2 类。第三方监控工具、追踪中间件和认证集成必须显式声明支持 HTTPX2，否则可能无法正常工作。

原始响应、流式与异常

SDK 解析后的响应模型（如 client.models.list() 返回的模型）完全不变。但当你使用原生 HTTPX2 客户端并访问传输层对象时，这些对象属于 HTTPX2：

python
import httpx2
from openai import OpenAI

client = OpenAI()
response = client.models.with_raw_response.list()

assert isinstance(response.http_response, httpx2.Response)
assert isinstance(response.http_request, httpx2.Request)

当你请求未解析的 HTTP 响应时，应使用 cast_to=httpx2.Response。流式响应包装器同样暴露 HTTPX2 响应对象。

异常处理：应用代码通常应捕获 SDK 级别的异常（如 openai.APITimeoutError、openai.APIConnectionError）。但如果你需要检查底层传输异常，原生客户端下其 __cause__ 将是 HTTPX2 的异常类型。

重要警告：以上类型保证 仅适用于原生 HTTPX2 客户端。如果你向后兼容地注入了一个旧版 HTTPX 客户端，那么 http_response 将是 httpx.Response，异常也是 HTTPX 的，即使你传了 cast_to=httpx2.Response 也不会改变。

aiohttp 支持

SDK 提供的 aiohttp extra 现在使用 HTTPX2 原生传输层，不再安装旧版 HTTPX 或外部 httpx-aiohttp 适配器：

bash
pip install 'openai[aiohttp]'

python
from openai import AsyncOpenAI, DefaultAioHttpClient

client = AsyncOpenAI(http_client=DefaultAioHttpClient())

DefaultAioHttpClient() 本身就是一个 httpx2.AsyncClient，使用此辅助类的应用无需直接构造或导入传输层。

请求模拟与测试

如果你的测试套件使用 mock 拦截请求，现在必须拦截 HTTPX2 请求并返回 HTTPX2 响应：

python
import httpx2
from openai import OpenAI

def handler(request: httpx2.Request) -> httpx2.Response:
return httpx2.Response(200, request=request, json={"object": "list", "data": []})

client = OpenAI(http_client=httpx2.Client(transport=httpx2.MockTransport(handler)))
assert client.models.list().data == []

RESPX 用户注意：如果你的测试套件使用 RESPX 库，必须升级到兼容 HTTPX2 的版本或进行 fork。仅修补旧版 HTTPX 的 RESPX 版本 无法拦截 SDK 默认的 HTTPX2 客户端。

如果暂时无法迁移该集成，SDK 提供了一个临时的旧版客户端逃生舱口（具体用法见官方文档）。但请将其视为短期方案，长期仍需迁移到 HTTPX2 生态。

总结与建议

这次迁移的核心要点：

1. 默认用户：API 调用层无感，但注意 TLS 信任库从 certifi 切换为操作系统信任库，容器环境需额外配置。
2. 自定义用户：所有 HTTPX 类型必须替换为 HTTPX2 对应类型，SDK 辅助类 DefaultHttpx2Client / DefaultAsyncHttpx2Client 是首选。
3. 测试用户：mock 和 RESPX 必须升级到 HTTPX2 兼容版本。
4. 依赖管理：SDK 不再传递安装 httpx，如有直接使用需自行添加依赖。

建议所有使用 OpenAI SDK 的开发者尽早完成迁移测试，特别是涉及企业代理、容器部署和复杂测试套件的场景。

原文链接：https://github.com/openai/openai-python/blob/main/httpx2.md