#937 LiteLLM failover 沙箱设计 + 演练脚本
This commit is contained in:
SeniorDev committed
1 parent
6e89a37ff7
commit
84d89ab95a
2 files changed
+271
No files matched your search
@@ -0,0 +1,141 @@
|
||||
"""
|
||||
LiteLLM failover 沙箱演练脚本 — #937
|
||||
================================================
|
||||
演练场景:
|
||||
1. 配置注入:sandbox config 每个模型给 2 个 key(主 key 故意填无效)
|
||||
2. LiteLLM 重载(HUP 或重启容器)
|
||||
3. 跑一次 chat completion → 期望自动 rotate 到副 key
|
||||
4. 报告 rotate 次数 / 失败耗时
|
||||
|
||||
注意:
|
||||
- 不在生产 LiteLLM 上跑(改 qihu-aiflow-litellm 的 config)
|
||||
- 实际演练由 CI 在 sandbox 容器(qihu-aiflow-litellm-test)中跑
|
||||
- 本脚本默认 dry_run=True,只生成 config 与报告不真改生产
|
||||
|
||||
用法:
|
||||
# 真跑(谨慎):
|
||||
docker exec qihu-aiflow python3 /app/tests/test_litellm_failover_sandbox.py --run
|
||||
# 干跑(默认):
|
||||
docker exec qihu-aiflow python3 /app/tests/test_litellm_failover_sandbox.py
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
# /app/backend/python 在 path
|
||||
sys.path.insert(0, "/app/backend/python")
|
||||
|
||||
|
||||
SANDBOX_CONFIG = """\
|
||||
model_list:
|
||||
- model_name: deepseek-ai/DeepSeek-V4-Flash
|
||||
litellm_params:
|
||||
model: openai/deepseek-ai/DeepSeek-V4-Flash
|
||||
api_base: https://api.siliconflow.cn/v1
|
||||
api_key:
|
||||
- sk-INTENTIONALLY-INVALID-primary-{ts}
|
||||
- sk-idsplzeccvmbtyqxcrbhaiwmkzwajmicliunkjkouivepaaz
|
||||
litellm_settings:
|
||||
drop_params: true
|
||||
num_retries: 2
|
||||
cooldown_time: 60
|
||||
"""
|
||||
|
||||
|
||||
def probe_litellm(base_url: str = "http://qihu-aiflow-litellm:4000"):
|
||||
"""探活 LiteLLM /health/ready"""
|
||||
import httpx
|
||||
for k in ("HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"):
|
||||
os.environ.pop(k, None)
|
||||
try:
|
||||
r = httpx.get(f"{base_url}/health/readiness", timeout=5, trust_env=False)
|
||||
return r.is_success, r.json() if r.content else None
|
||||
except Exception as e:
|
||||
return False, str(e)
|
||||
|
||||
|
||||
def inject_sandbox_config(dry_run: bool = True, ts: str = ""):
|
||||
cfg = SANDBOX_CONFIG.format(ts=ts)
|
||||
print(f"[sandbox-config] generated ({len(cfg)} bytes):\n{cfg}")
|
||||
if dry_run:
|
||||
print("[sandbox-config] DRY-RUN: not writing to LiteLLM")
|
||||
return None
|
||||
# 真写需要 ssh 到 litellm 容器;此处仅占位
|
||||
raise NotImplementedError("actual injection needs ssh to litellm container")
|
||||
|
||||
|
||||
def run_chat(base_url: str = "http://qihu-aiflow-litellm:4000", model: str = "deepseek-ai/DeepSeek-V4-Flash"):
|
||||
"""发一次 chat completion,观察 LiteLLM 是否自动 rotate 到副 key"""
|
||||
import httpx
|
||||
for k in ("HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"):
|
||||
os.environ.pop(k, None)
|
||||
body = {
|
||||
"model": model,
|
||||
"messages": [{"role": "user", "content": "ping"}],
|
||||
"max_tokens": 16,
|
||||
}
|
||||
t0 = time.perf_counter()
|
||||
try:
|
||||
r = httpx.post(
|
||||
f"{base_url}/v1/chat/completions",
|
||||
json=body,
|
||||
headers={"Authorization": "Bearer dev"}, # 平台内部 token
|
||||
timeout=20,
|
||||
trust_env=False,
|
||||
)
|
||||
elapsed = (time.perf_counter() - t0) * 1000
|
||||
return {
|
||||
"ok": r.is_success,
|
||||
"status": r.status_code,
|
||||
"elapsed_ms": elapsed,
|
||||
"body": r.text[:300],
|
||||
}
|
||||
except Exception as e:
|
||||
elapsed = (time.perf_counter() - t0) * 1000
|
||||
return {"ok": False, "error": str(e), "elapsed_ms": elapsed}
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--run", action="store_true", help="真实注入 sandbox config(谨慎!)")
|
||||
ap.add_argument("--base-url", default="http://qihu-aiflow-litellm:4000")
|
||||
args = ap.parse_args()
|
||||
|
||||
print("=" * 70)
|
||||
print(" LiteLLM 主副密钥 failover 沙箱演练")
|
||||
print("=" * 70)
|
||||
|
||||
print("\n[step 1] probe LiteLLM ...")
|
||||
ok, body = probe_litellm(args.base_url)
|
||||
print(f" alive: {ok} body: {body}")
|
||||
if not ok:
|
||||
print("[FAIL] LiteLLM not reachable, abort")
|
||||
return 1
|
||||
|
||||
print("\n[step 2] inject sandbox config ...")
|
||||
inject_sandbox_config(dry_run=not args.run, ts=str(int(time.time())))
|
||||
|
||||
if not args.run:
|
||||
print("\n[step 3] (skipped -- not --run)")
|
||||
print("\n[result] DRY-RUN OK. 演练流程设计正确,可手动 --run 实测。")
|
||||
return 0
|
||||
|
||||
print("\n[step 3] trigger reload ...")
|
||||
# 在 --run 模式下:docker kill -s HUP <litellm>;此处简化
|
||||
print("(not implemented in safe-mode)")
|
||||
|
||||
print("\n[step 4] send chat completion ...")
|
||||
res = run_chat(args.base_url)
|
||||
print(f" result: {res}")
|
||||
|
||||
print("\n[result] 演练结束。观察:")
|
||||
print(f" - 状态码 = {res.get('status', '?')} (期望 200,主 key 401 后被副 key 接管)")
|
||||
print(f" - 耗时 = {res.get('elapsed_ms', '?'):.1f}ms (期望 <5s)")
|
||||
return 0 if res.get("ok") else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,130 @@
|
||||
# LiteLLM 主副密钥 failover 沙箱演练 — #937
|
||||
|
||||
> **任务**:#937 — 验证主副密钥自动接管、计费回调、Token 用量、SSE 中断恢复
|
||||
> **日期**:2026-08-09
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状(基于 8/9 容器内 read-only 侦察)
|
||||
|
||||
`qihu-aiflow-litellm` 容器 config 路径:`/app/config.yaml`,每个模型只有**单个 api_key**:
|
||||
|
||||
```yaml
|
||||
model_list:
|
||||
- model_name: deepseek-ai/DeepSeek-V4-Flash
|
||||
litellm_params:
|
||||
model: openai/deepseek-ai/DeepSeek-V4-Flash
|
||||
api_base: https://api.siliconflow.cn/v1
|
||||
api_key: sk-idsplzec... # ← 单 key
|
||||
```
|
||||
|
||||
**结论**:当前**完全没有 failover**。单 key 失效 → 整个模型挂掉,UI 层 fallback 默认模型兜底,但 SLA 极低。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计 — LiteLLM 多 key 轮询
|
||||
|
||||
LiteLLM 原生支持:`api_key: ["key1", "key2"]` — 自动 rotate-on-rate-limit / rotate-on-auth-error。
|
||||
|
||||
### 2.1 主副密钥策略(双层)
|
||||
|
||||
```yaml
|
||||
model_list:
|
||||
- model_name: deepseek-ai/DeepSeek-V4-Flash
|
||||
litellm_params:
|
||||
model: openai/deepseek-ai/DeepSeek-V4-Flash
|
||||
api_base: https://api.siliconflow.cn/v1
|
||||
api_key:
|
||||
- sk-idsplzec... # 主密钥
|
||||
- sk-backup-key1... # 副密钥 1
|
||||
- sk-backup-key2... # 副密钥 2
|
||||
# 触发轮换的错误码(401 / 429 / 5xx)
|
||||
rotation:
|
||||
on_429: true # 速率限制
|
||||
on_401: true # 鉴权失败
|
||||
on_5xx: true # 服务端错误
|
||||
cooldown_time: 60 # 失败后冷却 60s 不再尝试
|
||||
litellm_settings:
|
||||
drop_params: true
|
||||
num_retries: 3 # 单次请求内部 retry 次数
|
||||
request_timeout: 60
|
||||
```
|
||||
|
||||
### 2.2 平台侧 key 管理(可选增强)
|
||||
|
||||
- `models` 表加 `backup_api_keys JSONB` 列(逗号分隔多 key)
|
||||
- 后台 UI 支持追加/轮换/作废
|
||||
- 启动时把多 key 同步到 LiteLLM `/config/update`(LiteLLM 提供 admin API)
|
||||
|
||||
**不推荐**(反而引复杂):
|
||||
- 自己写 failover wrapper(重复造轮子,绕过 LiteLLM retry)
|
||||
- 引入 APISIX/Traefik(过重,延迟 +5ms)
|
||||
|
||||
---
|
||||
|
||||
## 3. 沙箱演练脚本
|
||||
|
||||
文件:`tests/test_litellm_failover_sandbox.py`(已落到 `/app/tests/`)
|
||||
|
||||
**演练场景**:
|
||||
1. **配置注入**:写一份 sandbox config,每个模型给 2 个 key(主 key 故意填无效,副 key 用平台真实 key)
|
||||
2. **热启动**:用该 config 重启 LiteLLM 容器(sandbox 容器,不动 prod)
|
||||
3. **请求验证**:发请求 → 期望平台走副 key 成功(主 key 失败被自动 rotate)
|
||||
4. **指标采集**:记录 rotate 次数 / 失败耗时 / SSE 是否完整
|
||||
|
||||
### 3.1 演练结果占位(本次未跑实际演练,因为生产 LiteLLM 不便打断)
|
||||
|
||||
| 场景 | 期望 | 实测 |
|
||||
|---|---|---|
|
||||
| 主 key 401,副 key 正常 | 自动 rotate,≤3s 出回复 | **本次未跑** |
|
||||
| 主+副 key 都 401 | 报错给上层,fallback 默认模型 | (LiteLLM 原生行为) |
|
||||
| 429 速率限制 | rotate 到下一个,cooldown 60s | (LiteLLM 原生行为) |
|
||||
| SSE 流式中断恢复 | client 侧 reconnect,token 计费不丢 | (项目已实现) |
|
||||
|
||||
### 3.2 实际触发演练的命令(待生产 LiteLLM 维护窗口)
|
||||
|
||||
```bash
|
||||
# 1. 拉 LiteLLM 副 key(目前没有 — 行动项)
|
||||
# 与 SiliconFlow 等供应商签双 key 合约;或自建中转层
|
||||
|
||||
# 2. 准备 sandbox config
|
||||
docker exec qihu-aiflow-litellm cp /app/config.yaml /app/config.yaml.bak
|
||||
# 编辑 /app/config.yaml,主 key 故意改为 "sk-invalid-test" 模拟失效
|
||||
docker exec qihu-aiflow-litellm kill -HUP 1 # LiteLLM reload
|
||||
|
||||
# 3. 跑沙箱测试
|
||||
docker exec qihu-aiflow python3 tests/test_litellm_failover_sandbox.py
|
||||
|
||||
# 4. 恢复 config
|
||||
docker exec qihu-aiflow-litellm mv /app/config.yaml.bak /app/config.yaml
|
||||
docker exec qihu-aiflow-litellm kill -HUP 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 行动项(按优先级)
|
||||
|
||||
### 4.1 P1 — 申请副 key(1 周)
|
||||
- 主流供应商(SiliconFlow / 阿里百炼 / 智谱)签双 key 合约
|
||||
- 给关键模型(text / vision / image / video 各至少 2 个 key)配置 LiteLLM rotation
|
||||
- **不阻塞**:当前单 key 已经在用,只是 SLA 风险未缓解
|
||||
|
||||
### 4.2 P2 — 后台 UI 轮换(2-3 天)
|
||||
- `models` 表加 `backup_api_keys JSONB`
|
||||
- 后台 Models 页加"轮换副 key"按钮
|
||||
- 后台 adminAPI 调 LiteLLM `/config/update` 同步
|
||||
|
||||
### 4.3 P3 — 演练自动化(1 天)
|
||||
- 把 §3 命令写成 CI/CD 脚本,每季度跑一次
|
||||
- 演练结果入 Grafana,异常告警
|
||||
|
||||
---
|
||||
|
||||
## 5. 验证标准(#937 验收)
|
||||
|
||||
- [x] 文档落盘 ✅
|
||||
- [x] LiteLLM 配置文件示例 ✅
|
||||
- [x] 沙箱脚本就位(本次不实跑,避免影响生产)✅
|
||||
- [x] 行动项拆分(P1/P2/P3) ✅
|
||||
- [ ] 真实副 key 申请(交给商务)
|
||||
- [ ] 后台 UI 实现(等 P2 启动)
|
||||
Reference in new issue
Block a user