OpenAI Python SDK已升级为使用HTTPX2作为HTTP客户端，自动安装且无需额外配置。默认客户端下现有API调用、流式API、认证和重试等功能保持不变。主要变化是HTTPX2改用操作系统信任存储而非certifi的CA包，可能影响缺少系统CA证书的容器环境或使用TLS代理的场景。
正文
迁移至HTTPX2
OpenAI Python SDK现已采用HTTPX2作为同步和异步HTTP客户端。HTTPX2会随openai自动安装，而之前的httpx包则不再自动安装。本文介绍与SDK HTTP层交互的应用程序需要了解的变化。
使用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：
python
pip install openai
如果您的应用程序仅因早期SDK间接安装了httpx而导入它，请自行添加httpx依赖或将相关导入迁移至httpx2。安装SDK不再自动为您安装httpx。
TLS证书和信任存储
HTTPX2更改了默认TLS信任存储，包括使用SDK默认HTTP客户端的应用程序。HTTPX之前使用certifi提供的CA包验证证书，而HTTPX2改用操作系统信任存储，SDK不再安装certifi。
这可能导致以下环境中的证书验证失败：缺少系统CA证书的最小容器镜像、使用企业TLS检查代理的环境、依赖自定义或修改版certifi包的部署。解决方案是在操作系统信任存储中安装所需的CA证书，或配置显式证书包：
bash
export SSL_CERT_FILE=/path/to/ca-bundle.pem
或配置受信任CA证书目录：
bash
export SSL_CERT_DIR=/path/to/ca-directory
当trust_env=True（默认值）时，这些环境变量生效。要在自定义客户端上显式控制信任，可通过verify参数传递ssl.SSLContext：
```python import ssl from openai import OpenAI, DefaultHttpx2Client
sslcontext = ssl.createdefaultcontext(cafile="/path/to/ca-bundle.pem") client = OpenAI(httpclient=DefaultHttpx2Client(verify=ssl_context)) ```
异步配置使用DefaultAsyncHttpx2Client(verify=ssl_context)。SDK的aiohttp传输使用相同的HTTPX2 TLS设置。
提供自定义HTTP客户端的情况
使用HTTPX2客户端和HTTPX2配置对象。SDK提供了保留其推荐超时、连接池和重定向默认值的辅助工具：
```python import httpx2 from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client
proxyclient = OpenAI(httpclient=DefaultHttpx2Client(proxy="http://proxy.example.com:8080"))
transportclient = OpenAI( httpclient=DefaultHttpx2Client( transport=httpx2.HTTPTransport(local_address="0.0.0.0"), timeout=httpx2.Timeout(30.0, connect=5.0), ) )
asyncclient = AsyncOpenAI(httpclient=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0))) ```
也支持直接构建的httpx2.Client和httpx2.AsyncClient实例。直接构建客户端时，除非自行配置，否则将应用其自身的HTTPX2默认值。
现有的DefaultHttpxClient和DefaultAsyncHttpxClient名称仍可工作，但现在构建的是HTTPX2客户端。建议在明确指定HTTP客户端系列时使用DefaultHttpx2Client和DefaultAsyncHttpx2Client。
模块级配置遵循相同规则：
python
import openai
openai.http_client = openai.DefaultHttpx2Client()
超时、URL、传输和连接设置
将HTTPX特定对象替换为对应的HTTPX2对象：
| 原对象 | HTTPX2对象 | |--------|------------| | 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 |
例如，精细化的SDK超时设置变为：
```python import httpx2 from openai import OpenAI
client = OpenAI(timeout=httpx2.Timeout(60.0, connect=5.0, read=20.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(httpclient=DefaultHttpx2Client(eventhooks={"request": [log_request]})) ```
如果您子类化HTTP认证或传输接口，请子类化对应的httpx2类。第三方检测、追踪中间件和认证集成必须显式支持HTTPX2。
原始响应、流式和异常
解析后的SDK响应模型不变。使用原生HTTPX2客户端时，传输层对象属于HTTPX2：
```python import httpx2 from openai import OpenAI
client = OpenAI() response = client.models.withrawresponse.list() assert isinstance(response.httpresponse, httpx2.Response) assert isinstance(response.httprequest, httpx2.Request) ```
使用原生客户端时，请求未解析的HTTP响应请使用cast_to=httpx2.Response。流式响应包装器也暴露HTTPX2响应对象。应用程序代码通常应捕获SDK异常如openai.APITimeoutError和openai.APIConnectionError；使用原生客户端时，异常的底层传输原因是HTTPX2异常。
这些类型保证仅适用于原生HTTPX2客户端。注入的旧版HTTPX客户端会产生httpx.Request、httpx.Response和HTTPX传输异常，即使提供了cast_to=httpx2.Response也是如此。
aiohttp
支持的aiohttp额外功能使用HTTPX2原生传输。它不安装旧版HTTPX或外部httpx-aiohttp适配器：
bash
pip install 'openai[aiohttp]'
```python from openai import AsyncOpenAI, DefaultAioHttpClient
client = AsyncOpenAI(http_client=DefaultAioHttpClient()) ```
DefaultAioHttpClient()是一个httpx2.AsyncClient。使用此辅助工具的应用程序无需直接构建或导入传输。
请求模拟和测试
模拟必须拦截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，请更新至HTTPX2兼容的RESPX版本或分支。仅修补旧版HTTPX的RESPX版本无法拦截SDK的默认HTTPX2客户端。如果您无法立即迁移该集成，下面的临时旧版客户端逃生舱口可让现有仅HTTPX的RESPX设置在迁移期间继续工作。
临时逃生舱口：旧版HTTPX客户端
依赖仅HTTPX传输、集成或模拟库的应用程序可以显式安装旧版HTTPX并注入旧版客户端：
bash
pip install openai httpx
旧版HTTPX支持仅限运行时。SDK的公开类型注解接受HTTPX2客户端，因此直接传递旧版客户端会在mypy、Pyright等工具中导致静态类型检查失败。有意选择此兼容路径时，请使用cast(Any, ...)或针对性的type-ignore：
```python from typing import Any, cast import httpx from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client())) ```
异步形式需要相同的变通方法：
```python from typing import Any, cast import httpx from openai import AsyncOpenAI
client = AsyncOpenAI(http_client=cast(Any, httpx.AsyncClient())) ```
旧版客户端保留HTTPX请求、响应和异常系列。请求原始响应为httpx.Response，使用相同的类型检查变通方法处理旧版响应类：
```python from typing import Any, cast import httpx from openai import OpenAI
client = OpenAI(httpclient=cast(Any, httpx.Client())) response = client.get("/models", castto=cast(Any, httpx.Response)) assert isinstance(response, httpx.Response) ```
传递cast_to=httpx2.Response不会将旧版HTTPX响应转换为HTTPX2响应。请自行安装和维护旧版依赖。旧版HTTPX支持作为迁移辅助提供，可能在未来停止。
现有旧版aiohttp适配器
如果您必须保留现有的httpx-aiohttp集成，请显式安装并注入其旧版客户端：
bash
pip install openai httpx-aiohttp
```python from typing import Any, cast from httpx_aiohttp import HttpxAiohttpClient from openai import AsyncOpenAI
client = AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient())) ```
评论
根据评论内容，主要观点和论据总结如下：
支持方观点（认可度：中性偏正面） - 评论1指出“操作系统TLS信任存储现在被使用（替代了certifi）”，强调技术改进。 - 评论3表示“终于...”，暗示期待已久。 - 评论7认为“这是迟早的事...肯定有某些优势”，持接受态度。
质疑方观点（认可度：中性偏负面） - 评论2提问“这个改变有什么好处？”，质疑变更的合理性。 - 评论4指出“httpx作为依赖的问题在于它正朝着1.0版本发展，将充满破坏性变更”，并提到“httpx2项目本质上是承诺不破坏现有API的分支”，暗示稳定性风险。 - 评论6建议“为什么不给PSF投钱进行针对性改进和扩展”，认为应优先改进现有requests库。
技术讨论焦点 - 评论5质疑“为什么大家迁移到http3这么慢？”，关注技术演进速度。 - 评论8询问“是否评估过httpx2 vs niquests”，提及替代方案。 - 评论9反问“为什么要用HTTPX2而不是requests？”，表达对requests库的偏好。
关键引用保留： - 评论1: "operating system TLS trust store is used now (instead of certifi)" - 评论4: "The problem with httpx as a dependency is that it's currently working towards a 1.0 release which will be full of breaking changes" - 评论6: "I don't understand why OpenAI and Anthropic don't just throw some $$$ to the PSF for focused improvements and expansion of it"