在调用 AI 接口或开发自动化工具时，遇到 APITimeoutError（请求超时）是家常便饭。如果超时时间设置得不合理，轻则导致程序无限卡死，重则让批量任务大面积报错。本文介绍如何在 Python 中正确管理 API 超时，并处理好长任务。
为什么 AI 请求经常需要更长的超时？
普通的 HTTP 接口（比如查询用户资料、修改状态）通常在毫秒级就能响应。但 AI 模型不同：
- 模型的生成速度受到字数限制（tokens per second）。
- 如果用户要求模型写一篇长文章、分析大段代码或者执行复杂的 Agent 推理，服务端可能需要十几秒甚至几十秒才能完整返回。
如果直接使用默认或过短的超时时间，程序就会频繁报错；而如果把超时时间设得无限长，一旦上游服务卡死，你的客户端也会跟着无限挂起。
因此，合理的超时管理是保证 Python AI 脚本稳定运行的重要一环。
一、在 OpenAI 客户端中设置超时
在使用 OpenAI 官方 Python SDK（或兼容客户端）时，超时参数可以分为两类：全局客户端级别 和 单次请求级别。
1. 全局初始化时设置超时
在实例化客户端时，直接传入 timeout 参数（单位为秒）：
from openai import OpenAIclient = 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, APIConnectionErrorclient = 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 脚本将任务拆分：
- 循环遍历大纲中的每一章，分别发送请求让模型生成单章内容。
这样每次请求的字数和耗时都处于安全范围内，完全不需要调大超时时间。
四、生产环境中的超时配置建议
根据不同的业务场景，建议设置差异化的超时策略：
| | |
|---|
| 文本分类 / 意图识别 | | |
| 日常对话 / 问答 | | |
| 长文本分析 / 代码生成 | | |
| 健康检查（Health Check） | | |
五、结语
在开发 AI 应用时，超时控制是一把双刃剑：
- 设置得太长，系统会在遇到死锁或严重拥堵时被大量卡住的线程拖垮。
通过合理设置单次请求超时、善用流式输出以及将长任务拆分为多步执行，你可以让你的 Python 程序在面对各种耗时场景时游刃有余。
免责声明
本文内容仅用于技术交流与经验分享，具体实现请结合项目实际网络环境和模型响应速度进行调整。
10个月宝宝每天需要喝多少奶粉？
