LiteLLM 怎样给不同 API Key 配置独立 fallback

如果不同调用方需要不同的容灾策略，LiteLLM 不必把所有 fallback 写成一套全局规则。Proxy 会按 Key > Team > Global 解析 router settings：给某个 API Key 配置了 router settings，就优先使用这份设置；没有 Key 级设置时才看它所属 Team，二者都没有才回到全局配置。

官方文档：https://docs.litellm.ai/docs/proxy/keys_teams_router_settings

因此，生产 Key 可以使用较短的 timeout 和备用模型链，开发 Key 可以保留更宽松的重试；关键是不要把“重试一次”“换模型”和“把故障部署暂时冷却”混成一个参数。

先确定每个 Key 的生效层级

先把配置对象分成三层。Key 级设置只影响使用该 Key 的请求；Team 级设置可作为团队内多个 Key 的共同默认值；Global 级设置则是没有更具体配置时的最后兜底。Key 一旦存在自己的 router settings，就不会再叠加 Team 的同名策略。

实操时先问一个问题：这个策略是“只给一把 Key”，还是“给一组 Key”。前者放在 Key 的 Router Settings，后者放在 Team；不要为了让一把 Key 覆盖团队规则而修改全局配置。

在 Key 的 Router Settings 中配置 fallback 链

在 LiteLLM 管理界面编辑目标 Key，依次进入 Optional Settings → Router Settings，然后在 Fallbacks 中选择主模型组和备用模型组。官方文档给出的 Team 配置入口相同，只是从 Teams 进入；这让同一套思路可以先在单个 Key 上小范围使用，再推广到团队。

假设主模型组叫 primary-chat，备用模型组叫 backup-chat 和 backup-chat-lite，配置意图可以写成下面这样。代码中的模型名只是示例，必须替换成你自己的 model_list 名称。

# 这是一份 router_settings 结构示意，模型组名要对应现有 model_list
router_settings:
  # 先尝试 primary-chat，失败后按列表顺序切换
  fallbacks:
    - primary-chat: ["backup-chat", "backup-chat-lite"]
  # 只控制这一把 Key 的路由行为，不改其他 Key
  num_retries: 1
  # 约束一次路由调用允许等待的最长时间
  timeout: 20
  # 连续失败达到阈值后，暂时让该部署进入冷却
  allowed_fails: 3
  cooldown_time: 30

上面的配置表达了三件事：同一个模型组内的重试由 num_retries 控制；跨到另一个模型组由 fallbacks 控制；allowed_fails 与 cooldown_time 负责把持续失败的部署暂时移出可选范围。fallback 链按顺序处理，不能只写备用模型而忘记把它加入当前 Key、Team 或项目允许访问的模型范围。

组合 timeout、num_retries、allowed_fails 与 cooldown_time

这四个参数最好按故障处理阶段来理解。timeout 先限制一次调用不能无限等待；num_retries 决定 LiteLLM 在当前模型组内还要不要重试；当前组仍然失败时，才进入 fallbacks 的下一个模型组。allowed_fails 和 cooldown_time 不等于一次请求的重试次数，它们处理的是部署健康状态。

• timeout：给单次路由调用设上限，避免一个慢上游长期占住请求。
• num_retries：控制 LiteLLM 自己的重试循环；它和供应商 SDK 的 max_retries 不是同一个旋钮。
• fallbacks：从当前模型组切换到另一个模型组，列表顺序就是故障后的候选顺序。
• allowed_fails / cooldown_time：连续失败达到阈值后暂时冷却部署，减少请求继续撞向已知异常的实例。

生产 Key 通常应该先收紧 timeout，再谨慎设置重试次数；如果主模型和备用模型都消耗同一类昂贵资源，盲目增加 retry 只会放大请求量。若备用模型受 Key 的模型权限或预算限制，LiteLLM 会跳过没有权限或超出预算的 fallback，最后仍可能返回主模型错误。

用非生产故障演练排查 fallback 没生效

排查顺序建议固定下来，避免看到一次 5xx 就直接改全局配置。

1. 确认生效层级：检查这把 Key 是否已经保存了 router settings。只要 Key 级设置存在，Team 的同名设置就不是本次请求的首选。
2. 确认模型权限：主模型能调用不代表备用模型也能调用。给 Key、所属 Team 和项目都授予备用模型访问权，否则 fallback 会被权限检查跳过。
3. 区分重试和 fallback：同一模型组内的再次尝试属于 retry，切换到另一个模型组才是 fallback。把 num_retries 调大，不会替代缺失的 fallback 链。
4. 在非生产环境制造可控故障：让主模型返回可重试的限流或服务错误，再发送普通请求，观察是否落到备用模型；不要用真实生产流量做故障演练。
5. 记录最终模型：结合 LiteLLM 的请求日志和 fallback 相关元数据，确认请求的原始模型组、尝试次数以及最终服务模型，而不是只看客户端收到 200。

还有一个常见误区是把“关闭 fallback”只理解为全局开关。LiteLLM 也支持在请求或 Key 元数据中设置 disable_fallbacks: true；如果某把 Key 带着这个设置，即使路由器里配置了 fallback，也可能按该 Key 的意图直接返回主模型错误。

常见问题

Key 级和 Team 级 router_settings 会合并吗？

按官方文档的层级解析规则，Key、Team、Global 是优先级关系，不应把它们当作会自动拼接的三份配置。需要独立策略时，把完整的 Key 级设置写清楚。

为什么设置了 fallback 仍然返回主模型错误？

优先检查备用模型是否在当前 Key 的可访问范围内，再检查请求是否携带 disable_fallbacks，最后确认主模型的错误类型是否属于当前 fallback 路径处理的范围。