
AI API 超时:原因、重试模式与回退设计

你的 AI API 请求超时了。但"超时"不是一个问题——它至少是四种不同的问题,穿着相同的错误消息外衣。
文本模型在 30 秒后超时和视频生成任务在 5 分钟后超时是完全不同的问题。修复错误的类型会浪费工程时间,甚至可能使问题恶化。
本指南帮助你诊断你面对的是哪种类型的超时,并选择正确的应对模式。
要点速览
- AI API 超时有不同的根本原因:模型延迟、提供商队列、大输入或网络问题。
- 文本模型超时和视频/图像生成超时需要不同的处理策略。
- 不要盲目重试——有些超时意味着请求仍在处理中。
- 对于长时间运行的任务(视频、图像),使用异步模式而非等待同步响应。
- 提前设计回退:更短的超时 + 回退模型通常优于更长的超时 + 无回退。
超时诊断表
在选择修复方案之前,使用此表确定你的超时类型:
| 超时类型 | 典型持续时间 | 根本原因 | 如何验证 | 正确应对 |
|---|---|---|---|---|
| 文本模型 — 响应慢 | 15–60秒 | 大输入、复杂推理或高输出 token | 检查输入大小和 max_tokens | 减少输入、降低 max_tokens 或切换到更快的模型 |
| 文本模型 — 提供商过载 | 30–120秒 | 提供商负载重;请求排队 | 在非高峰时段尝试相同请求 | 带退避重试,或路由到不同的提供商 |
| 视频/图像生成 — 正常处理 | 60–300秒+ | 生成本身就需要时间(尤其是视频) | 查看提供商文档了解预期生成时间 | 使用异步轮询,而非同步等待 |
| 视频/图像生成 — 队列积压 | 300秒+ | 提供商队列中有太多任务排在前面 | 查看提供商队列状态或位置 | 添加队列管理,设定用户预期,或使用不同的提供商 |
| 网络超时 | 不定 | DNS、防火墙、代理或连接问题 | 用简单的健康检查请求测试 | 修复网络配置,而非 API 调用 |
| 客户端超时设置太短 | 固定 | HTTP 客户端超时比模型需要的时间短 | 增加超时设置并重新测试 | 增加客户端超时以匹配预期响应时间 |
模式 1:处理文本模型超时
文本模型超时通常由以下三种原因之一引起:
1.1 大输入或高 max_tokens
max_tokens 设置允许更长的生成,也需要更多时间。# 问题:大输入 + 高 max_tokens = 响应慢
response = client.chat.completions.create(
model="gpt-4o",
messages=very_long_messages, # 100K+ token
max_tokens=4096 # 请求长输出
)
# 修复:减少输入或限制输出
response = client.chat.completions.create(
model="gpt-4o",
messages=trimmed_messages, # 减少到 50K token
max_tokens=1024 # 更短的输出
)1.2 提供商负载过重
在使用高峰期,提供商可能会将你的请求排队。这表现为超时而非明确的排队消息。
- 同一请求在非高峰时段正常工作
- 错误是间歇性的,非持续性
- 其他用户同时报告类似问题
- 带抖动退避重试
- 路由到替代提供商或模型
- 使用流式传输更快获取部分结果
1.3 流式传输作为超时缓解措施
流式传输不会让生成更快,但它更早开始返回 token。这可以防止客户端超时触发:
# 同步 — 客户端可能在等待完整响应时超时
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
max_tokens=2048
)
# 流式 — 第一个 token 更快到达,保持连接活跃
stream = client.chat.completions.create(
model="gpt-4o",
messages=messages,
max_tokens=2048,
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")模式 2:处理视频/图像生成超时
视频和图像生成与文本根本不同。30 秒到几分钟的生成时间是正常的,不是错误。
2.1 同步 vs 异步生成
| 方式 | 工作原理 | 何时使用 |
|---|---|---|
| 同步 | 在一次 HTTP 调用中等待完整响应 | 快速生成(< 30秒)、简单集成 |
| 异步轮询 | 提交任务 → 获取任务 ID → 轮询状态 → 获取结果 | 视频生成、批处理、任何 > 30秒的任务 |
| Webhooks | 提交任务 → 完成时提供商调用你的端点 | 高吞吐管道、事件驱动架构 |
2.2 异步轮询模式
import asyncio
import httpx
async def generate_video_async(client, prompt: str, timeout: int = 600):
"""提交视频生成任务并轮询完成状态。"""
# 第 1 步:提交任务
submit_response = await client.post(
"/v1/video/generations",
json={"model": "veo-3-fast", "prompt": prompt}
)
job_id = submit_response.json()["id"]
# 第 2 步:轮询完成状态
for _ in range(timeout // 5): # 每 5 秒检查一次
status_response = await client.get(f"/v1/video/generations/{job_id}")
status = status_response.json()
if status["status"] == "completed":
return status["result"]
elif status["status"] == "failed":
raise RuntimeError(f"生成失败: {status.get('error')}")
await asyncio.sleep(5)
raise TimeoutError(f"视频生成未在 {timeout} 秒内完成")模式 3:针对超时的智能重试逻辑
不是所有超时都应该以相同方式重试:
不同超时类型的重试规则
| 超时类型 | 应该重试吗? | 怎么做 |
|---|---|---|
| 文本模型慢 | 是 | 带退避重试;重试时考虑使用更快的模型 |
| 提供商过载 | 谨慎地是 | 更长退避重试;考虑不同的提供商 |
| 视频生成仍在处理 | 否 — 任务可能仍在运行 | 轮询状态而非重新提交 |
| 网络超时 | 是 | 先修复网络;确认连接后再重试 |
| 客户端超时太短 | 否 — 应增加超时 | 调整配置,不要重试 |
最危险的错误是重试一个仍在处理中的视频生成任务。这会创建重复任务、浪费金钱,并可能使提供商队列过载。
模式 4:生产环境的回退设计
超时触发的模型回退
async def call_with_fallback(messages, client, primary_model, fallback_model):
"""尝试主模型;超时后回退到更快的模型。"""
try:
return await asyncio.wait_for(
client.chat.completions.create(
model=primary_model,
messages=messages
),
timeout=30.0
)
except asyncio.TimeoutError:
# 回退到更快、可能更小的模型
return await client.chat.completions.create(
model=fallback_model,
messages=messages
)使用路由网关实现超时弹性
与其在每个服务中实现回退逻辑,路由网关可以在基础设施层面处理超时:
- 当主路由慢时路由到更快的提供商
- 自动在不同的上游路径上重试
- 返回实际使用的模型,让你的应用知道发生了什么
from openai import OpenAI
client = OpenAI(
api_key="your-evolink-key",
base_url="https://api.evolink.ai/v1"
)
# Smart Router 处理提供商选择和回退
response = client.chat.completions.create(
model="evolink/auto",
messages=messages
)超时配置参考
| 设置 | 推荐值 | 原因 |
|---|---|---|
| HTTP 客户端超时(文本) | 60–120秒 | 允许大输入和复杂推理 |
| HTTP 客户端超时(图像) | 120–300秒 | 图像生成因模型和分辨率而异 |
| HTTP 客户端超时(视频) | 使用异步轮询 | 同步超时不适合视频 |
| 重试次数 | 文本 2–3 次,处理中的视频 0 次 | 避免重复的视频/图像任务 |
| 退避基础延迟 | 2秒 + 抖动 | 防止提供商恢复时的惊群效应 |
| 回退模型切换超时 | 15–30秒 | 在用户失去耐心前切换到更快的模型 |
相关文章
- 修复 OpenRouter 429 "Provider Returned Error" — 当错误是速率限制而非超时时
- LLM API 调用中的 Context Length Exceeded 错误 — 当大输入导致拒绝而非超时时
- 如何减少 Agent 工作负载中的 429 错误 — 管理导致超时的突发流量
- 2026年最佳生产可靠性AI API平台 — 选择内置故障转移的平台
常见问题
为什么我的 AI API 请求超时,即使模型可以正常工作?
超时通常由以下原因之一引起:(1) 大输入需要更长处理时间,(2) 提供商负载过重,(3) 客户端超时配置太短,或 (4) 网络问题。模型本身可能没问题。
应该增加超时还是使用不同的方案?
取决于情况。对于文本模型,增加超时有助于处理偶尔的慢响应。对于视频/图像生成,应切换到异步轮询而非增加同步超时。对于持续性超时,在增加限制之前先调查根本原因。
超时和速率限制错误一样吗?
不一样。超时意味着服务器在你的时间限制内没有响应。速率限制(429)意味着服务器主动拒绝了你的请求。超时通常表示处理慢;429 表示请求太多。
如何处理视频生成的超时?
永远不要同步等待视频生成。使用异步任务提交配合轮询或 webhooks。如果视频任务在轮询期间超时,在重新提交之前检查状态——任务可能仍在处理中。
流式传输能防止超时吗?
流式传输能防止客户端超时,因为第一个 token 很快到达,保持连接活跃。但流式传输不会让总生成更快——它只是改变了交付模式。
什么时候应该在超时时切换到回退模型?
设置一个阈值(如文本 15–30 秒),当主模型超时时切换到更快的模型。这给用户一个响应而非错误。回退模型可能能力稍弱,但一个略差的答案总好过没有答案。

