`httpx.PoolTimeout` occurs frequently with SyncClient

问题场景

用户在生产应用中使用 OpenAI Python SDK 的 SyncClient，以每秒约 3-6 次的频率向 ChatCompletions 端点发起请求。在流量高峰时段，请求会频繁因 httpx.PoolTimeout 失败，导致下游任务堆积。用户最初在 v1.2.3 迁移前就遇到请求卡在默认 600 秒超时的问题，迁移到 v1.2.4 后问题依旧，并通过设置 30 秒超时和重试来缓解，但仍持续出现 httpx.PoolTimeout。

报错原文

httpx.PoolTimeout occurs frequently with SyncClient

原因分析

最可能的原因是 OpenAI Python SDK 的默认 httpx 客户端连接池配置不适合较高并发场景。当并发请求数超过默认池上限时，新请求需要等待可用连接，若等待时间超过池超时设置便抛出 httpx.PoolTimeout。Issue 中维护者指出，默认超时时间较长会加剧池问题（与 #769 有关），并确认在 v1.15.0 中已提高默认连接池上限作为改进。另有用户反馈，常规超时（非 pool timeout）在 v0 和 v1 上都有约 1/10 的发生率，这部分可能与应用侧网络或服务端响应有关，属于独立问题。

环境排查

• 确认 OpenAI Python SDK 版本，建议使用 v1.15.0 及以上，该版本已提高默认连接池上限。
• 确认 Python 版本（Issue 中为 3.10.8）与 httpx 依赖版本。
• 确认当前使用的客户端类型是 SyncClient 还是 AsyncClient。
• 确认当前请求频率与并发量，判断是否超过默认连接池上限。
• 确认是否已自定义 httpx.Client 及其 timeout 与 limits 配置。
• 确认常规 read timeout 与 pool timeout 的发生频率和场景，区分两类问题。

解决步骤

1. 优先升级 OpenAI Python SDK 到 v1.15.0 或更高版本。该版本已将默认连接池上限提升到 1000 连接和 100 keepalive 连接（见 PR #1281），若仍使用旧版本可先尝试升级。
2. 如果升级后仍出现 httpx.PoolTimeout，创建一个自定义 httpx.Client，显式设置 timeout 与连接池上限，可优先尝试 Issue 中用户验证过的配置：

   DEFAULT_TIMEOUT = httpx.Timeout(
       timeout=OPENAI_TIMEOUT,
       connect=OPENAI_TIMEOUT,
       pool=OPENAI_TIMEOUT
   )
   DEFAULT_LIMITS = httpx.Limits(
       max_connections=500,
       max_keepalive_connections=100
   )
   
   OpenAIHTTPClient = httpx.Client(
       timeout=DEFAULT_TIMEOUT,
       limits=DEFAULT_LIMITS
   )

3. 将该自定义 httpx.Client 传入 OpenAI 客户端，替换默认客户端。
4. 若仍偶发 pool timeout，进一步调大 max_connections 与 max_keepalive_connections。Issue 中用户最终使用 max_connections=25000、max_keepalive_connections=100。
5. 将超时时间降低到合理范围（如 30 秒或更短），避免 API 调用较快时长时间占用连接，加剧池压力。
6. 对于常规 read timeout（非 pool timeout），Issue 中未给出 SDK 层的明确修复方案，需要单独排查网络或服务端响应问题。

验证方法

在应用中以相同请求频率运行一段时间，观察是否仍出现 httpx.PoolTimeout。如果超时频率明显下降或消失，说明连接池配置调整生效；如果仍有常规 read timeout，需要将其与 pool timeout 区分开，单独分析。

参考来源

openai/openai-python #821

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。