fix: streamline monitored model maintenance
This commit is contained in:
@@ -1,180 +1,252 @@
|
||||
# VolcSync - LiteLLM 火山引擎每日限制管理系统
|
||||
# VolcSync - LiteLLM 火山模型监控与限额说明
|
||||
|
||||
## 项目概述
|
||||
## 当前生效入口
|
||||
|
||||
VolcSync 是一个专为 LiteLLM 代理服务器设计的智能每日限制管理系统，专注于火山引擎 API 的使用限制控制和资源包同步。它提供了动态限制计算、自动模型路由管理和资源包余额实时同步功能。
|
||||
当前 `config.yaml` 使用的回调入口是：
|
||||
|
||||
## 核心功能
|
||||
```yaml
|
||||
callbacks: ["volc_limit_sync.proxy_handler_instance"]
|
||||
```
|
||||
|
||||
### 1. 智能限制管理
|
||||
- **动态限制计算**：基于资源包余额和使用模式自动调整每日限制
|
||||
- **硬性限制配置**：支持静态配置特定模型的每日硬限制
|
||||
- **北京时区优化**：完全按照北京时间 (UTC+8) 进行每日限制计算
|
||||
- **多层级限制策略**：支持精确匹配、模糊匹配和默认策略
|
||||
这意味着当前 Docker 容器里真正生效的是 `volc_limit_sync.py`。
|
||||
|
||||
### 2. 自动模型路由管理
|
||||
- **软驱逐机制**：当模型达到每日限制时自动禁用路由
|
||||
- **自动恢复机制**：定期检查已禁用模型的配额恢复情况
|
||||
- **恢复策略优化**：根据时间段动态调整检查频率
|
||||
`daily_limit.py` 目前 **未启用**，只保留作历史参考。除非你把 `callbacks` 改回 `daily_limit.py`，否则改它里面的 `MODEL_QUOTAS` 不会影响当前运行行为。
|
||||
|
||||
### 3. 资源包同步
|
||||
- **火山引擎 API 集成**：实时同步资源包余额
|
||||
- **智能缓存策略**：基于余额和使用模式动态调整同步频率
|
||||
- **突发流量检测**：自动检测异常流量并触发紧急同步
|
||||
- **资源包去重**：处理火山引擎 API 响应中的重复项
|
||||
---
|
||||
|
||||
### 4. 监控与日志
|
||||
- **详细使用统计**：实时跟踪每个模型的使用情况
|
||||
- **多级别日志**：支持 DEBUG、INFO、WARNING、ERROR 级别
|
||||
- **可视化指标**：使用 emoji 图标增强日志可读性
|
||||
- **配置自动发现**：自动从 config.yaml 中发现火山引擎模型
|
||||
## 术语约定
|
||||
|
||||
## 安装与配置
|
||||
为避免再把“白名单”这种不准确的说法带进来，这个仓库统一使用下面几组名称：
|
||||
|
||||
- **纳入监控模型**
|
||||
- 指 `config.yaml` 中启用了火山 `api_base` 的上游模型。
|
||||
- 这些模型会被 `volc_limit_sync.py` 自动发现，并参与资源包同步、用量统计和限额控制。
|
||||
|
||||
- **监控别名**
|
||||
- 指火山资源包返回的名字，经过归一化后，用来匹配“纳入监控模型”的名字。
|
||||
- 例如 `doubao-seed-2-0-pro-260215` 会自动推导出监控别名 `doubao-seed-2-0-pro`。
|
||||
|
||||
- **手工别名覆盖**
|
||||
- 指 `volc_limit_sync.py` 中 `MANUAL_MONITORED_MODEL_ALIASES` 里的特殊映射。
|
||||
- 只用于两类场景：
|
||||
- 资源包名和上游模型名不一致。
|
||||
- 一个资源包要映射到多个上游模型。
|
||||
|
||||
- **硬限额**
|
||||
- 指 `volc_limit_sync.py` 中的 `HARD_DAILY_LIMITS`。
|
||||
- 支持三种常见粒度：
|
||||
- `model:hash`
|
||||
- `model`
|
||||
- `__DEFAULT__`
|
||||
|
||||
---
|
||||
|
||||
## 维护入口
|
||||
|
||||
### 主入口：`config.yaml`
|
||||
|
||||
新增、删除“纳入监控模型”时，第一步永远是改 `config.yaml` 里的 `model_list`。
|
||||
|
||||
对大多数正常的版本号模型，做到这一步就已经足够让运行时识别它们进入监控链路了。现在的逻辑会自动把：
|
||||
|
||||
```text
|
||||
deepseek-v3-2-251201 -> deepseek-v3-2
|
||||
doubao-seed-2-0-pro-260215 -> doubao-seed-2-0-pro
|
||||
glm-4-7-251222 -> glm-4-7
|
||||
```
|
||||
|
||||
这类常规版本号模型推导成监控别名，不需要你再手工去补映射。
|
||||
|
||||
### 审计入口：`generate_keys.py`
|
||||
|
||||
每次改完 `config.yaml` 后，执行：
|
||||
|
||||
### 1. 依赖安装
|
||||
```bash
|
||||
pip install litellm redis requests
|
||||
python generate_keys.py
|
||||
```
|
||||
|
||||
### 2. 环境变量配置
|
||||
```bash
|
||||
# 火山引擎认证
|
||||
VOLC_ACCESS_KEY="your-access-key"
|
||||
VOLC_SECRET_KEY="your-secret-key"
|
||||
这个脚本现在不是单纯“生成 key”，而是正式的 **监控模型审计入口**。它会输出：
|
||||
|
||||
# Redis 连接
|
||||
REDIS_HOST="localhost"
|
||||
REDIS_PORT="6379"
|
||||
REDIS_PASSWORD="your-password"
|
||||
- 当前从 `config.yaml` 发现了哪些“纳入监控模型”
|
||||
- 每个上游模型对应哪些“监控别名”
|
||||
- 每个模型当前命中的限额来源
|
||||
- 自定义键
|
||||
- 模型级规则
|
||||
- 模糊规则
|
||||
- `__DEFAULT__`
|
||||
- 哪些模型当前仍在使用 `__DEFAULT__`
|
||||
- 如果你想把默认限额改成单模型硬限额，应复制哪些 key 到 `HARD_DAILY_LIMITS`
|
||||
|
||||
# 日志级别
|
||||
DAILY_LIMIT_LOG_LEVEL="INFO"
|
||||
```
|
||||
### 特殊入口：`volc_limit_sync.py`
|
||||
|
||||
### 3. 配置文件
|
||||
系统会自动读取 `config.yaml` 文件中的火山引擎模型配置。
|
||||
只有下面两种情况，才需要改 `volc_limit_sync.py`：
|
||||
|
||||
## 使用方法
|
||||
1. 资源包名和上游模型名不一致
|
||||
|
||||
示例：
|
||||
|
||||
### 1. 作为模块导入
|
||||
```python
|
||||
from volc_limit_sync import proxy_handler_instance
|
||||
"doubao-seed-code": "doubao-seed-code-preview-251028"
|
||||
```
|
||||
|
||||
### 2. 直接运行监控
|
||||
```bash
|
||||
python volc_limit_sync.py
|
||||
```
|
||||
2. 一个资源包要映射到多个上游模型
|
||||
|
||||
### 3. 集成到 LiteLLM 代理服务器
|
||||
系统会自动作为回调函数注册到 LiteLLM 的 input_callback 和 callbacks 中。
|
||||
示例：
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 核心组件
|
||||
|
||||
1. **DailyLimitHandler**：使用记录和限制检查
|
||||
2. **QuotaInterceptor**：请求前的配额检查
|
||||
3. **SoftEvict/Restore**：模型路由管理
|
||||
4. **ActiveMonitorLoop**：资源包同步和动态限制计算
|
||||
5. **Util Functions**：工具函数集合（哈希、清理、签名）
|
||||
|
||||
### 关键策略
|
||||
|
||||
#### 动态限制算法
|
||||
```python
|
||||
# 基于资源包峰值 - 安全缓冲计算有效限制
|
||||
effective_limit = max(0, current_peak - safety_margin)
|
||||
"doubao-seed-1-6": ["doubao-seed-1-6-250615", "doubao-seed-1-6-251015"]
|
||||
```
|
||||
|
||||
#### 同步频率调整
|
||||
- 高余额时：低频同步（每小时）
|
||||
- 低余额时：高频同步（每2分钟）
|
||||
- 突发流量：立即同步
|
||||
如果只是新增一个普通的版本号模型，例如 `xxx-260215`，通常不需要改这里。
|
||||
|
||||
#### 北京时区处理
|
||||
```python
|
||||
beijing_time_ts = now + (8 * 3600)
|
||||
date_str = time.strftime("%Y-%m-%d", time.gmtime(beijing_time_ts))
|
||||
```
|
||||
---
|
||||
|
||||
## 配置说明
|
||||
## 推荐维护流程
|
||||
|
||||
### 新增监控模型
|
||||
|
||||
1. 在 `config.yaml` 的 `model_list` 里加入新的火山模型条目。
|
||||
2. 运行 `python generate_keys.py`。
|
||||
3. 先确认脚本输出中：
|
||||
- 该模型已经出现在“监控模型审计”里。
|
||||
- “监控别名”正确。
|
||||
- “限额来源”符合预期。
|
||||
4. 如果只是走默认限额，到这一步通常已经可以结束。
|
||||
5. 如果需要单模型硬限额，把脚本输出的 key 复制到 `volc_limit_sync.py` 的 `HARD_DAILY_LIMITS`。
|
||||
6. 只有当脚本显示资源包名无法靠常规版本号自动推导时，再去改 `MANUAL_MONITORED_MODEL_ALIASES`。
|
||||
7. 重启 LiteLLM 容器，让新配置生效。
|
||||
|
||||
### 删除监控模型
|
||||
|
||||
1. 从 `config.yaml` 里删掉对应模型条目。
|
||||
2. 运行 `python generate_keys.py`，确认它已经不在“监控模型审计”里。
|
||||
3. 如果该模型曾有单独的 `HARD_DAILY_LIMITS` 项，可以按需清理。
|
||||
4. 如果该模型对应的是特殊手工别名，且已经没有任何上游模型再用它，可以再清理 `MANUAL_MONITORED_MODEL_ALIASES`。
|
||||
5. 重启 LiteLLM 容器。
|
||||
|
||||
---
|
||||
|
||||
## 运行时行为概览
|
||||
|
||||
### 1. 自动发现纳入监控模型
|
||||
|
||||
`volc_limit_sync.py` 启动后会扫描 `config.yaml`，找出使用火山 `api_base` 的上游模型，并记录：
|
||||
|
||||
- 监控的上游模型名
|
||||
- `api_base` 对应的 hash
|
||||
- 由上游模型自动推导出来的监控别名
|
||||
|
||||
### 2. 资源包名归一化
|
||||
|
||||
火山接口返回资源包名后，脚本会先做归一化：
|
||||
|
||||
- 去掉资源包后缀
|
||||
- 统一小写
|
||||
- `_` 和 `.` 归一化成 `-`
|
||||
|
||||
之后再尝试通过：
|
||||
|
||||
- 自动版本号推导
|
||||
- 手工别名覆盖
|
||||
|
||||
把资源包归到实际纳入监控的上游模型。
|
||||
|
||||
### 3. 限额来源优先级
|
||||
|
||||
`HARD_DAILY_LIMITS` 的命中顺序是：
|
||||
|
||||
1. `model:hash`
|
||||
2. `model`
|
||||
3. 模糊规则
|
||||
4. `__DEFAULT__`
|
||||
|
||||
例如：
|
||||
|
||||
### 硬限制配置
|
||||
```python
|
||||
HARD_DAILY_LIMITS = {
|
||||
"doubao-seed-code-preview-251028": 4_800_000,
|
||||
"doubao-seed-2-0-pro-260215:ba0383d3": 1_900_000,
|
||||
"doubao-seed-2-0-lite-260215:ba0383d3": 1_900_000,
|
||||
"__DEFAULT__": 1_800_000,
|
||||
}
|
||||
```
|
||||
|
||||
### 模型映射
|
||||
```python
|
||||
VOLC_MODEL_MAP = {
|
||||
"doubao-seed-1-6": ["doubao-seed-1-6-250615", "doubao-seed-1-6-251015"],
|
||||
"deepseek-v3": "deepseek-v3-250324",
|
||||
}
|
||||
---
|
||||
|
||||
## 常见坑
|
||||
|
||||
### 1. 改了 `daily_limit.py` 但不生效
|
||||
|
||||
这是最容易踩的坑。
|
||||
|
||||
当前 `config.yaml` 没有启用 `daily_limit.py`，所以：
|
||||
|
||||
- 改 `daily_limit.py`
|
||||
- 改 `MODEL_QUOTAS`
|
||||
|
||||
都不会影响当前 LiteLLM 容器的启动和监控行为。
|
||||
|
||||
### 2. 只补了硬限额，但没有纳入监控
|
||||
|
||||
`HARD_DAILY_LIMITS` 只负责限额，不负责把模型纳入监控。
|
||||
|
||||
模型是否被监控，首先取决于：
|
||||
|
||||
- `config.yaml` 是否有该火山模型条目
|
||||
- 资源包名是否能被自动推导或手工别名覆盖正确归到该模型
|
||||
|
||||
### 3. 普通版本号模型不需要每次都手改映射
|
||||
|
||||
现在的运行逻辑已经支持从上游模型自动推导：
|
||||
|
||||
```text
|
||||
xxx-251201 -> xxx
|
||||
xxx-260215 -> xxx
|
||||
```
|
||||
|
||||
### 同步参数
|
||||
```python
|
||||
BUFFER = 300000 # 安全缓冲
|
||||
SYNC_INTERVAL = 60 # 基础同步间隔
|
||||
CHECK_INTERVAL = 10 # 检查间隔
|
||||
THRESHOLD = 300000 # 硬阈值
|
||||
```
|
||||
所以普通版本升级时，通常只需要改 `config.yaml`，再跑一遍 `python generate_keys.py` 审计确认。
|
||||
|
||||
## 高级功能
|
||||
---
|
||||
|
||||
### 1. 模型别名处理
|
||||
支持一个火山引擎模型映射到多个 LiteLLM 模型。
|
||||
## 常用命令
|
||||
|
||||
### 2. API Base 哈希
|
||||
通过对 API Base 进行哈希处理，支持多端点配置。
|
||||
### 审计当前纳入监控模型
|
||||
|
||||
### 3. 资源包清理
|
||||
自动清理响应中的后缀（如"_pack_data_collaboration"）。
|
||||
|
||||
### 4. 配置自动发现
|
||||
从 config.yaml 中自动发现火山引擎配置的模型。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **Redis 连接失败**
|
||||
- 检查环境变量配置
|
||||
- 确保 Redis 服务正在运行
|
||||
|
||||
2. **模型未被识别**
|
||||
- 检查 config.yaml 中的模型配置
|
||||
- 确保 api_base 包含"volcengineapi"或"HUOSHAN_BASE_URL"
|
||||
|
||||
3. **同步失败**
|
||||
- 检查火山引擎 API 密钥
|
||||
- 验证网络连接
|
||||
|
||||
## 开发与维护
|
||||
|
||||
### 项目结构
|
||||
```
|
||||
litellm/
|
||||
├── volc_limit_sync.py # 主文件
|
||||
├── daily_limit.py # 每日限制计算
|
||||
├── debug_volc_sync.py # 调试工具
|
||||
├── debug_volc_sync_manual.py # 手动同步工具
|
||||
└── config.yaml # LiteLLM 配置
|
||||
```
|
||||
|
||||
### 调试模式
|
||||
```bash
|
||||
DAILY_LIMIT_LOG_LEVEL="DEBUG" python volc_limit_sync.py
|
||||
python generate_keys.py
|
||||
```
|
||||
|
||||
## 许可证
|
||||
### 直接运行同步监控
|
||||
|
||||
MIT License
|
||||
```bash
|
||||
python volc_limit_sync.py
|
||||
```
|
||||
|
||||
## 作者
|
||||
### LiteLLM 调试模式
|
||||
|
||||
OpenCode 社区
|
||||
```bash
|
||||
DAILY_LIMIT_LOG_LEVEL=DEBUG python volc_limit_sync.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件职责
|
||||
|
||||
```text
|
||||
litellm-config/
|
||||
├── config.yaml # 纳入监控模型的主入口
|
||||
├── volc_limit_sync.py # 当前生效的监控、同步、限额脚本
|
||||
├── generate_keys.py # 监控模型审计入口
|
||||
├── daily_limit.py # 旧脚本，当前 config 未启用
|
||||
├── debug_volc_sync.py # 资源包调试脚本
|
||||
└── debug_volc_sync_manual.py # 手动调试脚本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 维护原则
|
||||
|
||||
- 先改 `config.yaml`，不要先改 `daily_limit.py`
|
||||
- 先跑 `python generate_keys.py` 审计，再决定要不要补 `HARD_DAILY_LIMITS`
|
||||
- 普通版本号模型优先依赖自动推导，不要手工补一堆重复映射
|
||||
- 只有特殊别名或一对多场景，才改 `MANUAL_MONITORED_MODEL_ALIASES`
|
||||
|
||||
Reference in New Issue
Block a user