169 lines
5.0 KiB
Markdown
169 lines
5.0 KiB
Markdown
# TODO — LiteLLM Gateway
|
||
|
||
> 建立时间：2026-04-10
|
||
> 负责人：西莉雅 (Sileya)
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
### 问题
|
||
- MiniMax M2.7 频繁返回 529（服务过载），导致 session 被 terminate
|
||
- Agent 的 API Key 存在泄漏风险（直接写在配置里）
|
||
- 没有额度管控，agent 滥用无法控制
|
||
- 缺少统一日志，无法追踪用量
|
||
|
||
### 目标
|
||
在 OMV（Nas/Proxmox）节点上部署 LiteLLM Gateway，实现：
|
||
1. MiniMax API 安全代理（key 集中管理）
|
||
2. 模型自动回落（M2.7 → M2.5 → M2.5-Lightning）
|
||
3. per-key 额度管控
|
||
4. 完整 API 管理接口（用量查询、key 生成/封禁）
|
||
5. Sileya Skill 化（通过 API 动态管理）
|
||
|
||
---
|
||
|
||
## 部署规划
|
||
|
||
### 部署节点
|
||
- **OMV (Open Media Vault)** — 运行在 NAS 上的 Proxmox 容器
|
||
- 或者直接跑在 Nas 本身（推荐，更简单）
|
||
|
||
### 模型路由策略
|
||
```
|
||
优先: MiniMax-M2.7
|
||
↓ 529 / 超时 / 500
|
||
备用: MiniMax-M2.5
|
||
↓ 529 / 超时 / 500
|
||
兜底: MiniMax-M2.5-Lightning
|
||
```
|
||
|
||
### 双 Key 隔离
|
||
- `sk-sileya-fixed` — 西莉雅的专属 key，指向固定 model group，**不动 config.yaml 就永远不受影响**
|
||
- `sk-admin-*` — 管理员 key，可动态管理其他 key
|
||
|
||
### 热更新策略
|
||
| 操作 | 是否需要重启 |
|
||
|------|------------|
|
||
| `/key/generate` 生成新 key | ❌ 不需要 |
|
||
| `/key/block` 封禁 key | ❌ 不需要 |
|
||
| `/model/new` 动态加模型 | ❌ 不需要 |
|
||
| 改 fallback 策略 / 模型顺序 | ⚠️ 需要（但不频繁，重启 < 5s）|
|
||
|
||
---
|
||
|
||
## 待办事项
|
||
|
||
### P0 — 必须完成（网关可用）
|
||
- [ ] **DEPLOY-01**: 在 OMV/Nas 上安装 Python 环境 + pip install litellm
|
||
- [ ] **DEPLOY-02**: 配置 `config.yaml`（MiniMax provider + fallback 路由 + virtual key）
|
||
- [ ] **DEPLOY-03**: 配置 `.env`（MINIMAX_API_KEY + LITELLM_MASTER_KEY）
|
||
- [ ] **DEPLOY-04**: 启动验证 — curl 测试 `/health`
|
||
- [ ] **DEPLOY-05**: OpenClaw 接入 — 修改 `openclaw.json` 的 model provider 指向 LiteLLM
|
||
|
||
### P1 — 管控能力
|
||
- [ ] **MGMT-01**: 生成各 agent 的专属 key（`sk-sileya-fixed`、`sk-ligoudan`、`sk-nico`）
|
||
- [ ] **MGMT-02**: 配置 per-key RPM 限制（各 agent 独立额度）
|
||
- [ ] **MGMT-03**: Sileya Skill — `lite-llm-admin`（用量查询、key 管理接口）
|
||
- [ ] **MGMT-04**: 验证 hot reload — 测试 `/key/generate` 不影响 Sileya session
|
||
|
||
### P2 — 安全加固
|
||
- [ ] **SEC-01**: 网络隔离 — LiteLLM 仅内网可访问，Tailscale/ZeroTier 组网
|
||
- [ ] **SEC-02**: 确认 Sileya 的 key 配置在 `config.yaml` 固定区域，不参与动态更新
|
||
- [ ] **SEC-03**: 审计日志 — 确认所有请求记录到数据库
|
||
|
||
### P3 — 可选优化
|
||
- [ ] **OPT-01**: LiteLLM Dashboard（`:4000/ui`）启用，Web UI 管理
|
||
- [ ] **OPT-02**: Prometheus metrics 接入（Grafana 监控）
|
||
- [ ] **OPT-03**: 多 provider 预留 — 对接其他 LLM（Claude/GPT）时网关层无需修改
|
||
|
||
---
|
||
|
||
## 关键配置
|
||
|
||
### config.yaml 核心结构
|
||
```yaml
|
||
model_list:
|
||
- model_name: MiniMax-M2.7
|
||
litellm_params:
|
||
model: minimax/MiniMax-M2.7
|
||
api_key: os.environ/MINIMAX_API_KEY
|
||
api_base: https://api.minimax.io/v1
|
||
rpm: 60
|
||
|
||
- model_name: MiniMax-M2.5
|
||
litellm_params:
|
||
model: minimax/MiniMax-M2.5
|
||
api_key: os.environ/MINIMAX_API_KEY
|
||
api_base: https://api.minimax.io/v1
|
||
rpm: 60
|
||
|
||
- model_name: MiniMax-M2.5-Lightning
|
||
litellm_params:
|
||
model: minimax/MiniMax-M2.5-Lightning
|
||
api_key: os.environ/MINIMAX_API_KEY
|
||
api_base: https://api.minimax.io/v1
|
||
rpm: 120
|
||
|
||
router_settings:
|
||
fallback_params: [{"model": ["MiniMax-M2.7", "MiniMax-M2.5", "MiniMax-M2.5-Lightning"]}]
|
||
num_retries: 3
|
||
retry_after: 5
|
||
timeout: 30
|
||
|
||
general_settings:
|
||
master_key: os.environ/LITELLM_MASTER_KEY
|
||
```
|
||
|
||
### Sileya Key 专属配置（不参与动态更新）
|
||
```yaml
|
||
# config.yaml 中的 sileya 专属区
|
||
# 此区域修改需要重启，但这种情况极低频
|
||
```
|
||
|
||
---
|
||
|
||
## API 接口
|
||
|
||
### 管理 API（admin key）
|
||
```
|
||
POST /key/generate — 生成新 key
|
||
GET /key/info?key=sk-xxx — 查询 key 用量
|
||
GET /spend — 查询总用量
|
||
POST /key/block — 封禁 key
|
||
POST /key/unblock — 解封 key
|
||
POST /model/new — 动态添加模型（热生效）
|
||
```
|
||
|
||
### 对外 API（agent 使用）
|
||
```
|
||
POST /v1/chat/completions — 标准 OpenAI 兼容接口
|
||
GET /health — 健康检查
|
||
```
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
```
|
||
litellm-gateway/
|
||
├── README.md
|
||
├── TODO.md
|
||
├── config.yaml # 主配置
|
||
├── .env.example # 环境变量模板
|
||
├── requirements.txt # Python 依赖
|
||
├── run.sh # 启动脚本
|
||
└── docs/
|
||
├── CONFIG_GUIDE.md
|
||
├── DEPLOYMENT.md
|
||
└── SKILL_INTEGRATION.md
|
||
```
|
||
|
||
---
|
||
|
||
## 里程碑
|
||
|
||
- [ ] **M1**: LiteLLM 在 OMV 上跑通，health check 通过
|
||
- [ ] **M2**: Sileya 通过 LiteLLM 代理访问 MiniMax，fallback 验证通过
|
||
- [ ] **M3**: 所有 agent 迁移到独立 key 体系
|
||
- [ ] **M4**: Sileya Skill `lite-llm-admin` 可用，日常管理无需手动操作
|