# VolcSync - LiteLLM 火山模型监控与限额说明

## 当前生效入口

当前 `config.yaml` 使用的回调入口是：

```yaml
callbacks: ["volc_limit_sync.proxy_handler_instance"]
```

这意味着当前 Docker 容器里真正生效的是 `volc_limit_sync.py`。

`daily_limit.py` 目前 **未启用**，只保留作历史参考。除非你把 `callbacks` 改回 `daily_limit.py`，否则改它里面的 `MODEL_QUOTAS` 不会影响当前运行行为。

---

## 术语约定

为避免再把“白名单”这种不准确的说法带进来，这个仓库统一使用下面几组名称：

- **纳入监控模型**
  - 指 `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` 后，执行：

```bash
python generate_keys.py
```

这个脚本现在不是单纯“生成 key”，而是正式的 **监控模型审计入口**。它会输出：

- 当前从 `config.yaml` 发现了哪些“纳入监控模型”
- 每个上游模型对应哪些“监控别名”
- 每个模型当前命中的限额来源
  - 自定义键
  - 模型级规则
  - 模糊规则
  - `__DEFAULT__`
- 哪些模型当前仍在使用 `__DEFAULT__`
- 如果你想把默认限额改成单模型硬限额，应复制哪些 key 到 `HARD_DAILY_LIMITS`

### 特殊入口：`volc_limit_sync.py`

只有下面两种情况，才需要改 `volc_limit_sync.py`：

1. 资源包名和上游模型名不一致

示例：

```python
"doubao-seed-code": "doubao-seed-code-preview-251028"
```

2. 一个资源包要映射到多个上游模型

示例：

```python
"doubao-seed-1-6": ["doubao-seed-1-6-250615", "doubao-seed-1-6-251015"]
```

如果只是新增一个普通的版本号模型，例如 `xxx-260215`，通常不需要改这里。

---

## 推荐维护流程

### 新增监控模型

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,
}
```

---

## 常见坑

### 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
```

所以普通版本升级时，通常只需要改 `config.yaml`，再跑一遍 `python generate_keys.py` 审计确认。

---

## 常用命令

### 审计当前纳入监控模型

```bash
python generate_keys.py
```

### 直接运行同步监控

```bash
python volc_limit_sync.py
```

### LiteLLM 调试模式

```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`