Headroom开源项目：LLM Token压缩95%准确率不变，22k star

ivye
免费干货
3小时前
7热度
0评论

最近GitHub上有个项目彻底炸了：Headroom，上线没多久就冲到22.2k star。

它干的事很简单粗暴：把发给LLM的Token直接砍掉60-95%，回答质量几乎不变。

这不是PPT吹牛，是实测数据。代码搜索场景，17765 Token压到1408，省了92%。SRE故障排查，65694 Token压到5118，也是92%。准确率呢？GSM8K数学推理测试，0.870对0.870，分毫不差。

Headroom Token节省实测数据——代码搜索省92%、SRE排查省92%、GitHub Issue分类省73%、代码库探索省47%（来源：GitHub项目README官方截图）

Headroom 到底是个啥？

说白了，它是一个开源的LLM Token压缩层。解决的就是一个痛点：AI Agent调用LLM时，上下文里塞了大量冗余信息。

举个例子。你让AI助手搜代码库，它返回100个文件片段，然后全塞给LLM。但里面大量是重复模式、无关注释、冗余JSON结构——LLM根本不需要看完整版。

Headroom做的事：发出去之前，智能压缩。保留核心语义，体积缩小十几倍。

三层架构，层层压缩

Headroom的底层分三层，各有分工：

第一层：ContentRouter（内容路由器）——检测内容类型（JSON、代码、纯文本），自动选最佳压缩器。

第二层：智能压缩器——SmartCrusher压JSON，CodeCompressor做AST感知代码压缩（理解语法树），Kompress-base走通用文本压缩（基于HuggingFace模型）。

第三层：CCR可逆压缩——这是最核心的创新。原始数据缓存到本地，LLM收到压缩版，需要更多细节时调用 headroom_retrieve 按需检索完整内容。既省Token，又不丢信息。老实讲，这个设计确实聪明。

三种接入方式，从零代码到全定制

Wrap模式：一条命令搞定。headroom wrap claude，自动启动本地代理改配置，Claude Code、Codex、Cursor、Aider都能用。之后所有请求自动走压缩，零代码改动。

Proxy模式：启动代理服务 headroom proxy --port 8787，代码里base URL改成 localhost:8787/v1 即可。所有支持OpenAI SDK的语言都能接。

Library模式：直接调用 compress() 函数，精确控制压缩行为。Python和TypeScript都支持。

实战数据：代码搜索省92%

10万行代码项目找功能实现，这个场景最有说服力：

不用Headroom：Agent搜返回100个文件，全发给LLM，消耗17,765 Token
用Headroom：压缩后仅1,408 Token，节省92%

SRE故障排查更夸张。10,000行日志调试场景，原始65,694 Token压到5,118，也是92%。

其他数据：GitHub Issue分类省73%（54,174→14,761），代码库探索省47%（78,502→41,254）。不同场景压缩比不同，但几乎没有低于40%的。

跨Agent共享记忆，真香

这个功能让团队开发者直呼真香。

多个AI助手可以共享压缩后的缓存。Claude Code扫过的代码库索引，Codex和Cursor直接复用，不用重新扫描。加个 --memory 参数就行。

先用Claude Code审查代码，再用Codex生成测试，后用Cursor重构——后两个Agent直接用第一个的缓存索引，省掉40-60%的初始扫描Token。

每天跟多个AI工具打交道的开发者，这个功能省的不只是钱，还有时间。

CCR可逆压缩：核心创新

很多人会担心：压缩了会不会丢信息？

Headroom的CCR（Compress-Cache-Retrieve）就是解决这个问题的。流程很简单：

压缩内容，发压缩版给LLM
LLM发现需要更多细节，调用 headroom_retrieve(chunk_id)
从本地缓存返回原始数据
LLM拿到完整信息，继续推理

原始数据永远不会丢，按需调取。需要的时候LLM能拿到完整上下文，没有信息损失。你猜怎么着？这设计跟计算机体系结构里的缓存层次简直一个思路。

安装和使用

一行命令：

pip install "headroom-ai[all]"

然后 headroom wrap claude 开跑。想看压缩效果跑 headroom perf，显示当前环境的压缩数据和性能指标。

完整版需要Python 3.10+，压缩模型首次运行自动下载（约500MB）。不想装ML模型也行：headroom-ai[proxy] 仅代理模式，headroom-ai[mcp] 仅MCP服务器。

Headroom GitHub Star历史趋势——22.2k star迅速引爆开发者社区（来源：Star History 图表）

适合谁装？

每月LLM API支出超过100美元的开发者或团队，Headroom几乎是必装的。60-95%的成本降幅，同样预算能多调用2到10倍的Token。

而且完全本地运行，压缩、缓存、存储都在自己机器上，数据不外传。

本地压缩10-50毫秒搞定，相比网络请求的几百毫秒到几秒几乎忽略不计。Token发少了，整体响应反而更快。

写在最后

Headroom解决的是一个被忽视但很痛的问题——AI Agent的Token浪费。过去大家比模型参数、比Benchmark，很少有人管发给模型的上下文到底有多少冗余。

Headroom用一组漂亮数据证明：上下文里大部分内容可以压缩，压缩后模型回答质量几乎不受影响。

CCR可逆压缩的设计尤其巧妙——先发摘要，按需调取完整版。这个思路跟计算机体系结构里的缓存层次很像，既省带宽又保留信息完整性。

对于重度使用AI编程助手的开发者来说，这可能是2026年最值得装的开源工具之一。代码量少、接入简单、效果肉眼可见。

项目地址：https://github.com/chopratejas/headroom

Headroom支持哪些AI编程工具？

目前支持Claude Code、Codex、Cursor、Aider等主流AI编程助手，通过Wrap模式一条命令接入，也支持任意支持OpenAI SDK的语言通过Proxy模式接入。

Headroom压缩后LLM回答质量会下降吗？

实测数据显示几乎不变。GSM8K数学推理测试中，压缩前后准确率均为0.870。CCR可逆压缩机制确保LLM在需要时可以检索完整原始数据，不会丢失关键信息。

Headroom安装需要什么前置条件？

需要Python 3.10+环境。完整版安装约500MB压缩模型（首次运行自动下载）。如果不需要ML模型，可以按需安装子模块：仅代理模式或仅MCP服务器，体积更小。