vibe-code
96b81d52c4
- 新增 volc_consume.py：消耗任务模块，直连 Ark 洗 9 天内过期资源包 （旧 calculate_plan 均分×1.1/24h冲刺保留 + 双 clamp：2M 采集上限、余额−BUFFER 防扣费） - volc_limit_sync.py：限额 v2 简化（stable_limit = usage+balance−BUFFER，删除峰值状态机 ~90 行）， HARD_DAILY_LIMITS 统一 2M（pre-block 不滞后，1.8M 折扣作废）， 新增 _maybe_trigger_daily_consume（北京时间 23:00 ± 抖动，SETNX 去重，延迟导入） - docker-compose 挂载 volc_consume.py；AGENTS.md/文档同步
310 lines
18 KiB
Markdown
310 lines
18 KiB
Markdown
# 火山免费额度自动消耗：auto_consume 合入 volc_limit_sync 设计方案
|
||
|
||
> 日期：2026-08-11
|
||
> 背景：`/root/workspace/huoshan-api-auto_consume/`（自动消耗脚本）与 `/root/workspace/litellm-config/`（LiteLLM 限流回调 + 火山余额同步）合并，使每日 23:00 自动消耗免费额度，防止资源包过期蒸发，避免真实扣费。
|
||
> 前置文档：《merge-volc-limit-into-newapi.md》（2026-08-05，方向相反：把 volc_limit_sync 功能迁往 new-api，未实施）。
|
||
|
||
---
|
||
|
||
## 一、火山免费额度业务模型（一切设计的事实基础）
|
||
|
||
### 1.1 日返还循环
|
||
|
||
```
|
||
每天任意时刻 真实用户 + 消耗任务 的消耗 = 当日采集量（火山实时统计，每模型单独计算）
|
||
每天 23:00 CST 消耗任务补齐缺口（可选，见 §4）
|
||
次日 00:00 起 火山按昨日采集量发放资源包（不定时，可能延迟到上午）
|
||
```
|
||
|
||
### 1.2 五个硬规则（用户确认）
|
||
|
||
| 规则 | 值 | 影响 |
|
||
|---|---|---|
|
||
| 采集上限 | **2M token/模型/天** | 消耗超过 2M 的部分**不返还**（白烧）；所有模型统一 |
|
||
| 发放额度 | = 昨日采集量（≤2M） | 消耗 X → 次日返还 X，用多少补多少，延迟一天到账 |
|
||
| 发放时间 | **不定时** | 次日 0:00 至发放时点存在余额空窗 |
|
||
| 资源包有效期 | **30 天** | 过期额度实打实消失，失去"启动资金" |
|
||
| 消耗顺序 | **FIFO（先消耗获得时间早的包）** | 队列头部 = 最早获得 = 最早过期（效期统一 30 天时两者等价） |
|
||
| 余额耗尽 | **请求不失败，按真实价格扣费** | 全部防护的终极目标：**避免扣费** |
|
||
| 首次开通 | **每模型赠送 2M** | 启动资金的种子（无对应前日采集的免费午餐） |
|
||
|
||
### 1.3 关键账目：启动资金守恒
|
||
|
||
```
|
||
余额_{N+1} = 余额_N − 消耗_N + 返还_{N+1}
|
||
= 余额_N − 消耗_N + 采集_N
|
||
= 余额_N （消耗即采集，≤2M 内全额返还）
|
||
```
|
||
|
||
**推论**：
|
||
- **使用不损失额度**（用多少补多少，仅延迟一天）
|
||
- **过期才损失额度**（额度蒸发 = 启动资金永久减少）
|
||
- 消耗任务的价值 = 防止"启动资金"被 30 天过期侵蚀，把额度滚成新包永续循环
|
||
- 真实用量 ≥ 66.7k/天（= 2M/30 天）时，赠送包被自然消耗，脚本自动闲置；低于此值必须靠脚本在最后 9 天窗口洗掉
|
||
|
||
### 1.4 扣费风险链（限流系统的真正职责）
|
||
|
||
```
|
||
免费额度耗尽（余额 = 0） → 继续请求 → 真实扣费
|
||
```
|
||
|
||
触发扣费的两种路径：
|
||
1. **真实用户单日用量 > 当日可用余额**（含空窗期 0:00–发放时点余额不足）
|
||
2. **消耗任务烧穿余额**（脚本自身引入的扣费，必须结构性杜绝）
|
||
|
||
---
|
||
|
||
## 二、两项目现状与合并可行性
|
||
|
||
### 2.1 当前项目 `volc_limit_sync.py`（1536 行，LiteLLM 回调 + 常驻守护）
|
||
|
||
| 能力 | 实现 |
|
||
|---|---|
|
||
| 火山余额同步 | SigV4 签名调 `ListResourcePackages`（`Status: Effective` 过滤 + `seen_tokens` 防分页死循环），`normalize_volc_name` 归一化，按监控模型聚合 |
|
||
| 动态限额 | Peak-Buffer：`PeakPool = 当日用量 + 余额`；`stable_limit = PeakPool − 15% margin（下限 25w）`；与静态 `HARD_DAILY_LIMITS` 取小得 `effective_limit` |
|
||
| 当日用量计数 | LiteLLM 成功回调 `INCRBY total_tokens` → Redis `daily_usage:{北京日期}:{model}:{api_base_hash}`，北京时间 00:00 滚动，TTL 2 天 |
|
||
| 超限停用/恢复 | `soft_evict_from_router` 重命名软踢；北京时间 7–13 点每 30 分钟、其余 4 小时检查恢复；`startup_audit` 启动预踢 |
|
||
| 模型发现 | 解析 `config.yaml` 中 `volcengine/` 前缀 + `HUOSHAN_BASE_URL` 条目 → `MONITORED_MODEL_PAIRS`；版本号自动推导别名 + `MANUAL_MONITORED_MODEL_ALIASES` 手工覆盖 |
|
||
|
||
### 2.2 目标项目 `huoshan-api-auto_consume/`（420 行 + 4 辅助）
|
||
|
||
| 能力 | 实现 |
|
||
|---|---|
|
||
| 语料 | `/var/log` 系统日志分组 + 脱敏（IP/MAC/邮箱/路径）+ 不足时合成日志 |
|
||
| 计划 | `calculate_plan`：9 天窗口内包 `remaining/ceil(days_left)×1.1`，最后 24h 冲刺全量，多包相加 |
|
||
| 执行 | 直连 Ark API（`ark.cn-beijing.volces.com/api/v3/chat/completions`），速率伪装（15–40s 随机），指数退避，6h 上限，连续失败 5 次跳过 |
|
||
| 配置 | `config.py`：`MONITOR_TARGETS`（id/keyword/alias/extra_params） |
|
||
|
||
### 2.3 可复用资产与冲突点
|
||
|
||
**重叠（合并即消除重复）**：
|
||
- SigV4 签名（`volc_signer.py` ≈ `get_signed_headers`）——**同一账户同一组 AK/SK**
|
||
- `fetch_all_packages`（目标版缺 `seen_tokens` 防循环保护，保留当前版）
|
||
- 资源包→模型映射（当前版 `normalize_volc_name` + 别名体系更健壮，目标版 `keyword` 模糊匹配退役）
|
||
|
||
**关键事实：模型配置天然单一化**。`config.yaml` 的 volcengine 上游模型名（剥掉 `volcengine/` 前缀）就是 Ark endpoint id，与 `MONITOR_TARGETS` 的 id 一一对应（`deepseek-v4-flash` 的 `-ga-260731` vs `-0731` 差异已由 `MANUAL_MONITORED_MODEL_ALIASES` 覆盖）→ **`MONITOR_TARGETS` 退役，消耗任务直接由 config.yaml 驱动**。
|
||
|
||
**冲突点与解法**：
|
||
1. 限额 vs 消耗：消耗请求**必须直连 Ark，绝不改走 LiteLLM**（否则被 `quota_interceptor` 拦下自杀）
|
||
2. 消耗量**必须计入 `daily_usage`**（手动 INCR 同 key）——空窗期防扣费闭环的关键，见 §5.3
|
||
3. 脚本自身不能烧穿余额（结构性防扣费，见 §4.4）
|
||
|
||
---
|
||
|
||
## 三、消耗策略设计
|
||
|
||
### 3.1 为什么不做"烧满 2M"
|
||
|
||
API 请求的 token 消耗不可精确控制（输入按字符估算、输出不确定）。若目标 = 补满 2M：
|
||
- 烧超采集上限的部分不返还 → 白烧
|
||
- 烧到余额 0 仍继续 → **直接扣费**
|
||
- 精确校准需要逐请求调整 → 复杂度不可接受
|
||
|
||
### 3.2 目标：洗掉"即将过期的额度"（过期风险驱动）
|
||
|
||
```
|
||
消耗量 = Σ(该模型 ExpiryTime − now ≤ MONITOR_DAYS 的资源包剩余额度)
|
||
```
|
||
|
||
- 消耗量 ≤ 快过期包剩余 ≤ 当前可用余额 → **结构上不可能烧穿余额**（估算偏差只决定多烧/少烧几笔请求，多烧部分来自非过期包，次日照常返还，无害）
|
||
- FIFO 先烧最早获得 = 最早过期的包 → 脚本烧的恰好是最该洗的包，顺序自动正确
|
||
- 不追求 2M 精确值 → 无校准问题
|
||
|
||
### 3.3 均分逻辑（保留旧 `calculate_plan`，经真实使用验证）
|
||
|
||
```
|
||
对每个 9 天窗口内的包：
|
||
days_left ≤ 1.0 → plan = remaining # 24h 冲刺，全量兜底
|
||
days_left > 1.0 → plan = remaining / ceil(days_left) × 1.1 # 均分 + 10% 提前量
|
||
总 plan = Σ(各包 plan)
|
||
```
|
||
|
||
**为什么均分优于一次性洗光**（在新模型下）：
|
||
1. **最小干扰真实用户**：只在额度即将死亡（进窗口）后才每天接管 1/D，其余留给真实用户 → 免费额度利用率最大化，空窗风险最小
|
||
2. **请求负载分摊**：每天 3–5 次请求（而非 25–40 次），速率伪装自然，风控友好
|
||
3. **余额下降平缓**：23:00 后余额仍保留大部分 → 扣费只发生在余额真正归零时，均分下脚本几乎不可能制造归零
|
||
4. **FIFO 自动一致**：效期统一 30 天 → 获得早 = 过期早 → 队列头部 = 窗口内包，计划与执行不打架（分包明细仅用于定总量）
|
||
|
||
**与日返还循环的契合**：旧脚本本就是"每天跑一次、分 D 天烧完"的设计；自动化后每天重算（余额/天数变化 → div 递减 → 当日份额递增），节奏天然吻合。9 天窗口 + 1.1 系数 + 24h 冲刺：只要每天触发成功，任何进窗口的包都赶在过期前清空。
|
||
|
||
### 3.4 三个约束（旧逻辑缺失，必须补）
|
||
|
||
```
|
||
plan = min(plan, 2M − daily_usage) # 采集上限：超出不返还，白烧
|
||
plan = min(plan, 余额快照 − 本次会话已烧 − BUFFER) # 防扣费：脚本不烧穿余额
|
||
```
|
||
|
||
**执行停止条件（每轮请求后检查，3 条闭环）**：
|
||
```
|
||
daily_usage ≥ 2M → 停（采集上限，再烧不返还）
|
||
余额快照 − 本次已烧 ≤ 0 → 停（防扣费）
|
||
本次已烧 ≥ plan → 停（任务完成）
|
||
```
|
||
|
||
### 3.5 消耗量估算
|
||
|
||
- 单次请求：输入 3–5.5 万字符 ≈ 5–11 万 token（中文 1 字 ≈ 1–2 token）+ 输出 ~1000
|
||
- 极值 2M / 8 万 ≈ 25 次请求 → 15–40s 间隔 ≈ 10–17 分钟，1 小时窗口绰绰有余
|
||
- 均分模式每天 3–5 次请求，更宽松
|
||
|
||
### 3.6 触发调度
|
||
|
||
- 北京时间 **23:00 ± 随机抖动**（防固定时间被风控识别），Redis `consume:last_run:{日期}` 去重，当天未跑过才触发
|
||
- 守护线程（`active_monitor_loop` 已有主循环）检测时点 → spawn daemon 线程执行，不阻塞主循环
|
||
- 23:00 的时点语义：距 00:00 采集结算 1 小时，此时窗口内包状态已定（真实用户当天用量已发生），洗包目标最准
|
||
|
||
---
|
||
|
||
## 四、限额设计（防扣费）——v2 简化逻辑
|
||
|
||
### 4.1 为什么废弃 Peak-Buffer 峰值状态机（存量场景产物）
|
||
|
||
旧逻辑 `stable_limit = PeakPool × 0.85`（PeakPool = usage + balance，首锁/门控重锁/DROP 状态机维护）有两个问题：
|
||
|
||
1. **比例 margin 在 usage 接近 balance 时数学失效**（致命）：
|
||
- `u=0.5b` 时限额允许再烧 `0.775b`，实际余额只剩 `0.5b`（超 55%）
|
||
- `u=0.8b` 时允许再烧 `0.73b`，实际只剩 `0.2b`（超 3.6 倍）→ **烧穿扣费**
|
||
- 存量场景没爆是因为 usage 远小于 balance；新模型"返还 = 消耗"使 usage 天天逼近 balance → 必炸
|
||
2. **峰值状态机防的是旧 bug**（存量包余额只减不增时，滞后虚高把 PeakPool 漂移、限额越算越多 399,836 → 599,511）。新模型 balance 每天真实跳涨（返还），锁峰值会把真实发放当异常压住——**跟随现值即可，状态机删除**
|
||
|
||
### 4.1b 1.7M/1.8M 保守值的来历：post-hoc 滞后时代的遗产
|
||
|
||
旧拦截机制是"请求成功后记账 + 踢模型"（`log_success_event`），**超限请求本身已放行**，存在"滞后一个请求"的漏网量。因此限额必须打折留安全垫：`HARD_DAILY_LIMITS` 默认 1.8M（2M 打 9 折）、`stable_limit` 打 8.5 折（≈1.7M 效应）。
|
||
|
||
**现状已改为请求前闸门**：`async_pre_call_hook` → `_check_request_block`（429 拒绝，不进 router，不触发 retries/fallback）——主拦截不再滞后，"滞后一个请求"的折扣失去存在必要。新公式精确到 2M；BUFFER 30 万保留，但它防的是**余额统计滞后**（实测 20 万内不动，固定量非比例），与请求滞后无关。
|
||
|
||
### 4.2 新公式
|
||
|
||
```
|
||
effective_limit = min(HARD_DAILY_LIMITS, max(0, usage + balance − BUFFER))
|
||
HARD_DAILY_LIMITS → 统一 2M（采集上限；doubao-seed-code-preview-251028 480 万遗留一并改为 2M）
|
||
```
|
||
|
||
**`usage + balance` = 当日初始可用池，天然稳定**：
|
||
- 消耗中：usage ↑ / balance ↓ → 池恒定 → 限额恒定 ✓
|
||
- 返还：balance 跳涨 → 池涨 → 限额次日自动解锁（无需 RECHARGE）✓
|
||
- 过期：balance 跳跌 → 池跌 → 限额收紧（无需 DROP）✓
|
||
- 余额滞后（实测 20 万内不动）：池虚高 ≤ 20 万 → BUFFER 30 万覆盖 ✓
|
||
- 消耗任务 23:00 烧（usage 计入）：池不变 → 滞后窗口内限额偏松 ≤ BUFFER ✓
|
||
- 余额耗尽：池 − 30 万 ≤ 0 → 限额 0 → 全拦，扣费结构性杜绝 ✓
|
||
|
||
**与消耗任务同构**：限额放行条件 = `balance − BUFFER ≥ 0`；消耗任务停止条件 = `余额快照 − 已烧 ≤ 0`——同一把尺子。
|
||
|
||
### 4.3 简化后保留/删除清单
|
||
|
||
| 保留 | 删除（~100 行） |
|
||
|---|---|
|
||
| 同步频率控制（驱动改为 balance，余额越低同步越勤） | `volc:peak_pool:*` 状态机 |
|
||
| `remaining = balance − BUFFER` 写入 | RECHARGE / DROP / 首锁 / 门控重锁分支 |
|
||
| 软踢 / 恢复 / 审计 / pre-block / usage 记账 | `volc:last_seen_pool` / `volc:last_balance` |
|
||
| `get_usage_key` 北京时间滚动 | stable_limit 改直接写 `max(0, usage + balance − BUFFER)` |
|
||
|
||
### 4.4 空窗期防扣费闭环（消耗量计入 daily_usage 的理由）
|
||
|
||
23:00 消耗任务把额度洗掉后余额可能很低，此时真实用户请求必须被拦。拦截依据 = `daily_usage vs effective_limit`：
|
||
|
||
- **若消耗量不计入 daily_usage**：限额看到"真实用户才用 100k，未超限" → 放行 → **扣费**
|
||
- **若计入**：daily_usage ≈ 真实 + 消耗任务 ≈ 2M → 超限拦截 → 空窗期安全
|
||
|
||
同步线程检测 balance 归零 → limit 收紧有 2–60min 滞后；消耗量计入让拦截在**滞后窗口内也有效**，双保险。
|
||
|
||
### 4.3 限额与消耗共用数据、方向相反
|
||
|
||
| 数据 | 限额（拦真实用户） | 消耗任务（洗过期额度） |
|
||
|---|---|---|
|
||
| `daily_usage` | 超限踢出 | 停止条件（≥2M 停） |
|
||
| `remaining`（余额−缓冲） | 限额收紧 | 防烧穿上限 |
|
||
| `stable_limit` | effective_limit 组成 | 不适用（直连旁路） |
|
||
|
||
---
|
||
|
||
## 五、架构与实现
|
||
|
||
### 5.1 代码形态
|
||
|
||
```
|
||
litellm-config/
|
||
├── volc_limit_sync.py # 现状：签名/拉取/归一化/限额/守护线程
|
||
│ # 新增：23:00 调度钩子（检测时点 + spawn 消耗线程 + 去重）
|
||
├── volc_consume.py # 新增：消耗任务（从 auto_consume 移植 + 改造）
|
||
│ ├── load_base_logs / generate_dynamic_payload / _sanitize_line # 原样
|
||
│ ├── calculate_plan # 保留 + 两个 clamp
|
||
│ ├── run_stealthy_consume # 保留（停止条件 + 手动 INCR）
|
||
│ └── consume_once(model) # 新封装：查缺口 → 执行 → 记账
|
||
├── config.yaml # 模型入口不变（消耗任务读同一份监控发现）
|
||
└── .env # 密钥统一走 env（HUOSHAN_API_KEY 即 Ark key）
|
||
```
|
||
|
||
请求直连 Ark（`HUOSHAN_API_KEY`），复用 `MONITORED_MODEL_PAIRS` / `MONITORED_MODEL_ALIASES` / `fetch_all_packages` / 签名。`MONITOR_TARGETS` 与 `config.py` 不再需要。
|
||
|
||
### 5.2 Redis key 一览
|
||
|
||
| key | 读写方 | 说明 |
|
||
|---|---|---|
|
||
| `daily_usage:{日期}:{model}:{hash}` | LiteLLM 回调 INCR + 消耗任务 INCR | 当日用量，TTL 2 天 |
|
||
| `limit:dynamic:volcengine:remaining:{model}` | 守护线程写 | 余额 − BUFFER |
|
||
| `limit:dynamic:volcengine:stable_limit:{model}` | 守护线程写 | 稳定限额 |
|
||
| `volc:peak_pool:{日期}:{model}` | 守护线程 | 当日峰池 |
|
||
| `consume:last_run:{日期}` | 消耗任务 | 当日去重，新增 |
|
||
|
||
### 5.3 消耗任务执行流程
|
||
|
||
```
|
||
23:00 触发（守护线程）
|
||
→ consume:last_run:{今天} 已存在？ → 跳过
|
||
→ 遍历 MONITORED_MODELS（config.yaml 发现的 volcengine 模型）
|
||
→ fetch_all_packages（复用）→ 按模型过滤窗口内包
|
||
→ plan = calculate_plan 结果，应用两个 clamp
|
||
→ plan > 阈值(如 5 万)？
|
||
→ 读 remaining 快照 → spawn 消耗线程
|
||
→ 循环：生成语料 payload → 直连 Ark（速率伪装/退避/6h 上限）
|
||
→ 成功 → INCR daily_usage；每轮检查 3 停止条件
|
||
→ 失败 > 5 次 → 跳过该模型
|
||
→ 写 consume:last_run:{今天}
|
||
```
|
||
|
||
### 5.4 代码资产迁移清单
|
||
|
||
| 资产 | 来源 | 处理 |
|
||
|---|---|---|
|
||
| 签名 / `fetch_all_packages` / 归一化 / 模型发现 | volc_limit_sync | 原样复用 |
|
||
| `calculate_plan`（9 天窗口/均分×1.1/冲刺/相加） | auto_consume | 保留，加 2 个 clamp |
|
||
| 语料生成/脱敏/合成 | auto_consume | 原样移植 |
|
||
| 速率伪装/退避/失败上限/6h 上限 | auto_consume | 原样移植 |
|
||
| `_record_usage` 的 key 计算（`get_usage_key`） | volc_limit_sync | 消耗任务复用做 INCR |
|
||
| 调度钩子 | 新增 | 守护线程 23:00 检测 + 去重 |
|
||
|
||
---
|
||
|
||
## 六、风险与边界（已确认/已知）
|
||
|
||
| 项 | 结论 |
|
||
|---|---|
|
||
| 空窗期（0:00–次日发放不定时） | **用户确认可接受**；均分策略使空窗概率最小化（余额平缓下降） |
|
||
| 烧满 2M 的精确性 | 放弃该策略，改为过期风险驱动，结构性规避 |
|
||
| 物理上限 | 窗口内快过期额度 > 2M 时每天最多洗 2M，极少数过期蒸发不可避（返还上限硬约束） |
|
||
| 触发连续性 | 依赖每天 23:00 成功；连续失败 ~8 天耗尽窗口缓冲（冲刺兜底），守护线程常驻风险低 |
|
||
| 风控 | 23:00 ± 抖动 + 15–40s 随机间隔 + 每天 3–5 次请求，接近真实行为 |
|
||
| 容器语料 | LiteLLM 容器内无 `/var/log` 系统日志 → 合成语料兜底（5000 行够用） |
|
||
| 消耗任务自身扣费 | 结构性杜绝：plan ≤ 余额快照 − 缓冲，且每轮检查余额 |
|
||
|
||
---
|
||
|
||
## 七、待确认事项
|
||
|
||
1. `MONITOR_DAYS` 沿用 9 天（推荐：每天触发 + 冲刺兜底下足够，且与旧逻辑一致）
|
||
2. 实现落点：拆 `volc_consume.py` 模块（推荐，单文件将超 2000 行）还是严格并入 `volc_limit_sync.py`
|
||
3. 消耗触发阈值（plan 小于多少跳过）：建议 5 万 token，避免无谓请求
|
||
4. 消耗任务与真实用户的额度优先级：均分策略已隐含"真实用户优先"，无需额外开关
|
||
|
||
---
|
||
|
||
## 八、实施步骤（确认后执行）
|
||
|
||
1. 移植 `auto_consume.py` 的语料/执行逻辑到 `volc_consume.py`，请求层改为直连 Ark（env key）
|
||
2. `calculate_plan` 加两个 clamp + 停止条件；执行循环加 `daily_usage` INCR 与余额检查
|
||
3. `volc_limit_sync.py` 守护线程加 23:00 调度钩子 + `consume:last_run` 去重
|
||
4. `HARD_DAILY_LIMITS` 统一为 2M；`MONITOR_TARGETS`/`config.py` 退役
|
||
5. 用 `test_connection.py` 等价方式验证 Ark 连通 → 手动触发一次消耗任务（dry-run 模式验证 plan 计算与 clamp）→ 观察 Redis key 变化
|
||
6. 全量回归：守护线程限额逻辑不受影响（消耗线程独立 daemon）
|