VolcSync - LiteLLM 火山引擎每日限制管理系统

项目概述

VolcSync 是一个专为 LiteLLM 代理服务器设计的智能每日限制管理系统，专注于火山引擎 API 的使用限制控制和资源包同步。它提供了动态限制计算、自动模型路由管理和资源包余额实时同步功能。

核心功能

1. 智能限制管理

• 动态限制计算：基于资源包余额和使用模式自动调整每日限制
• 硬性限制配置：支持静态配置特定模型的每日硬限制
• 北京时区优化：完全按照北京时间 (UTC+8) 进行每日限制计算
• 多层级限制策略：支持精确匹配、模糊匹配和默认策略

2. 自动模型路由管理

• 软驱逐机制：当模型达到每日限制时自动禁用路由
• 自动恢复机制：定期检查已禁用模型的配额恢复情况
• 恢复策略优化：根据时间段动态调整检查频率

3. 资源包同步

• 火山引擎 API 集成：实时同步资源包余额
• 智能缓存策略：基于余额和使用模式动态调整同步频率
• 突发流量检测：自动检测异常流量并触发紧急同步
• 资源包去重：处理火山引擎 API 响应中的重复项

4. 监控与日志

• 详细使用统计：实时跟踪每个模型的使用情况
• 多级别日志：支持 DEBUG、INFO、WARNING、ERROR 级别
• 可视化指标：使用 emoji 图标增强日志可读性
• 配置自动发现：自动从 config.yaml 中发现火山引擎模型

安装与配置

1. 依赖安装

pip install litellm redis requests

2. 环境变量配置

# 火山引擎认证
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. 作为模块导入

from volc_limit_sync import proxy_handler_instance

2. 直接运行监控

python volc_limit_sync.py

3. 集成到 LiteLLM 代理服务器

系统会自动作为回调函数注册到 LiteLLM 的 input_callback 和 callbacks 中。

架构设计

核心组件

1. DailyLimitHandler：使用记录和限制检查
2. QuotaInterceptor：请求前的配额检查
3. SoftEvict/Restore：模型路由管理
4. ActiveMonitorLoop：资源包同步和动态限制计算
5. Util Functions：工具函数集合（哈希、清理、签名）

关键策略

动态限制算法

# 基于资源包峰值 - 安全缓冲计算有效限制
effective_limit = max(0, current_peak - safety_margin)

同步频率调整

• 高余额时：低频同步（每小时）
• 低余额时：高频同步（每2分钟）
• 突发流量：立即同步

北京时区处理

beijing_time_ts = now + (8 * 3600)
date_str = time.strftime("%Y-%m-%d", time.gmtime(beijing_time_ts))

配置说明

硬限制配置

HARD_DAILY_LIMITS = {
    "doubao-seed-code-preview-251028": 4_800_000,
    "__DEFAULT__": 1_800_000,
}

模型映射

VOLC_MODEL_MAP = {
    "doubao-seed-1-6": ["doubao-seed-1-6-250615", "doubao-seed-1-6-251015"],
    "deepseek-v3": "deepseek-v3-250324",
}

同步参数

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 配置

调试模式

DAILY_LIMIT_LOG_LEVEL="DEBUG" python volc_limit_sync.py

许可证

MIT License

作者

OpenCode 社区