kim/litellm-config

Fork 0

Files

T

kim bc9f4e4680 Add README.md for volc_limit_sync

2026-01-30 09:01:03 +08:00

4.7 KiB

Raw Blame History

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 中。

架构设计

核心组件

DailyLimitHandler：使用记录和限制检查
QuotaInterceptor：请求前的配额检查
SoftEvict/Restore：模型路由管理
ActiveMonitorLoop：资源包同步和动态限制计算
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 中自动发现火山引擎配置的模型。

故障排除

常见问题

Redis 连接失败
- 检查环境变量配置
- 确保 Redis 服务正在运行
模型未被识别
- 检查 config.yaml 中的模型配置
- 确保 api_base 包含"volcengineapi"或"HUOSHAN_BASE_URL"
同步失败
- 检查火山引擎 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 社区

4.7 KiB Raw Blame History