调用 OpenAI API 或 OpenAI-compatible 网关时日志里出现 502、503 或超时最常见的误判是“我的代码只调用了一次所以服务端只收到一次请求”。OpenAI Python SDK 本身有自动重试如果业务层、任务队列或反向代理又各自重试一次用户操作可能被放大成多次上游请求。排查这类问题先不要立刻把重试次数从 2 改成 10。应该先记录 SDK 版本、异常类型、request ID、实际请求次数和每次耗时再决定 5xx 是否值得重试。本文锁定官方 openai2.48.0用只监听 127.0.0.1 的 fixture 复现三组行为默认重试两次后成功、禁用重试后首次 503 即失败、极短 timeout 触发 APITimeoutError。没有请求线上 OpenAI 或第三方 provider。## 先跑这 5 步### 1. 固定 SDK 版本bashpython3 -m venv /tmp/openai-sdk-checksource /tmp/openai-sdk-check/bin/activatepython -m pip install openai2.48.0python -c import openai; print(openai.__version__)本文实测版本是 2.48.0。先固定版本是因为“默认重试哪些状态、默认 timeout 多长、异常类叫什么”属于 SDK 行为不能只凭旧文章或另一个语言 SDK 推断。### 2. 先知道默认重试了什么官方 README 写明连接错误、408、409、429 和 500 默认自动重试 2 次并使用短指数退避。这里的“2 次”是首次请求失败后最多再试两次因此最坏情况下可能看到 3 次请求。pythonfrom openai import OpenAIclient OpenAI(api_keyYOUR_API_KEY,base_urlhttps://your-endpoint.example/v1,)如果业务代码外层还有三次重试不能把两个数字简单理解成总共五次嵌套重试可能形成乘法。先用服务端 request ID、访问日志或本地计数器确认真实次数。### 3. 诊断时可临时关闭 SDK 重试pythonclient OpenAI(api_keyYOUR_API_KEY,base_urlhttps://your-endpoint.example/v1,max_retries0,)max_retries0 适合做一次受控诊断让第一次 503 原样暴露确认错误体、响应头和 request ID。它不等于“生产环境永远不重试”。生产策略还要考虑请求是否幂等、用户能否接受重复执行、上游是否给出 Retry-After以及业务层是否已有队列重试。### 4. 捕获异常并记录 request IDpythonimport openaitry:response client.chat.completions.create(modelyour-model-id,messages[{role: user, content: reply with OK}],)print(response._request_id)except openai.APIStatusError as exc:print(type(exc).__name__)print(exc.status_code)print(exc.request_id)成功响应的公开 _request_id 来自 x-request-id 头失败状态则从 APIStatusError.request_id 读取。第三方兼容网关不一定提供这个头缺失时应如实记 missing_request_id不要自己生成一个值冒充上游 ID。### 5. 把 timeout 与 5xx 分开pythonimport httpxfrom openai import OpenAIclient OpenAI(api_keyYOUR_API_KEY,base_urlhttps://your-endpoint.example/v1,max_retries0,timeouthttpx.Timeout(20.0, connect2.0, read10.0, write10.0),)官方 SDK 默认请求超时是 10 分钟可以传一个秒数也可以用 httpx.Timeout 分开设置连接、读取和写入。客户端等待超时通常抛 APITimeoutError它不等同于服务端返回 HTTP 504也不等同于 502/503。三者的观测点和修复动作不同。## 本地实测默认 3 次请求关闭重试后 1 次本地 fixture 按请求头分三种场景- retry前两次返回 503第三次返回 200。- no-retry始终返回 503并携带 x-request-id。- timeout延迟响应超过客户端极短读取时间。执行bashpython 06-evidence/probe_openai_sdk_5xx.py本次输出textOPENAI_VERSION2.48.0DEFAULT_RETRY_REQUESTS3DEFAULT_RETRY_FINAL_HTTP200DEFAULT_RETRY_TEXTSDK_RETRY_OKNO_RETRY_REQUESTS1NO_RETRY_ERRORInternalServerErrorNO_RETRY_HTTP503NO_RETRY_REQUEST_IDreq_no_retry_1TIMEOUT_REQUESTS1TIMEOUT_ERRORAPITimeoutErrorONLINE_PROVIDER_REQUESTNO这组结果证明在本文锁定版本和本地夹具下默认配置把两次 503 重试成第三次成功max_retries0 让第一次 503 直接暴露并从响应头读回 request ID极短 timeout 得到单独的超时异常。它不能证明线上 provider 的恢复率也不能说明所有 503 都应该重试。## 502/503 的排查顺序### 第一步确认错误来自哪一层记录最终请求 URL 的主机、状态码、响应 Content-Type、错误类型和 request ID。502 常见于代理没有拿到有效上游响应503 常见于服务暂不可用或过载但不同网关会重写状态最终仍要看目标服务的错误体和链路日志。### 第二步确认 SDK 已经请求了几次不要只看业务函数调用次数。对同一次逻辑操作用稳定的本地 trace ID 关联每次下游请求再分别记录上游 request ID。若业务层一次、SDK 三次、队列再重跑一次就已经存在明显放大。### 第三步决定哪些请求允许重试纯文本推理通常可以在明确边界下重试但带工具执行、写数据库、发消息或扣费的 Agent 任务可能产生外部副作用。即使 API 本身幂等工具调用也未必幂等。重试前要确认请求是否已被上游接受以及业务是否有幂等键。### 第四步给重试设总预算总预算至少包括最大次数、总耗时和退避上限。不要让 SDK、代理、任务队列和页面按钮各自无限等待。若 503 持续存在应停止重试并保留最后一个 request ID、错误体摘要和时间窗口交给服务端排查。## 一张检查清单text[ ] openai SDK 版本已固定[ ] 记录异常类型、HTTP 状态和 request ID[ ] 确认默认 max_retries 与业务外层重试是否叠加[ ] 诊断时用 max_retries0 暴露第一次错误[ ] 区分 502、503、504 与 APITimeoutError[ ] 记录实际请求次数和总耗时[ ] 对工具调用和写操作设置幂等边界[ ] 日志中没有完整 Key、Cookie 或用户数据## 总结OpenAI Python SDK 遇到 502/503 时先还原真实请求次数再谈增加重试。openai2.48.0 默认会对 500 再试两次max_retries0 能让第一次错误原样暴露失败的 APIStatusError 可读取 request IDtimeout 则是另一条异常路径。把这些信号记录完整才能判断是短暂上游波动、代理路径错误、客户端等待超时还是多层重试已经放大了故障。
调用 OpenAI API 或 OpenAI-compatible 网关时日志里出现 502、503 或超时最常见的误判是“我的代码只调用了一次所以服务端只收到一次请求”。OpenAI Python SDK 本身有自动重试如果业务层、任务队列或反向代理又各自重试一次用户操作可能被放大成多次上游请求。排查这类问题先不要立刻把重试次数从 2 改成 10。应该先记录 SDK 版本、异常类型、request ID、实际请求次数和每次耗时再决定 5xx 是否值得重试。本文锁定官方 openai2.48.0用只监听 127.0.0.1 的 fixture 复现三组行为默认重试两次后成功、禁用重试后首次 503 即失败、极短 timeout 触发 APITimeoutError。没有请求线上 OpenAI 或第三方 provider。## 先跑这 5 步### 1. 固定 SDK 版本bashpython3 -m venv /tmp/openai-sdk-checksource /tmp/openai-sdk-check/bin/activatepython -m pip install openai2.48.0python -c import openai; print(openai.__version__)本文实测版本是 2.48.0。先固定版本是因为“默认重试哪些状态、默认 timeout 多长、异常类叫什么”属于 SDK 行为不能只凭旧文章或另一个语言 SDK 推断。### 2. 先知道默认重试了什么官方 README 写明连接错误、408、409、429 和 500 默认自动重试 2 次并使用短指数退避。这里的“2 次”是首次请求失败后最多再试两次因此最坏情况下可能看到 3 次请求。pythonfrom openai import OpenAIclient OpenAI(api_keyYOUR_API_KEY,base_urlhttps://your-endpoint.example/v1,)如果业务代码外层还有三次重试不能把两个数字简单理解成总共五次嵌套重试可能形成乘法。先用服务端 request ID、访问日志或本地计数器确认真实次数。### 3. 诊断时可临时关闭 SDK 重试pythonclient OpenAI(api_keyYOUR_API_KEY,base_urlhttps://your-endpoint.example/v1,max_retries0,)max_retries0 适合做一次受控诊断让第一次 503 原样暴露确认错误体、响应头和 request ID。它不等于“生产环境永远不重试”。生产策略还要考虑请求是否幂等、用户能否接受重复执行、上游是否给出 Retry-After以及业务层是否已有队列重试。### 4. 捕获异常并记录 request IDpythonimport openaitry:response client.chat.completions.create(modelyour-model-id,messages[{role: user, content: reply with OK}],)print(response._request_id)except openai.APIStatusError as exc:print(type(exc).__name__)print(exc.status_code)print(exc.request_id)成功响应的公开 _request_id 来自 x-request-id 头失败状态则从 APIStatusError.request_id 读取。第三方兼容网关不一定提供这个头缺失时应如实记 missing_request_id不要自己生成一个值冒充上游 ID。### 5. 把 timeout 与 5xx 分开pythonimport httpxfrom openai import OpenAIclient OpenAI(api_keyYOUR_API_KEY,base_urlhttps://your-endpoint.example/v1,max_retries0,timeouthttpx.Timeout(20.0, connect2.0, read10.0, write10.0),)官方 SDK 默认请求超时是 10 分钟可以传一个秒数也可以用 httpx.Timeout 分开设置连接、读取和写入。客户端等待超时通常抛 APITimeoutError它不等同于服务端返回 HTTP 504也不等同于 502/503。三者的观测点和修复动作不同。## 本地实测默认 3 次请求关闭重试后 1 次本地 fixture 按请求头分三种场景- retry前两次返回 503第三次返回 200。- no-retry始终返回 503并携带 x-request-id。- timeout延迟响应超过客户端极短读取时间。执行bashpython 06-evidence/probe_openai_sdk_5xx.py本次输出textOPENAI_VERSION2.48.0DEFAULT_RETRY_REQUESTS3DEFAULT_RETRY_FINAL_HTTP200DEFAULT_RETRY_TEXTSDK_RETRY_OKNO_RETRY_REQUESTS1NO_RETRY_ERRORInternalServerErrorNO_RETRY_HTTP503NO_RETRY_REQUEST_IDreq_no_retry_1TIMEOUT_REQUESTS1TIMEOUT_ERRORAPITimeoutErrorONLINE_PROVIDER_REQUESTNO这组结果证明在本文锁定版本和本地夹具下默认配置把两次 503 重试成第三次成功max_retries0 让第一次 503 直接暴露并从响应头读回 request ID极短 timeout 得到单独的超时异常。它不能证明线上 provider 的恢复率也不能说明所有 503 都应该重试。## 502/503 的排查顺序### 第一步确认错误来自哪一层记录最终请求 URL 的主机、状态码、响应 Content-Type、错误类型和 request ID。502 常见于代理没有拿到有效上游响应503 常见于服务暂不可用或过载但不同网关会重写状态最终仍要看目标服务的错误体和链路日志。### 第二步确认 SDK 已经请求了几次不要只看业务函数调用次数。对同一次逻辑操作用稳定的本地 trace ID 关联每次下游请求再分别记录上游 request ID。若业务层一次、SDK 三次、队列再重跑一次就已经存在明显放大。### 第三步决定哪些请求允许重试纯文本推理通常可以在明确边界下重试但带工具执行、写数据库、发消息或扣费的 Agent 任务可能产生外部副作用。即使 API 本身幂等工具调用也未必幂等。重试前要确认请求是否已被上游接受以及业务是否有幂等键。### 第四步给重试设总预算总预算至少包括最大次数、总耗时和退避上限。不要让 SDK、代理、任务队列和页面按钮各自无限等待。若 503 持续存在应停止重试并保留最后一个 request ID、错误体摘要和时间窗口交给服务端排查。## 一张检查清单text[ ] openai SDK 版本已固定[ ] 记录异常类型、HTTP 状态和 request ID[ ] 确认默认 max_retries 与业务外层重试是否叠加[ ] 诊断时用 max_retries0 暴露第一次错误[ ] 区分 502、503、504 与 APITimeoutError[ ] 记录实际请求次数和总耗时[ ] 对工具调用和写操作设置幂等边界[ ] 日志中没有完整 Key、Cookie 或用户数据## 总结OpenAI Python SDK 遇到 502/503 时先还原真实请求次数再谈增加重试。openai2.48.0 默认会对 500 再试两次max_retries0 能让第一次错误原样暴露失败的 APIStatusError 可读取 request IDtimeout 则是另一条异常路径。把这些信号记录完整才能判断是短暂上游波动、代理路径错误、客户端等待超时还是多层重试已经放大了故障。
