OpenAI Python SDK 超时与重试怎么处理？用国产模型接口做一次错误分层教学

首次调用大模型 API 时，很多人会写一个“失败就重试”的循环。它看起来提高了成功率，却可能把一次超时放大成多次调用，把配置错误掩盖成网络不稳定。

这篇教程以 FlowBarCN 国内站的文本接口为例，给出一个便于诊断的命令行脚本：只发起一次请求，区分连接、超时和 HTTP 状态错误，再决定下一步该查什么。重点是建立错误处理顺序，而不是承诺自动重试能解决所有问题。

作者说明：本文由 FlowBarCN 团队提供，使用自家服务作为配置示例，内容由 AI 辅助整理。验证日期为 2026 年 10 月 22 日。本次执行的是本地模拟测试，没有新增付费模型调用，也没有主动对线上服务制造故障。

1. 先区分三种失败

层次	典型表现	首先检查
连接层	APIConnectionError	网络、代理、DNS、TLS 和服务是否可达
等待阶段	APITimeoutError	客户端超时设置、链路延迟和服务处理情况
HTTP 响应	APIStatusError	状态码和受控环境中的脱敏错误信息

超时异常需要放在连接异常之前捕获，避免被更宽泛的连接错误分支提前处理。HTTP 状态码只能缩小范围，不能单凭 429 就断言一定是余额不足，也不能单凭 404 就断言一定是模型名错了。

2. 为什么教学阶段先关闭自动重试？

OpenAI Python SDK 支持自动重试。排错时如果外层又套了一层重试，实际请求次数可能比肉眼看到的函数调用次数多。本文设置 max_retries=0，并且没有外层循环，让一次脚本执行对应一次生成尝试。

这不意味着生产环境永远不能重试。是否重试，需要结合错误性质、总时限、费用预算和业务是否允许重复结果决定。尤其是连接中断或超时后，客户端没有拿到结果，不等于服务端没有执行。

3. 创建环境并保存完整脚本

本文使用 Windows、Python 3.11.9 和 openai==3.35.1。在 PowerShell 中运行：

python -m venv .venv
.venv\Scripts\python.exe -m pip install openai==3.35.1
$env:FLOWBAR_API_KEY = "替换为你自己的 FlowBarCN API Key"

把下面内容保存为 diagnose.py。密钥由环境变量读取，不能写入源码；示例模型与账号权限、可用额度需要自行核对。

import os
import sys
import time
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError


def ask_once(client):
    started = time.monotonic()
    try:
        result = client.chat.completions.create(
            model='deepseek-v4-flash-0731-new',
            messages=[{'role': 'user', 'content': '请用一句话解释什么是 API。'}],
            max_tokens=128,
        )
    except APITimeoutError:
        return {'ok': False, 'kind': 'timeout', 'auto_retry': False}
    except APIConnectionError:
        return {'ok': False, 'kind': 'connection', 'auto_retry': False}
    except APIStatusError as exc:
        return {'ok': False, 'kind': 'http', 'status': exc.status_code,
                'auto_retry': False}
    if not result.choices or not result.choices[0].message.content:
        return {'ok': False, 'kind': 'empty_text', 'auto_retry': False}
    return {'ok': True, 'answer': result.choices[0].message.content,
            'elapsed_seconds': round(time.monotonic() - started, 2)}


def main():
    key = os.getenv('FLOWBAR_API_KEY', '').strip()
    if not key:
        sys.exit('请先设置 FLOWBAR_API_KEY')
    with OpenAI(api_key=key, base_url='https://flowbar.cn/v1',
                timeout=30.0, max_retries=0) as client:
        print(ask_once(client))


if __name__ == '__main__':
    main()

运行命令：

.venv\Scripts\python.exe diagnose.py

使用真实密钥运行会产生实际生成请求，可能计费。脚本没有输出密钥、请求头或上游完整错误正文。成功分支会输出模型回答，因此也不要把包含业务敏感内容的终端输出随意共享。

4. 读懂脚本返回值

正常结果包含 ok、answer 和 elapsed_seconds。耗时用单调时钟计算，仅代表本次函数的观察时间，不能当作吞吐量或稳定性指标。

失败结果使用固定分类：timeout 表示超时，connection 表示其他连接问题，http 表示收到错误 HTTP 状态，empty_text 表示没有获得可用文本。auto_retry=False 是本脚本的策略标识，不是上游协议字段。

timeout=30.0 配置的是客户端网络超时行为，不是一个严格的“业务总耗时 30 秒”闹钟。若要实现总时限，还需在任务调度、队列和业务层共同控制。

5. 哪些错误适合重试，哪些应先停下？

结果	优先动作	重试前的条件
401	检查密钥有效性、归属和是否复制完整	配置修正后再调用
403	检查账号或访问策略	权限问题解决后再调用
404	核对 Base URL、接口路径和具体报错	修正路径或模型配置
429	区分频率、额度或其他限制	按错误信息处理；若响应提供 Retry-After，应纳入等待策略
5xx	检查服务状态和错误频率	允许重复、次数和总时间均受限时再考虑
超时或断连	判断是否可能已经处理	不确定时避免立即无限重发

生产环境可以采用有上限的退避等待，并加入随机抖动，避免多个客户端同时再次冲击服务。但重试策略最好只由一层负责：如果业务代码控制重试，就要明确 SDK 是否还会自动重试。

对一次性任务，还要单独设计业务去重。不能假设兼容接口一定支持某个幂等请求头，更不能认为换一个请求编号就能避免重复计费。

6. 空回答也要和网络错误分开

HTTP 成功并不代表一定拿到了可展示文本。脚本先检查 choices，再检查 message.content，避免直接读取空列表。

如果返回 empty_text，应检查输出上限、结束原因和该模型的响应行为。本文只展示普通文本接口，没有处理工具调用、音频或其他非文本输出；不能把非文本响应都归为服务故障。

本例 max_tokens=128 适合短句演示，不适合直接搬到长文章或复杂推理任务。调整上限时，也要同时考虑成本和等待时间。

7. 流式响应为什么不能照搬普通重试？

流式输出已经显示了一半文字后发生中断，如果再次从头请求，用户可能看到重复文本，服务端也可能执行两次。业务层至少需要区分“尚未显示任何输出”和“已经显示部分输出”。

这篇脚本没有实现流式恢复，也没有对线上流式异常做测试。需要流式输出时，应先设计取消、部分结果提示和重新生成按钮，再处理网络重试。

8. 本次验证结果与边界

本地使用真实安装的 SDK 配合模拟 HTTP 传输，覆盖成功、401、429、500、连接失败、读超时和空 choices。每种情况均检查只发出一次模拟请求，并确认脚本结果不包含模拟上游错误正文。

模拟验证可以复现异常分支，不需要用真实密钥撞错或对生产服务施加压力；它不能证明线上当时的模型可用性、延迟或账单。本文没有报告新的真实调用成功率。

遇到问题时，先分清连接、等待、状态和内容四个层面，再决定是否重试，比直接增加重试次数更有助于定位原因。

参考资料

• FlowBarCN API 接入文档
• FlowBarCN 模型目录
• OpenAI Python SDK：错误、重试与超时