在调用 AI 接口或开发自动化工具时，遇到 APITimeoutError（请求超时）是家常便饭。如果超时时间设置得不合理，轻则导致程序无限卡死，重则让批量任务大面积报错。本文介绍如何在 Python 中正确管理 API 超时，并处理好长任务。

为什么 AI 请求经常需要更长的超时？

普通的 HTTP 接口（比如查询用户资料、修改状态）通常在毫秒级就能响应。但 AI 模型不同：

• 模型的生成速度受到字数限制（tokens per second）。
• 如果用户要求模型写一篇长文章、分析大段代码或者执行复杂的 Agent 推理，服务端可能需要十几秒甚至几十秒才能完整返回。

如果直接使用默认或过短的超时时间，程序就会频繁报错；而如果把超时时间设得无限长，一旦上游服务卡死，你的客户端也会跟着无限挂起。

因此，合理的超时管理是保证 Python AI 脚本稳定运行的重要一环。

---

一、在 OpenAI 客户端中设置超时

在使用 OpenAI 官方 Python SDK（或兼容客户端）时，超时参数可以分为两类：全局客户端级别 和 单次请求级别。

1. 全局初始化时设置超时

在实例化客户端时，直接传入 timeout 参数（单位为秒）：

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://your-api-domain.com/v1",
    timeout=20.0  # 全局默认超时时间为 20 秒
)

2. 单次请求时覆盖超时

如果某些轻量级任务（如文本分类、翻译短句）需要快速失败，而某些长任务需要更长时间，可以在具体的 create 方法中单独指定：

# 快速任务：5秒超时
quick_resp = client.chat.completions.create(
    model="your-model-name",
    messages=[{"role": "user", "content": "把 'hello' 翻译成中文"}],
    timeout=5.0
)

# 复杂任务：45秒超时
long_resp = client.chat.completions.create(
    model="your-model-name",
    messages=[{"role": "user", "content": "请写一篇关于量子计算的详细论文..."}],
    timeout=45.0
)

---

二、捕获并处理超时异常

当请求超时发生时，SDK 会抛出 APITimeoutError。我们必须在代码中捕获它，并结合我们前面介绍过的重试策略或降级策略来处理：

from openai import OpenAI, APITimeoutError, APIConnectionError

client = OpenAI(
    api_key="your-api-key",
    base_url="https://your-api-domain.com/v1",
)

def safe_ask_with_timeout(prompt: str, timeout_sec: float = 15.0) -> str:
    try:
        response = client.chat.completions.create(
            model="your-model-name",
            messages=[{"role": "user", "content": prompt}],
            timeout=timeout_sec
        )
        return response.choices[0].message.content

    except APITimeoutError:
        print(f"[超时警告] 请求在 {timeout_sec} 秒内未完成，触发超时保护。")
        # 这里可以返回默认提示，或者向上抛出由外层重试装饰器接管
        return "服务响应超时，请稍后重试。"
        
    except APIConnectionError as e:
        print(f"[连接错误] 无法连通服务器: {e}")
        return "网络连接失败。"

---

三、当任务确实很长时：如何避免超时？

如果你发现任务经常因为超过 60 秒而超时，单纯把 timeout 无休止地调大（比如设为 300 秒）并不是好办法，因为这会导致连接长时间被占用。更优雅的解法有两种：

方案 1：开启流式输出（Streaming）

流式输出（stream=True）的精髓在于**“只要首字返回了，连接就不会因为中间生成慢而整体超时”**。
虽然流式传输的整体时间可能也很长，但由于数据在持续不断地传输（有数据包交互），TCP 连接不会被中间代理或客户端断开。

stream = client.chat.completions.create(
    model="your-model-name",
    messages=[{"role": "user", "content": "写一本小说..."}],
    stream=True,
    timeout=15.0  # 这里的 timeout 通常指“建立连接和接收第一个分片”的超时
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

方案 2：将长任务拆分为多个短任务（Task Decomposition）

如果让模型“一次性写完一整本书”，不仅容易超时，而且生成质量会迅速劣化。
更好的做法是编写 Python 脚本将任务拆分：

1. 先让模型生成大纲。
2. 循环遍历大纲中的每一章，分别发送请求让模型生成单章内容。
3. 最后在本地把所有章节拼接起来。

这样每次请求的字数和耗时都处于安全范围内，完全不需要调大超时时间。

---

四、生产环境中的超时配置建议

根据不同的业务场景，建议设置差异化的超时策略：

业务场景	推荐超时时间 (timeout)	核心考量
文本分类 / 意图识别	3秒 - 5秒	要求极快反馈，宁可失败也不要让用户干等
日常对话 / 问答	10秒 - 20秒	兼顾生成质量与用户等待耐受度
长文本分析 / 代码生成	30秒 - 60秒	允许较长的生成时间，但必须配合流式传输
健康检查（Health Check）	2秒 - 3秒	用于快速探测上游接口是否存活

---

五、结语

在开发 AI 应用时，超时控制是一把双刃剑：

• 设置得太短，正常生成会被无情掐断。
• 设置得太长，系统会在遇到死锁或严重拥堵时被大量卡住的线程拖垮。

通过合理设置单次请求超时、善用流式输出以及将长任务拆分为多步执行，你可以让你的 Python 程序在面对各种耗时场景时游刃有余。

免责声明

本文内容仅用于技术交流与经验分享，具体实现请结合项目实际网络环境和模型响应速度进行调整。