OpenAI Python SDK默认HTTP客户端切换为HTTPX2

说得更直白一点,HTTPX是Python程序用来与互联网另一端服务器通信的工具,证书验证则是确认通信对象是否真的是OpenAI服务器的一道程序。此前这道验证依靠一个叫certifi的独立包所持有的证书列表来完成,如今改为使用每台电脑、每台服务器本身自带的操作系统证书存储。

变化的不只是通信工具的名字,证书验证的基准本身也随之改变。过去SDK是依据certifi提供的CA证书列表来核验服务器证书,而HTTPX2则改用操作系统自带的信任存储。SDK现在也不再单独安装certifi了。

这一变化为何可能造成问题

问题在于,并非所有环境都完备地具备这套操作系统证书存储。指南指出,缺少系统CA证书的精简容器镜像、使用TLS检测代理来审查内部流量的企业环境,以及依赖自定义或修改过的certifi证书包的部署,都可能出现证书验证失败的情况。这意味着,原本运行正常、无需额外配置的服务器,可能仅仅因为更新了SDK版本,就开始出现连接错误。

开发者现在应该检查什么

指南给出的应对方法是:要么直接在操作系统信任存储中安装所需的CA证书,要么明确指定证书包路径。这些设置在trust_env=True(默认值)时也可以通过环境变量生效,此外还可以把ssl.SSLContext作为verify参数传入自定义客户端,自行指定信任范围。

与既有代码的兼容性在很大程度上得以保留。如果创建OpenAI或AsyncOpenAI客户端时没有单独指定http_client,那么API调用、响应模型解析、流式传输、身份验证、重试机制以及以数字形式设置的超时时间都能照常运作。DefaultHttpxClient、DefaultAsyncHttpxClient这两个名称也可以继续使用,只不过内部实现已经改为生成HTTPX2客户端。指南建议,如果想明确表明所用客户端类型,可以改用DefaultHttpx2Client、DefaultAsyncHttpx2Client。

反过来,也有需要动手调整的地方。自定义的身份验证处理器或钩子函数,现在接收的是HTTPX2的请求与响应对象,相关类需要相应更新;如果测试代码中使用了RESPX之类的模拟(mock)库,也需要换成能够拦截HTTPX2的版本。指南指出,原本针对httpx设计的适配器,无法拦截SDK新的默认客户端。

对于暂时无法完成迁移的项目,指南也留了一条过渡通道。只要单独安装httpx并显式注入旧版客户端,就能暂时继续使用基于HTTPX的既有代码。不过指南特别强调,这条路径仅在运行时有效,若要通过静态类型检查,还需要用cast(Any, ...)之类的方式绕过,而且这项支持本身未来也可能被取消。

表格看懂前后变化

项目	此前(HTTPX)	变更后(HTTPX2)
默认HTTP客户端	httpx	httpx2
是否自动安装	安装openai时自动安装	安装openai时自动安装,httpx不再自动安装
证书信任基准	certifi CA证书包	操作系统信任存储
DefaultHttpxClient行为	生成HTTPX客户端	名称保留,内部生成HTTPX2客户端
旧版支持	不适用	显式安装后提供运行时兼容通道(可能被取消)

编辑视角

这次变化和OpenAI发布新模型或调整价格的动作性质不同。但对于真正接入OpenAI API运营服务的开发者来说,这类改动带来的风险不亚于——甚至可能比——模型更新更容易被忽视。模型名称一变,谁都能注意到;可HTTP客户端底层的调整,往往要等到部署突然失败之后才会被发现。

把这次SDK变化,和OpenAI近期将GPT-5.6 Luna输入、输出token价格双双下调80%的价格战放在一起看,能看出OpenAI眼下同时盯着两条战线:一条是与中国低价模型的价格竞争,另一条是如何让开发者更顺畅地使用API。改动SDK的默认通信层和证书验证基准,虽然不起眼,但对大规模调用OpenAI API的企业而言,这直接关系到部署的稳定性。

从实操角度看,不妨先排查三件事。第一,正在运行的容器镜像中是否确实包含系统CA证书。第二,是否存在依赖企业内部TLS检测代理或自定义证书包的部署。第三，如果测试代码中使用了RESPX之类的HTTP模拟库,要确认其版本是否兼容HTTPX2。在重新安装或升级openai包之前先确认好这三点,能大幅减少部署当天因证书错误而措手不及的情况。

既然OpenAI已经明确把对旧版HTTPX的支持定位为迁移过渡手段,那么这条兼容通道迟早会被取消。从现在起就按HTTPX2的标准整理代码,会是更稳妥的做法。