迁移到 HTTPX2 OpenAI Python SDK 现在使用 HTTPX2 作为其同步和异步 HTTP 客户端。HTTPX2 会在安装 openai 时自动安装；之前的 httpx 包则不再安装。本指南解释了与 SDK 的 HTTP 层交互的应用程序所需的更改。 如果您使用 SDK 的默认 HTTP 客户端 如果您在不提供 http_client 的情况下构造 OpenAI 或 AsyncOpenAI 客户端，则您现有的 API 调用、解析的响应模型、流式 API、身份验证、重试以及数字超时继续正常工作： ```python from openai import OpenAI client = OpenAI(timeout=30.0) response = client.responses.create(model="gpt-5.5", input="Hello") ``` 不需要额外或单独安装 HTTPX2： ```bash 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 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 设置。 如果您提供自定义 HTTP 客户端 使用 HTTPX2 客户端和 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 默认值生效，除非您自己进行配置。现有的 DefaultHttpxClient 和 DefaultAsyncHttpxClient 名称继续有效，但现在构造 HTTPX2 客户端。创建 HTTP 客户端家族时优先使用 DefaultHttpx2Client 和 DefaultAsyncHttpx2Client。 模块级配置遵循相同规则： ```python import openai openai.http_client = openai.DefaultHttpx2Client() ``` 超时、URLs、运输和连接设置 将 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)) ``` 数字超时值不会改变。现有的字符串 URLs 不会改变。自定义传输子类、挂载传输、代理集成和连接池仪器必须针对 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。