Consider migrating from httpx to httpx2

快速结论：该报错/问题发生在使用 OpenAI Python SDK 时，底层 HTTP 客户端 httpx 自 2024 年起停止维护，社区建议迁移至由 Pydantic Services Inc. 维护的 httpx2。优先排查方式：将 openai Python SDK 升级到 v3.0.0 或更高版本，该版本已默认使用 HTTPX2，且不再自动安装 httpx。

适用环境：openai-python SDK（Stainless 生成器生成）；已确认影响的 SDK 包括 openai 2.45.0、anthropic 0.116.0、groq 1.5.0（均为 Stainless 生成）；对比验证：cohere 7.0.5（Fern 生成器，鸭式类型，无名义检查）、mistralai 2.6.0（Speakeasy 生成器，使用 @runtime_checkable Protocol）。

最快修复方案：升级 openai Python SDK 至 v3.0.0（含）以上。该版本已完成 HTTPX2 迁移，HTTPX2 为默认 HTTP 客户端，httpx 不再自动安装。升级后无需其它手动操作即可消除“卡在无人维护的传输层”的风险。

注意事项：该修复（PR #3594）未完全满足本线程中讨论的所有要求。httpx 作为基础依赖在 openai[httpx2] extra 中仍会被安装（#3524 的现状），且即使使用 httpx2 客户端，URL 解析仍需经过 httpx（包括 _prepare_url 和 _build_request）。若需要彻底移除 httpx 依赖，需等待未来主版本将 httpx 设为可选依赖。

问题场景

用户在使用 OpenAI Python SDK（openai-python）时，底层 HTTP 客户端 httpx 已实质上无人维护——自 2024 年起无新版本发布，Issue 和讨论被关闭但得不到解决。社区建议迁移到 httpx2（由 Pydantic Services Inc. 维护，原作者 Tom Christie 参与）。该问题最初以 Issue 形式提出，随后有社区成员提交了候选实现（PR #3479），最终由官方在 v3.0.0 版本中完成迁移（PR #3594）。

报错原文

Consider migrating from httpx to httpx2

`httpx` has become effectively unmaintained — no releases since 2024, issues and discussions are being closed without resolution. The ecosystem is moving to `httpx2`, the successor maintained by Pydantic Services Inc. with the original author (Tom Christie).

原因分析

问题根因并不在 openai-python SDK 的 spec 生成代码中，而是位于 Stainless 共享运行时（shared runtime）。_base_client.py 中的类型检查是名义检查（nominal check），使用 isinstance 判断客户端实例是否为 httpx.AsyncClient。由于 httpx2.AsyncClient 是独立的类，与 httpx.AsyncClient 没有共享的 MRO，因此在构造时会被直接拒绝：

if http_client is not None and not isinstance(http_client, httpx.AsyncClient):
    raise TypeError("Invalid `http_client` argument; Expected an instance of `httpx.AsyncClient` ...")

该问题同时影响多个由 Stainless 生成的 SDK（openai、anthropic、groq），而其它生成器（Fern、Speakeasy）已经采用了更宽松的类型检查方式。

环境排查

确认 openai Python SDK 版本：如为 2.45.0 或更早版本，则存在该类型检查限制。
确认相关 SDK 的生成器类型：Stainless 生成器生成的 SDK（openai、anthropic、groq）均存在相同问题。
对比验证：cohere（Fern 生成器）和 mistralai（Speakeasy 生成器）已支持 httpx2.AsyncClient，无需额外配置。
检查当前环境中 httpx 的安装情况：如果同时安装了 httpx 和 httpx2，需注意 httpx 仍会参与 URL 解析过程。

解决步骤

将 openai Python SDK 升级至 v3.0.0 或更高版本（该版本通过 PR #3594 完成了 HTTPX2 迁移）。
升级后确认 HTTPX2 为默认 HTTP 客户端，且 httpx 不再自动安装。
如需继续使用自定义 HTTP 客户端，请确认传入的客户端实例与 httpx2 兼容（升级到 v3.0.0 后，类型检查已放宽，不再拒绝 httpx2 客户端）。
若项目中同时依赖 httpx（如通过其它包间接引入），可评估是否需要在未来主版本中彻底移除 httpx 依赖——这需要等待官方将 httpx 设为可选依赖。

验证方法

确认 openai SDK 版本 ≥ 3.0.0 后，创建一个 OpenAI 客户端并传入 http_client=httpx2.AsyncClient()，确认不再抛出 TypeError。同时检查环境中的 httpx 包是否已不存在（如果使用了 openai[httpx2] extra，httpx 仍会被安装——这是当前已知限制）。