cost-verification-auditor

成本验证审计工具

验证 Token 成本估算与 Claude API 实际用量的偏差是否在 ±20% 以内。

适用场景

✅ 适用于：

• 实现后验证 Token 估算系统
• 部署前检查成本估算准确性
• 调试意外的 API 账单
• 定期检测估算偏差

❌ 不适用于：

• 查询模型定价（请参阅定价文档）
• 预算规划或预测
• 成本优化策略
• 按价格比较模型

核心审计流程

决策树

Has estimator? ──No──→ Build estimator first (see Calibration Guidelines)
      │
     Yes
      ↓
Define 3+ test cases (simple/medium/complex)
      ↓
Estimate BEFORE execution (no peeking!)
      ↓
Execute against real API
      ↓
Calculate variance: (actual - estimated) / estimated
      ↓
Variance ≤ ±20%? ──Yes──→ PASS ✓
      │
     No
      ↓
Apply fixes from Anti-Patterns section
      ↓
Re-run verification

偏差公式

const inputVariance = (actual.inputTokens - estimate.inputTokens) / estimate.inputTokens;
const outputVariance = (actual.outputTokens - estimate.outputTokens) / estimate.outputTokens;
const costVariance = (actual.totalCost - estimate.totalCost) / estimate.totalCost;

// PASS if both input AND output within ±20%
const passed = Math.abs(inputVariance) <= 0.20 && Math.abs(outputVariance) <= 0.20;

常见反模式

反模式：500 Token 开销迷思

初学者的想法：“Claude Code 会增加约 500 个 Token 的开销，所以每次估算都加上这个数。”

实际情况：直接 API 调用的开销约为 10 个 Token。500+ Token 的开销仅在使用 Claude Code 的完整上下文（系统提示词、工具、对话历史）时出现。

时间线：

• 2025 年以前：许多教程使用 500+ Token 估算
• 2025 年及以后：直接 API 调用的开销极小（约 10 个 Token）

建议使用以下估算：

上下文	开销
直接 API 调用	约 10 个 Token
包含系统提示词	50-200 个 Token
包含工具/函数	100-500 个 Token
Claude Code 完整上下文	500-2000 个 Token

检测方法：持续高估 40-90% = 开销设得太高。

---

反模式：执着于单个节点的准确性

初学者的想法：“每个节点都必须在 ±20% 以内，否则估算器就有问题。”

实际情况：大模型的输出长度具有非确定性。单节点输出偏差 30-50% 属于正常情况。重要的是总体成本准确性。

建议采用以下做法：

• 关注整个 DAG 的成本偏差（应在 ±20% 以内）
• 接受单节点输出偏差最高达 ±40%
• 使用约束性提示词（例如“恰好列出 3 项”）来减少偏差

检测方法：输入估算准确，输出变化很大 = 大模型的正常行为。

---

反模式：估算前先查看结果

初学者的想法：“我先运行 API 调用，看看会得到多少 Token，然后再构建估算器。”

实际情况：这样会产生过度拟合的估算结果，遇到新提示词时就会失效。必须在执行前进行估算。

正确做法：

1. 根据提示词长度和启发式规则进行估算
2. 执行 API 调用
3. 比较偏差
4. 必要时调整启发式规则

校准指南

输入 Token 估算

// Calibrated 2026-01-30
const inputTokens = Math.ceil(prompt.length / CHARS_PER_TOKEN) + OVERHEAD;

文本类型	CHARS_PER_TOKEN	备注
英文散文	4.0	最稳定
代码	3.0-3.5	符号的 Token 切分方式不同
混合文本	3.5	较为均衡（推荐默认值）
JSON/结构化文本	3.0	标点较多

输出 Token 估算

提示词约束	倍数	备注
“恰好列出 N 项”	输入的 0.8 倍	约束性很强
“简要总结”	输入的 1.0 倍	约束程度适中
“详细说明”	输入的 2-3 倍	内容较多
无约束	输入的 1.5 倍	变化较大

始终注意：任何有意义的响应至少估算 100 个输出 Token。

模型行为

模型	输出倾向
Claude Opus	更长、更详细
Claude Sonnet	较为均衡
Claude Haiku	简洁、高效

快速修正

症状	原因	修正方法
高估 40% 以上	开销过高	从 500 降至 10
低估输入	每 Token 字符数设得过高	从 4.0 降至 3.5
输出变化很大	大模型的非确定性	使用约束性提示词
总成本准确，但单节点偏差大	正常的汇总现象	接受这一点，关注总量

验证清单

• 至少 3 个测试用例（简单、中等、复杂）
• 在 API 调用前运行估算
• 偏差公式：(actual - estimated) / estimated
• 目标：输入和输出的偏差均在 ±20% 以内
• 报告包含可执行的建议

参考资料

详细的校准表和历史数据请参阅 /references/calibration-data.md。