Python 调大模型 API 五大坑，一次讲清楚

# Python 调用大模型 API 的结构化摘要 **文章主旨：** 第一次用 Python 调通大模型 API 只是最简单的一步，真正决定代码能否长期运行的关键，是理解 SDK 在失败时替你做了什么，并能判断每个错误该“重试等待”还是“回头改代码”。 **关键要点：** 1. 最小调用只需三件事——构造客户端、发请求、取结果；客户端应复用，Key 应放入环境变量而非写死在代码中。 2. SDK 默认 `max_retries=2`，且重试发生在单次调用内部；批量任务不能只依赖它，还要看频率、并发、配额与任务调度。 3. `timeout` 管"一次尝试怎么等"，`retry` 管"失败后还试不试"，二者需绑定理解；默认超时为 10 分钟且超时也会被重试。 4. 400、401 属确定性错误，应改参数或检查 Key/权限，重试无用；429、超时、连接故障才考虑重试。 5. 兼容网关场景下可能出现 `OpenAIError` 体系之外的解析错误（如 `json.JSONDecodeError`），不能把 `except OpenAIError` 当作万能兜底。 **内容结构：** - **开篇：跑通容易，真难在循环里** 作者指出：装 SDK、填 Key、跑几行代码就能得到回答，容易造成“已会调 API”的错觉。麻烦要等代码进入批量循环才出现——429、卡住、400 交替出现。本篇不提供"复制即用"的魔法代码，而是拆解一次调用的全过程与错误语义。 - **01 先把最小调用跑通，但别急着庆祝** 以 `OpenAI()` + `responses.create` + `response.output_text` 展示最小调用，指出三要素：构造客户端（负责鉴权、连接复用、默认重试和超时）、发请求、取结果。对比旧版 Chat Completions 写法，说明其仍受支持但 Responses API 已成为主要入口。提醒不要把 Key 写死进待提交的代码。 - **02 429：SDK 会替你重试，但别当无限续命** 429 通常与限流/配额有关。SDK 默认 `max_retries=2`（单次调用最多 3 次尝试），可设 `max_retries=0` 关闭。作者通过本地 mock 注入 429 对比两种配置行为，强调重试发生在单次调用内部，批量任务最坏情况下请求数可能远高于预期。指出 SDK 会读取 `retry-after-ms`/`Retry-After`，并在合理范围内优先按服务端等待提示处理，否则走带抖动的指数退避。不建议在 SDK 外再套无条件 `while True: retry()`。 - **03 超时：你设的是“一次尝试怎么等”，不是整个任务的秒表** 指出常见误解：`timeout=30` 不等于整个调用 30 秒结束。SDK 当前默认超时为 10 分钟，可按客户端或单次请求设置。mock 测试（服务端延迟 3 秒、客户端 `timeout=1.0`）会抛 `APITimeoutError`，且超时本身也属默认重试范围。结论：timeout 与 retry 要一起看，具体数值取决于交互式产品还是离线批处理，没有“全行业最佳数字”。 - **04 400：这种错误别重试，先去看自己发了什么** 400 通常说明请求本身有问题（字段、参数组合、请求体格式等），同样请求重发结果一样，SDK 不会默认重试，直接抛 `BadRequestError`。作者建议按“下一步该干什么”给错误分类：429/超时/连接故障 → 考虑退避重试限速；400/401 → 改参数、查 Key 与权限。核心习惯是：先判断这个错误有没有可能“等一等自己变好”。 - **05 异常别只会写一个 `except Exception`** 给出 SDK 异常继承关系（`RateLimitError`、`BadRequestError` → `APIStatusError` → `APIError` → `OpenAIError`；`APITimeoutError` → `APIConnectionError` → …），并示范分类捕获的代码：限流、超时、请求参数、鉴权、其他 SDK 错误各归其位。好处是排错时不用猜——错误类型本身就是排查方向。 - **06 兼容端点还有一层坑：别假设所有异常都会被 SDK 包好** 官方端点遵循官方契约，但代理、网关、自建服务或“OpenAI 兼容接口”可能不一致。作者对本地 mock 兼容端点注入“HTTP 成功但响应体非合法 JSON”时，原生 `json.JSONDecodeError` 会直接冒出，不属于 `OpenAIError`。提醒在流式响应、代理改写、自建兼容层中可能还有 SDK 异常体系之外的解析错误，最好把“官方 SDK 错误”和“外围协议/解析错误”分开记录。 - **07 把它拼成一份真正能改的最小脚本** 给出一份骨架脚本：客户端设置 `timeout=30.0, max_retries=2`，`ask()` 函数分类捕获 `RateLimitError`、`APITimeoutError`、`BadRequestError`、`AuthenticationError`、`json.JSONDecodeError`、`OpenAIError`，打印定位信息后重新抛出；作者特意不把错误变成普通字符串返回，避免下游把“限流了”当成模型答案写进数据库。这一层负责识别和记录，是否跳过/重试/降级交给外层任务逻辑。 - **08 真正学会调 API，是失败以后知道下一步做什么** 总结四件事：（1）SDK 会重试一部分临时错误，但不是所有错误都值得重试；（2）timeout 与 retry 是两件事；（3）400、401 先改请求和凭证，别靠重跑碰运气；（4）批量任务的可靠性不能全部甩给 SDK，最终限速、失败记录、跳过或终止要由业务逻辑决定。建议下次遇到“跑到第 17 条突然挂了”时，先看异常类型和重试/超时配置，而非直接删掉重跑。 **文章总结：** 文章以“能跑通不等于可控”为核心态度，主张从判断错误性质出发建立正确的重试与异常处理习惯，让 API 调用从“能跑”走向“可控”。