iomgaa
9a8f5cea5a
Records the approved option, the four rejected alternatives with their reasons, the intentionally dropped CHS migration item, and the two defects the independent review caught. Links the entry to m1-core-design as a refinement, since that milestone is where est_tokens froze with both jobs attached.
3.8 KiB
3.8 KiB
type, node_id, title, date
| type | node_id | title | date |
|---|---|---|---|
| design | design:est-tokens-decoupling | est_tokens 解耦: 拆分限流预扣与遥测用量兜底(issue #2) | 2026-07-30 |
est_tokens 解耦: 拆分限流预扣与遥测用量兜底(issue #2)
全文见 2026-07-30-est-tokens-decoupling-design.md。缘起是 Gitea issue #2(下游 CHSAnalyzer 提出)。
- 缘起:
SourceConfig.est_tokens被派了两份对"保守"定义相反的差事——TPM 入场预扣(多押金 = 安全)与 usage 帧缺失时的遥测用量兜底(计费没有安全方向)。CHSconfig.py:55自己就把它定义为"须 ≥ 最坏情形 token"的上界,而库把遥测拆prompt/completion两列后又将整个估值塞进单价更贵的completion(openai_compat.py:146),形成双重系统性高估:实测算例 26 倍。 - 第二个症状:
types.py:125的tpm > 0 ⇒ est_tokens > 0把供应商配额(可从配额页抄)与库的实现细节(无人能正确取值)绑死,下游删掉猜测项后tpm只能填 0,被迫在自己配置模型里加校验绕开。 - 方案(两个决策点,人类审批): ① usage 不可得时记
0/0+usage_source新增unavailable+ cost 记 NULL;②est_tokens未填时由库派生tpm // 60,字段降为可选调优覆盖(不删不改名,迁移兼容)。 - 值域三态各有生产者:
measured(正常)、estimated(打捞路径——收到 usage 帧但流被截断,数字真实而可信度降级)、unavailable(用量不可得)。故estimated不是空值域,历史行亦读兼容。 - 被否决 · usage 兜底记 0 但沿用
estimated: cost 会算出0.0,"免费"与"未知"在数据上不可区分,账目缺口无法量化。 - 被否决 · 保留 est 兜底只修 prompt/completion 分配比例: 比例是又一个没有正确取值的魔数,且未触及"拿上界当实测"的根因,仍高估约 9 倍。
- 被否决 · 固定默认常量(如 1000): 与配额规模无关,在途上限随规模乱飘(
tpm=6000只剩 6 个在途、tpm=600000放行 600 个)。派生值尺度无关且语义可文档化("一次调用约占一秒钟的配额份额")。 - 被否决 · issue 原建议的遥测 p90 自估:
TelemetryRecorder是纯只写端口,自估需新增读接口并强制所有后端(含none)实现,公共 API 扩张远大于它要省掉的一个可选字段,且无实测证据表明派生默认值不够用。注: 初稿曾以"把两条方向相反的降级铁律焊在一起"为主论据,经独立审查撤回——p90 可在遥测读失败时回退纯派生值,限流侧仍能 fail-closed。 - 被否决 · 派生逻辑取全局与单源 tpm 的较紧者: 需改三处
QuotaGate装配,且它修的是一个既有缺口(单源tpm=0而全局tpm>0时预扣为 0),属任务外,建议另开 issue。 - 有意放弃的迁移保留项:
migrations/chsanalyzer.md:151曾把"usage 缺失按 est 估算"列为保留(理由"保守计量")。本设计推翻:CHS 只记单个total_tokens不存在分配问题,而"保守"在计费语境只有错误一个方向。反静默的原始意图仍保留——被放弃的只是"编一个数字"这个手段。 - 独立审查(两轮)抓出的两处实质缺陷: ① 只改失败侧结算不够,
retry.py:338/embedding.py:271的成功侧取自同一返回值,改前actual恰等于预扣量使delta==0,不同改则成功调用押金被整笔退回,对"从不回 usage 帧的网关源"构成系统性 TPM 失效;② OCR 行原判为"假陈述"是错的——types.py:51与ocr.py:9明示 OCR 的 0 token 属事实,且改标unavailable会灌水本方案赖以成立的缺口度量,已剔出。 - 待办: 经
writing-plans出实施计划;发版须同步 CHANGELOG 与 wiki(缺口查询口径须带AND cache_hit = false),并回帖 issue #2。