180 lines
4.7 KiB
Markdown
180 lines
4.7 KiB
Markdown
# VolcSync - LiteLLM 火山引擎每日限制管理系统
|
|
|
|
## 项目概述
|
|
|
|
VolcSync 是一个专为 LiteLLM 代理服务器设计的智能每日限制管理系统，专注于火山引擎 API 的使用限制控制和资源包同步。它提供了动态限制计算、自动模型路由管理和资源包余额实时同步功能。
|
|
|
|
## 核心功能
|
|
|
|
### 1. 智能限制管理
|
|
- **动态限制计算**：基于资源包余额和使用模式自动调整每日限制
|
|
- **硬性限制配置**：支持静态配置特定模型的每日硬限制
|
|
- **北京时区优化**：完全按照北京时间 (UTC+8) 进行每日限制计算
|
|
- **多层级限制策略**：支持精确匹配、模糊匹配和默认策略
|
|
|
|
### 2. 自动模型路由管理
|
|
- **软驱逐机制**：当模型达到每日限制时自动禁用路由
|
|
- **自动恢复机制**：定期检查已禁用模型的配额恢复情况
|
|
- **恢复策略优化**：根据时间段动态调整检查频率
|
|
|
|
### 3. 资源包同步
|
|
- **火山引擎 API 集成**：实时同步资源包余额
|
|
- **智能缓存策略**：基于余额和使用模式动态调整同步频率
|
|
- **突发流量检测**：自动检测异常流量并触发紧急同步
|
|
- **资源包去重**：处理火山引擎 API 响应中的重复项
|
|
|
|
### 4. 监控与日志
|
|
- **详细使用统计**：实时跟踪每个模型的使用情况
|
|
- **多级别日志**：支持 DEBUG、INFO、WARNING、ERROR 级别
|
|
- **可视化指标**：使用 emoji 图标增强日志可读性
|
|
- **配置自动发现**：自动从 config.yaml 中发现火山引擎模型
|
|
|
|
## 安装与配置
|
|
|
|
### 1. 依赖安装
|
|
```bash
|
|
pip install litellm redis requests
|
|
```
|
|
|
|
### 2. 环境变量配置
|
|
```bash
|
|
# 火山引擎认证
|
|
VOLC_ACCESS_KEY="your-access-key"
|
|
VOLC_SECRET_KEY="your-secret-key"
|
|
|
|
# Redis 连接
|
|
REDIS_HOST="localhost"
|
|
REDIS_PORT="6379"
|
|
REDIS_PASSWORD="your-password"
|
|
|
|
# 日志级别
|
|
DAILY_LIMIT_LOG_LEVEL="INFO"
|
|
```
|
|
|
|
### 3. 配置文件
|
|
系统会自动读取 `config.yaml` 文件中的火山引擎模型配置。
|
|
|
|
## 使用方法
|
|
|
|
### 1. 作为模块导入
|
|
```python
|
|
from volc_limit_sync import proxy_handler_instance
|
|
```
|
|
|
|
### 2. 直接运行监控
|
|
```bash
|
|
python volc_limit_sync.py
|
|
```
|
|
|
|
### 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)
|
|
```
|
|
|
|
#### 同步频率调整
|
|
- 高余额时：低频同步（每小时）
|
|
- 低余额时：高频同步（每2分钟）
|
|
- 突发流量：立即同步
|
|
|
|
#### 北京时区处理
|
|
```python
|
|
beijing_time_ts = now + (8 * 3600)
|
|
date_str = time.strftime("%Y-%m-%d", time.gmtime(beijing_time_ts))
|
|
```
|
|
|
|
## 配置说明
|
|
|
|
### 硬限制配置
|
|
```python
|
|
HARD_DAILY_LIMITS = {
|
|
"doubao-seed-code-preview-251028": 4_800_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",
|
|
}
|
|
```
|
|
|
|
### 同步参数
|
|
```python
|
|
BUFFER = 300000 # 安全缓冲
|
|
SYNC_INTERVAL = 60 # 基础同步间隔
|
|
CHECK_INTERVAL = 10 # 检查间隔
|
|
THRESHOLD = 300000 # 硬阈值
|
|
```
|
|
|
|
## 高级功能
|
|
|
|
### 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
|
|
```
|
|
|
|
## 许可证
|
|
|
|
MIT License
|
|
|
|
## 作者
|
|
|
|
OpenCode 社区 |