fix: 限额改 v4 冻结快照,余额红线防扣费

v2 的 stable_limit = usage + balance - BUFFER 依赖余额 API 随消耗实时递减,
实测滞后(08-12 快照 1,558,307 在 usage 涨 45 万期间不动)导致池膨胀、限额
虚高,放行到扣费区(当日超余额 13.8 万已扣费)。
扣费口径(用户确认):是否扣费只取决于当下免费额度,超出即扣费,采集量只
决定明日发放。v4:stable_limit = balance - BUFFER 冻结快照,本地 usage 实时
撞线即拦,等价于本地实时扣减余额;effective = min(2M 配额, stable_limit)。
新增 docs/volc-quota-notes.md 额度机制速查;merge-auto-consume.md 补 §4.5。
This commit is contained in:
vibe-code
2026-08-12 06:58:03 +00:00
parent c6c122426a
commit dd349b64cf
9 changed files with 249 additions and 12 deletions
+336
View File
@@ -0,0 +1,336 @@
# 火山免费额度自动消耗: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 简化逻辑(v4 修订见 §4.5,2026-08-12 已实施)
### 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 新公式
> ⚠️ 2026-08-12 修订:本节 v2 公式「池恒定」假设(usage ↑ / balance ↓ 同步)失效,
> 已由 v4 取代(见 §4.5)。保留原文作历史论证。
```
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 → 全拦,扣费结构性杜绝 ✓
**fallback(stable_limit 缺失窗口)**:免费模型余额常态 < 2M(昨日采多少返多少),若 dynamic 缺失(首次同步前/新增模型/TTL 过期)时裸奔到静态 2M,余额不足的模型会被烧穿扣费。故 fallback 用保守值 `FALLBACK_LIMIT = min(static, 90万)`(env 可调),宁可短时收紧不可裸奔。
**与消耗任务同构**:限额放行条件 = `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.5 v4 修订(2026-08-12 已实施):冻结快照,余额红线
**v2 失效点**:`usage + balance = 当日初始可用池,消耗中恒定` 依赖余额 API 随消耗**实时递减**。实测余额 API 滞后(2026-08-12:快照 1,558,307 在 usage 1.24M→1.70M 期间纹丝不动,滞后上限未知),balance 不随消耗递减 → 池随 usage 膨胀(2.80M→3.26M)→「余额耗尽 → 限额 0」防线失效 → 放行到扣费区(当日超余额 13.8 万已扣费)。
**扣费口径(用户确认,2026-08-12)**:是否扣费只取决于**当下免费额度(余额)**;超出免费额度的请求都会被扣费;采集量只决定明日发放,与今日是否扣费无关。→ 余额必须是闸门红线,且不能依赖 API 实时性。
**v4 公式**:
```
stable_limit = max(0, balance − BUFFER) # 冻结快照,同步时算一次,不随 usage 膨胀
effective_limit = min(HARD_DAILY_LIMITS, stable_limit) # 2M 防白烧;余额红线防扣费
```
- 以最近同步快照的余额为「当日免费池上限」,本地 usage 实时累计撞线即拦 → **等价于本地实时扣减余额**,不依赖 API 刷新
- 返还:balance 跳涨 → 下次同步红线上升 → 自动解锁 ✓;过期/异常:balance 跳跌 → 红线收紧 ✓
- 余额 < BUFFER → 限额 0 → 全拦,扣费结构性杜绝 ✓
- 与消耗任务「余额快照 − 已烧 ≤ 0 停」同一把尺子(不变量:放行条件 = `balance − BUFFER ≥ 0`)
- 与昨日采集量**无关**:昨日 10K、余额 2M → 今日可用 1.7M(存量余额守恒,v3「昨日锚」因把单日流量当存量已被否决,见 volc-quota-notes.md §7.2)
**BUFFER 语义变化**:v2 里防「余额统计滞后 ≤ 20 万」;v4 里防「快照滞后窗口内(30min 常规同步 + burst 触发)的消耗 + 返还/过期抖动」。默认 30 万(env 可调),滞后上限未知时建议调大(如 50 万)。
### 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}` | 守护线程写 | v4 冻结快照:余额 − BUFFER |
| `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 ≤ 余额快照 − 缓冲,且每轮检查余额 |
| 余额 API 滞后(v2 池膨胀根因) | v4 冻结快照:balance − BUFFER 定上限,本地 usage 实时撞线,滞后窗口由 BUFFER 覆盖 |
---
## 七、待确认事项
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)