From d9c7b1406d10946341c07dd760f2510766ea29cc Mon Sep 17 00:00:00 2001 From: vibe-code Date: Wed, 12 Aug 2026 06:58:16 +0000 Subject: [PATCH] =?UTF-8?q?refactor:=20=E7=9B=AE=E5=BD=95=E6=95=B4?= =?UTF-8?q?=E7=90=86=E9=85=8D=E5=A5=97=E5=BC=95=E7=94=A8=E5=90=8C=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README/AGENTS 文件清单与命令更新为新结构（generate_keys -> scripts/、 daily_limit -> archive/、文档 -> docs/）；config.yaml 与 volc_consume.py 注释中废弃脚本/文档路径同步；README 过期限额示例更新为 2M 配置。 --- AGENTS.md | 10 +++++---- README.md | 54 ++++++++++++++++++++++++++++++------------------- config.yaml | 2 +- volc_consume.py | 2 +- 4 files changed, 41 insertions(+), 27 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 59361e1..a2ce3c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,12 +7,14 @@ - **核心逻辑**：通过 `quota_interceptor` 拦截请求，并通过 `DailyLimitHandler` 记录用量到 Redis。后台 `active_monitor_loop` 守护线程定期从火山引擎 API 同步配额到 Redis。 - **架构**：主逻辑在 `volc_limit_sync.py`（限额 + 同步守护 + 每日消耗调度），消耗任务拆分在 `volc_consume.py`（每日北京时间 23:00 由守护线程延迟导入触发；见 `merge-auto-consume.md`）。LiteLLM 通过 `config.yaml` 中 `callbacks: ["volc_limit_sync.proxy_handler_instance"]` 加载回调，模块加载时自动启动后台同步线程。 - **关键文件**： - - `volc_limit_sync.py`: **核心文件**，包含同步守护线程（`active_monitor_loop`）、LiteLLM 回调（`DailyLimitHandler` + `quota_interceptor`）、限额计算（v2 简化：`stable_limit = usage + balance − BUFFER`，dynamic 缺失时 fallback `FALLBACK_LIMIT` 90 万兜底）、模型屏蔽/恢复、以及每日 23:00 消耗任务调度（`_maybe_trigger_daily_consume`，SETNX 去重）。 + - `volc_limit_sync.py`: **核心文件**，包含同步守护线程（`active_monitor_loop`）、LiteLLM 回调（`DailyLimitHandler` + `quota_interceptor`）、限额计算（v4 冻结快照：`stable_limit = balance − BUFFER`，`effective_limit = min(2M 采集配额, stable_limit)`；扣费红线 = 余额，与采集量/返还无关，见 `docs/volc-quota-notes.md`）、模型屏蔽/恢复、以及每日 23:00 消耗任务调度（`_maybe_trigger_daily_consume`，SETNX 去重）。 - `volc_consume.py`: 消耗任务模块（每日 23:00 触发；手动 `python volc_consume.py --dry-run` / `--force`）。复用 volc_limit_sync 的拉包/归一化/用量记账设施，直连 Ark API 洗即将过期的免费资源包（防 30 天过期蒸发）。 - `config.yaml`: LiteLLM 配置文件，包含模型定义和回调配置。 - - `docker-compose.yml`: 容器编排，仅挂载 `config.yaml` 和 `volc_limit_sync.py`。 - - `debug_volc_sync.py` / `debug_volc_sync_manual.py`: 调试脚本，用于手动验证 API 和 Redis 状态。 - - `daily_limit.py.deprecated`: 已废弃，功能已全部合并到 `volc_limit_sync.py`，仅保留作历史参考。 + - `docker-compose.yml`: 容器编排，仅挂载 `config.yaml`、`volc_limit_sync.py`、`volc_consume.py`。 + - `docs/`: 设计文档与额度机制速查（`merge-auto-consume.md` 消耗任务/限额设计、`volc-quota-notes.md` 火山额度机制事实基础、`merge-volc-limit-into-newapi.md` 未实施的迁移方案）。 + - `debug/`: 调试脚本（`debug_volc_sync.py` / `debug_volc_sync_manual.py`），手动验证 API 和 Redis 状态。 + - `scripts/`: 工具脚本（`generate_keys.py` 监控模型审计入口）。 + - `archive/`: 已废弃（`daily_limit.py.deprecated` 历史参考、`recover.py` 一次性恢复工具）。 ## 2. 环境与运行 (Build & Run) diff --git a/README.md b/README.md index 3cd3a5c..b6bb83e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ callbacks: ["volc_limit_sync.proxy_handler_instance"] 这意味着当前 Docker 容器里真正生效的是 `volc_limit_sync.py`。 -`daily_limit.py` 目前 **未启用**，只保留作历史参考。除非你把 `callbacks` 改回 `daily_limit.py`，否则改它里面的 `MODEL_QUOTAS` 不会影响当前运行行为。 +旧脚本 `archive/daily_limit.py.deprecated` 目前 **未启用**，只保留作历史参考。除非你把 `callbacks` 改回旧模块，否则改它里面的 `MODEL_QUOTAS` 不会影响当前运行行为。 --- @@ -62,7 +62,7 @@ glm-4-7-251222 -> glm-4-7 每次改完 `config.yaml` 后，执行： ```bash -python generate_keys.py +python scripts/generate_keys.py ``` 这个脚本现在不是单纯“生成 key”，而是正式的 **监控模型审计入口**。它会输出： @@ -106,7 +106,7 @@ python generate_keys.py ### 新增监控模型 1. 在 `config.yaml` 的 `model_list` 里加入新的火山模型条目。 -2. 运行 `python generate_keys.py`。 +2. 运行 `python scripts/generate_keys.py`。 3. 先确认脚本输出中： - 该模型已经出现在“监控模型审计”里。 - “监控别名”正确。 @@ -119,7 +119,7 @@ python generate_keys.py ### 删除监控模型 1. 从 `config.yaml` 里删掉对应模型条目。 -2. 运行 `python generate_keys.py`，确认它已经不在“监控模型审计”里。 +2. 运行 `python scripts/generate_keys.py`，确认它已经不在“监控模型审计”里。 3. 如果该模型曾有单独的 `HARD_DAILY_LIMITS` 项，可以按需清理。 4. 如果该模型对应的是特殊手工别名，且已经没有任何上游模型再用它，可以再清理 `MANUAL_MONITORED_MODEL_ALIASES`。 5. 重启 LiteLLM 容器。 @@ -160,14 +160,14 @@ python generate_keys.py 3. 模糊规则 4. `__DEFAULT__` -例如： +例如（当前值，2026-08）： ```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, + # 火山免费额度规则：每模型每日采集上限 2M，次日按采集量发放资源包。 + # 采集上限封顶；真正决定今日可采的是 v4 动态层： + # effective = min(2M, stable_limit)，stable_limit = 余额快照 − BUFFER（见 docs/volc-quota-notes.md） + "__DEFAULT__": 2_000_000, } ``` @@ -175,13 +175,13 @@ HARD_DAILY_LIMITS = { ## 常见坑 -### 1. 改了 `daily_limit.py` 但不生效 +### 1. 改了旧脚本（`archive/daily_limit.py.deprecated`）但不生效 这是最容易踩的坑。 -当前 `config.yaml` 没有启用 `daily_limit.py`，所以： +当前 `config.yaml` 没有启用旧模块 `daily_limit`，所以： -- 改 `daily_limit.py` +- 改 `archive/daily_limit.py.deprecated` - 改 `MODEL_QUOTAS` 都不会影响当前 LiteLLM 容器的启动和监控行为。 @@ -204,7 +204,7 @@ xxx-251201 -> xxx xxx-260215 -> xxx ``` -所以普通版本升级时，通常只需要改 `config.yaml`，再跑一遍 `python generate_keys.py` 审计确认。 +所以普通版本升级时，通常只需要改 `config.yaml`，再跑一遍 `python scripts/generate_keys.py` 审计确认。 --- @@ -213,7 +213,7 @@ xxx-260215 -> xxx ### 审计当前纳入监控模型 ```bash -python generate_keys.py +python scripts/generate_keys.py ``` ### 直接运行同步监控 @@ -235,18 +235,30 @@ 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 # 手动调试脚本 +├── docker-compose.yml # 容器编排（挂载 config.yaml / volc_limit_sync.py / volc_consume.py） +├── volc_limit_sync.py # 当前生效的监控、同步、限额脚本（v4 冻结快照限额） +├── volc_consume.py # 每日 23:00 自动消耗任务（防免费资源包过期蒸发） +├── AGENTS.md # 仓库 Agent 协议（代码风格/运行/提交规范） +├── README.md +├── docs/ +│ ├── merge-auto-consume.md # 消耗任务 + 限额设计（v2 历史 / v4 修订） +│ ├── volc-quota-notes.md # 火山额度机制速查（扣费口径/方案演进/排障） +│ └── merge-volc-limit-into-newapi.md # 未实施的迁移方案（历史） +├── scripts/ +│ └── generate_keys.py # 监控模型审计入口 +├── debug/ +│ ├── debug_volc_sync.py # 资源包调试脚本 +│ └── debug_volc_sync_manual.py # 手动调试脚本 +└── archive/ + ├── daily_limit.py.deprecated # 旧脚本，当前 config 未启用（历史参考） + └── recover.py # 一次性恢复工具（历史） ``` --- ## 维护原则 -- 先改 `config.yaml`，不要先改 `daily_limit.py` -- 先跑 `python generate_keys.py` 审计，再决定要不要补 `HARD_DAILY_LIMITS` +- 先改 `config.yaml`，不要先改旧脚本 `archive/daily_limit.py.deprecated` +- 先跑 `python scripts/generate_keys.py` 审计，再决定要不要补 `HARD_DAILY_LIMITS` - 普通版本号模型优先依赖自动推导，不要手工补一堆重复映射 - 只有特殊别名或一对多场景，才改 `MANUAL_MONITORED_MODEL_ALIASES` diff --git a/config.yaml b/config.yaml index fde4070..0b32d08 100644 --- a/config.yaml +++ b/config.yaml @@ -473,7 +473,7 @@ litellm_settings: allowed_fails: 3 # cooldown model if it fails > 1 call in a minute. # 当前生效入口：volc_limit_sync.py # 监控模型发现、监控别名推导、资源包同步、HARD_DAILY_LIMITS 都在这个脚本里。 - # daily_limit.py 当前未启用，仅保留作历史参考。 + # 旧脚本 archive/daily_limit.py.deprecated 当前未启用，仅保留作历史参考。 callbacks: ["volc_limit_sync.proxy_handler_instance"] router_settings: # router_settings are optional diff --git a/volc_consume.py b/volc_consume.py index 88f04b7..afdafa0 100644 --- a/volc_consume.py +++ b/volc_consume.py @@ -1,7 +1,7 @@ # ========================================== # 🚀 VolcConsume — 火山免费额度自动消耗任务 # ========================================== -# 与 volc_limit_sync.py 合并方案的一部分（见 merge-auto-consume.md）： +# 与 volc_limit_sync.py 合并方案的一部分（见 docs/merge-auto-consume.md）： # - 每日北京时间 23:00 由 volc_limit_sync 守护线程触发（可手动 --force） # - 洗掉 CONSUME_MONITOR_DAYS 天内过期的资源包额度（FIFO 下即队列头部）， # 防止 30 天过期蒸发导致"启动资金"缩水（免费额度规则：消耗 X → 次日返还 X）