Headroom美元节省计算原理：LiteLLM定价如何把Token节省换算成真金白银-育师

Headroom美元节省计算原理：LiteLLM定价如何把Token节省换算成真金白银

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom

Headroom 是一个 LLM 上下文压缩工具，可在工具输出、日志、文件和 RAG 分块进入大模型之前先行压缩，为编码 Agent 节省约 20% Token，对 JSON 类内容可节省 60–95%。很多人只看到"省了多少 Token"，却不知道 Headroom 仪表盘上那个亮眼的Cost Saved（节省美元）是怎么算出来的。这篇文章带你拆解 Headroom 的美元节省计算原理：它如何用 LiteLLM 的社区定价数据库，把每一次压缩节省的 Token 数，精准换算成真金白银。

一、为什么"省Token"必须换算成"省美元"

对 LLM API 用户来说，账单不是按字符计费，而是按Token × 单价计费。不同模型的输入、输出、缓存读取单价差异巨大：

同一个 Token，输出价格通常是输入价格的 4–5 倍；
缓存读取（Cache Read）通常只有标准输入价的 10%–50%；
部分模型（如 Anthropic Sonnet 4/4.5 系列）超过 200K 长上下文阈值后，整个请求会被重新计价。

所以"省了 10 万个 Token"到底值多少钱，取决于三个变量：哪个模型、哪类 Token（输入/输出/缓存）、是否触发长上下文重定价。Headroom 的美元节省计算正是围绕这三点展开的。

二、核心公式：节省Token数 × LiteLLM 每百万Token单价

Headroom 不自带硬编码价格表，而是直接复用LiteLLM 的社区维护模型成本数据库（覆盖 100+ 模型），相关实现在 headroom/pricing/litellm_pricing.py：

美元节省 = 节省的Token数 × 该模型每Token价格（USD）

核心换算函数estimate_cost()与estimate_cost_from_tokens()位于 headroom/pricing/litellm_pricing.py，后者专门处理两类"复杂账单"：

场景	LiteLLM 数据库中的价格字段
标准输入	`input_cost_per_token`
标准输出	`output_cost_per_token`
缓存读取	`cache_read_input_token_cost`
缓存写入（5分钟）	`cache_creation_input_token_cost`

💡 LiteLLM 内部以"每 Token"为存储单位，Headroom 在读取时统一放大 100 万倍换算为"每百万 Token 美元价"，并做 6 位小数舍入，避免浮点噪声（例如 $0.4/M 被存成 0.39999999999999997）。

三、Headroom 的四类节省：每一层单独计价

压缩代理在处理每个请求时，会区分四种性质不同的节省，并分别计价。这四条计价函数集中在 headroom/proxy/savings_tracker.py：

压缩节省（compression）：工具输出、日志等输入 Token 被压缩后省下的部分，按输入单价计费 → _estimate_compression_savings_usd
工具Schema节省（tool_schema）：工具定义压缩省下的 Token，同样按输入单价 → 复用压缩计价
输出塑形节省（output_shaping）：限制/优化模型生成内容省下的输出 Token，按更贵的输出单价计费 → _estimate_output_savings_usd
缓存节省（provider_cache）：命中前缀缓存省下的部分，按折扣差值计费（见下一节）→ _estimate_cache_savings_usd

统一入口是 estimate_request_savings_usd，它把四个数值汇总成一个字典，供仪表盘与遥测消费——这也是"省了多少美元"能被逐层归因的关键。

四、缓存折扣：不是省全部，而是省"差价"

这是最容易算错的一步。缓存读取并非免费，而是按折扣价计费，所以 Headroom 计算的缓存节省是标准输入价与缓存读取价之差：

每Token缓存节省 = input_cost_per_token − cache_read_input_token_cost 缓存节省总额 = 命中缓存的Token数 × 每Token缓存节省

例如某模型输入价 $3.0/M、缓存读取价 $0.3/M，每命中 1M Token 就省 $2.7。若差价 ≤ 0（个别模型缓存反而更贵），则记 $0，绝不会出现"负节省"。

在会话级成本追踪中，headroom/proxy/cost.py 还维护了一张各供应商缓存经济学系数表（如 Anthropic 缓存读取按输入价 10%、写入按 125% 计），用于更贴近真实账单的会话成本估算。

五、边界情况：LiteLLM 不认识这个模型怎么办

真实部署中，网关（Kong、LiteLLM Gateway 等）经常传入别名模型名（如claude-opus），LiteLLM 数据库里查不到，节省就会读成 $0。Headroom 用三道防线兜底：

模型名解析：resolve_litellm_model 会尝试加bedrock/、vertex_ai/、deepseek/等前缀反复查询，结果按模型名缓存，避免阻塞事件循环；
别名映射：通过HEADROOM_MODEL_ALIAS_MAP环境变量提供自定义名称映射（JSON 格式），fail-soft 设计，配置无效时行为与默认完全一致；
兜底混合价：实在查不到时，savings_tracker.py 使用保守混合单价——输入 $3.0/M、输出 $15.0/M——保证节省数字不为零，同时日志给出一次性警告。

还有一个细节值得注意：代码刻意区分"查不到价格"（走兜底）和"价格为 0.0"（免费模型，记 $0）。早期版本用if not x判断会把真实免费模型误判为"无价格"，凭空算出不存在的节省，这个 bug 的修复记录就写在 savings_tracker.py 的注释里。

此外，headroom/pricing/registry.py 提供了一个带价格时效性检查的注册表PricingRegistry：价格数据超过 30 天未核验即标记is_stale，并生成警告提示你去官方价格页核对——因为供应商调价后，过期的价格表会让"美元节省"失真。

六、结果去哪看：持久化与仪表盘

每一笔请求计价后，SavingsTracker 会把以下字段累加并持久化到本地 JSON（默认.headroom/proxy_savings.json），重启代理也不丢失：

compression_savings_usd：压缩节省美元
cache_savings_usd：缓存节省美元
output_savings_usd：输出塑形节省美元
total_input_cost_usd：输入实际花费

历史数据支持小时/天/周/月分桶聚合，并按供应商、项目、模型多维归因。最终所有数字汇聚到仪表盘上——"Cost Saved" 就是这套计价管线输出的社区级汇总：

💰 如上图所示，社区累计节省 59B Token、约 $235.9K 美元——每一个数字背后都是"Token 数 × LiteLLM 单价"这条公式在成千上万次请求上的累加。

七、小结：三条要点记住换算逻辑

要点	说明
📌 计价来源	复用 LiteLLM 社区数据库，100+ 模型实时价，非硬编码
📌 分层计价	压缩按输入价、输出塑形按输出价、缓存按折扣差值，四层独立归因
📌 稳健兜底	别名解析 + 混合兜底价 + 免费模型特判，保证数字可信不为零

想深入了解实现细节，建议按以下路径阅读源码：