qihuaiflow/docs/observability/litellm-failover-activation.md

LiteLLM 副 key 启用计划 (Task #937)

必要性判断

• 必要性: 🟡 中等(非紧急,设计已就绪)
• 理由: #937 failover 设计 + 沙箱已交付(commit 84d89ab),test_litellm_failover_sandbox.py 在沙箱跑通。但实际启用需要用户提供副 key。
• 冲突: 修改 litellm config + kill -HUP 1 会触发 litellm reload,可能瞬时影响 LLM 调用。

当前状态(本会话交付)

• 代码就绪:app/core/llm_router.py + test_llm_router.py 已支持熔断 + 路由
• 沙箱验证:tests/test_litellm_failover_sandbox.py dry-run 通过
• 运维脚本:litellm/apply_secondary_key.sh + rollback_secondary_key.sh + verify_failover.sh + README

启用流程(等用户提供副 key)

1. 用户:向 SiliconFlow 申请副 key(用户责任,无法自动化)
2. 在低峰期执行 SECONDARY_API_KEY=sk-xxx ./apply_secondary_key.sh --gray=10
3. 观察 24h 一致率
4. 切到 100%:./apply_secondary_key.sh --gray=100
5. 验证:./verify_failover.sh

不启用的代价

• 当前可用: 主 key 正常,实测 1-4% CPU 误判已修
• 风险: 主 key 限流时整个 LLM 服务中断
• 概率: 低(SiliconFlow 个人账户默认 1k req/min,平台日均 200 req)

总结

• 现在做:运维脚本 + 文档(本会话已交付,commit 下一行)
• 不实际启用:等用户提供副 key
• 执行时机:用户给副 key 后,单次低峰期会话完成切换