# 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 社区