失败重试与降级策略

⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准 更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补

背景

免费模型的稳定性天然低于付费:OpenRouter 免费模型经常 429、Groq 高峰时排队 5xx、Hugging Face 冷启动 30s。如果客户端直接裸调,每个调用点都要自己实现重试与降级,代码重复且容易写错。把这些策略集中到网关,客户端只关心业务结果。

核心策略

• 错误分类:网关把上游错误分成四类——retryable(429、503、timeout)、non-retryable(400、401)、degradable(模型不支持工具)、fatal(5xx 持续)。每类有不同处理路径。
• 指数退避 + 抖动:重试间隔 base * 2^attempt + random(0, 1),避免同步重试打爆上游。基础 200ms,最多 4 次,总时长不超过 8s。
• 跨 Provider 降级:同模型在多家 Provider 都有副本(如 llama-3.3-70b 在 Groq 与 OpenRouter 都有)。第一次失败直接换 Provider,不要在同一 Provider 上死磕。
• 熔断器:同一 Provider 5 分钟内失败率 >50% 自动熔断 60s,期间流量绕过它。
• 降级链:用户请求 gpt-4o → 免费等价物 deepseek-chat:free → 更便宜的 llama-3.1-8b:free → 拒绝。每跳都记录在响应 header 里,客户端可观测。

代码示例

import asyncio, random, time

async def call_with_fallback(call_fn, providers, max_attempts=4):
    for attempt in range(max_attempts):
        provider = providers[attempt % len(providers)]
        try:
            return await call_fn(provider)
        except (TimeoutError, RateLimitError) as e:
            # exponential backoff + jitter
            delay = 0.2 * (2 ** attempt) + random.random()
            await asyncio.sleep(delay)
        except (InternalError, ServiceUnavailable):
            # immediately switch provider, no retry on same one
            continue
    # all attempts failed: degrade to cheaper model or raise
    raise FallbackExhausted("tried: " + ",".join(providers))

部分重试语义

对于非流式的"多轮 tool 调用"场景,重试语义复杂:第一轮调用成功调了 tool,第二轮失败。如果整体重试,会触发 tool 的副作用两次。正确做法是幂等性 token:客户端为整条会话生成唯一 ID,网关在重试时把"已成功调用的 tool_call_id"作为透传头给上游,让上游跳过已执行的部分。没有幂等性 token 的 tool 调用,只允许 retry 在第一轮,后续失败必须整条失败。

最佳实践

• 重试要幂等:重试只对幂等请求(纯生成)安全;带 tool_calls 副作用的重试要更保守。
• 绝不重试流式:流式响应一旦开始吐 token 就不能再重试,首 chunk 之前失败才允许重试。
• 预算上限:为重试设最大消耗 token 数,避免一次失败连环触发 4 次重试把额度翻倍烧掉。
• 可观测:每次降级都打 metrics 标签 fallback_chain,运维能看出哪条链路最常触发。
• 断路器隔离:每家 Provider 独立断路器,避免一家连累另一家。

免费模型不是"能不能用"的问题,是"出问题时谁来兜"的问题,答案永远是网关。

🚀 立即开始：免费 API 一键调用

想要无需逐一注册、统一鉴权调用以上全部免费模型？Apishare.cc 提供统一 API Key，一个 Key 调用 100+ 模型，免费模型零成本直连。

👉 立即注册 Apishare.cc → 获取你的统一 API Key

📊 想看更多免费模型排行？查看 2026年9月 免费 LLM API 综合实力榜单 →

立即上手：APIShare 免费 API 目录

• 🆓 注册领取免费额度：立即注册 APIShare · 登录控制台
• 🔍 浏览全部免费 API 与实时榜单：APIShare 免费 API 目录
• 📊 查看免费 LLM API 排行：Free LLM API Rankings

免费 API 聚合平台说明

本文涉及的模型均由 APIShare 免费 API 聚合平台 统一接入，一份 Key 调用全站模型。

• 完整模型目录：APIShare 免费 API 目录
• 注册即送免费额度：注册领取 API Key