HappyHorse 1.0 正式上线立即体验
AI API 超时:原因、重试模式与回退设计
guide

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

EvoLink Team
EvoLink Team
Product Team
2026年5月13日
13 分钟阅读

你的 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提交任务 → 完成时提供商调用你的端点高吞吐管道、事件驱动架构
对于视频生成,永远不要使用同步等待。大多数视频模型需要 60–300+ 秒。你的 HTTP 客户端几乎肯定会超时。

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
        )

使用路由网关实现超时弹性

与其在每个服务中实现回退逻辑,路由网关可以在基础设施层面处理超时:

  • 当主路由慢时路由到更快的提供商
  • 自动在不同的上游路径上重试
  • 返回实际使用的模型,让你的应用知道发生了什么
EvoLink 的 Smart Router 通过 OpenAI 兼容接口在网关层面提供这些功能:
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秒在用户失去耐心前切换到更快的模型

相关文章

探索 EvoLink Smart Router

常见问题

为什么我的 AI API 请求超时,即使模型可以正常工作?

超时通常由以下原因之一引起:(1) 大输入需要更长处理时间,(2) 提供商负载过重,(3) 客户端超时配置太短,或 (4) 网络问题。模型本身可能没问题。

应该增加超时还是使用不同的方案?

取决于情况。对于文本模型,增加超时有助于处理偶尔的慢响应。对于视频/图像生成,应切换到异步轮询而非增加同步超时。对于持续性超时,在增加限制之前先调查根本原因。

超时和速率限制错误一样吗?

不一样。超时意味着服务器在你的时间限制内没有响应。速率限制(429)意味着服务器主动拒绝了你的请求。超时通常表示处理慢;429 表示请求太多。

如何处理视频生成的超时?

永远不要同步等待视频生成。使用异步任务提交配合轮询或 webhooks。如果视频任务在轮询期间超时,在重新提交之前检查状态——任务可能仍在处理中。

流式传输能防止超时吗?

流式传输能防止客户端超时,因为第一个 token 很快到达,保持连接活跃。但流式传输不会让总生成更快——它只是改变了交付模式。

什么时候应该在超时时切换到回退模型?

设置一个阈值(如文本 15–30 秒),当主模型超时时切换到更快的模型。这给用户一个响应而非错误。回退模型可能能力稍弱,但一个略差的答案总好过没有答案。

准备好把 AI 成本降低 89% 吗?

现在就开始使用 EvoLink,体验智能 API 路由的强大能力。