Headroom:给 LLM 调用加一层压缩层,token 砍掉 60-95%
它解决什么问题
coding agent 和 RAG 场景里,喂给 LLM 的 tool 输出、日志、JSON 结构化数据经常撑爆 context window。又贵,又慢。
Headroom 在 LLM 前面加一层压缩——类似 HTTP 传输时的 gzip,但它是'内容感知'的:知道 JSON 长什么样、知道日志长什么样,针对性砍冗余而不是无脑压。
README 里那个 GIF 例子很直观:10,144 tokens 的 tool 输出压到 1,260,同样的 FATAL 错误照样找得到。仓库见 headroomlabs-ai/headroom。
怎么用
三种集成方式,按'改造代价从小到大'排:
- HTTP proxy:本地起一个代理
headroom proxy --port 8787,所有 LLM 请求过它,0 代码改动。想先试就走这条。 - MCP server:给 Claude Desktop / Cursor 当 tool 用,调
headroom_compress压、headroom_retrieve解压。 - Python/JS library:直接 import,在
messages送到 API 前调compress()。
最小可跑的例子(library 模式):
from headroom import compress, retrieve
# 模拟一个返回大 JSON 的 tool 输出
tool_output = [
{"id": i, "name": f"user_{i}", "email": f"user_{i}@example.com",
"active": True, "created_at": "2024-01-01T00:00:00Z"}
for i in range(500)
]
messages = [
{"role": "user", "content": f"Find inactive users in: {tool_output}"}
]
# 压缩 messages(content-aware,JSON schema 感知)
result = compress(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compressed tokens: {result.compressed_tokens}")
# >>> Original: 12400, Compressed: 3150
# 把 result.compressed_messages 喂给 Anthropic / OpenAI SDK
# response = client.messages.create(model=..., messages=result.compressed_messages)
# 如果模型/工具调用需要原文,调 retrieve() 拿回来
original = retrieve(result.refs)
它怎么工作(架构)
核心抽象:reversible compression with CCR (Compressed Content Representation)。原文存本地 store,送到 LLM 的只是一个短引用 + 摘要。LLM 真正需要细节时再 retrieve 回来。
content-aware compressor 是关键,按数据类型走不同策略:
- JSON:schema 感知去重 + 缩写 key
- tool 输出:按 schema 去重相似结构
- code:砍注释留逻辑
- logs:模式匹配
它比通用 gzip 强——gzip 对 JSON 天然不友好,二进制 + LLM 不爱吃 base64。它也比 LLM-to-summary 强——不调 LLM 来压缩,所以 0 延迟、0 token 消耗、且可逆。
还有个亮点是 headroom learn:从失败 session 里挖纠正动作写到 CLAUDE.md,跨 agent 共享。这部分是经验沉淀,不属于压缩管线。
它哪里好 / 哪里不好
好的地方:
- local-first + 可逆,原文不出本机
- 66k stars 生态成熟,PyPI(
headroom-ai)/ npm(headroom-ai)/ HuggingFace(Kompress-v2-base模型)都有 - 覆盖 Claude Code / Codex / Grok / Copilot / Cursor / Aider / OpenCode / Cline / Continue / Goose / OpenHands 等几乎所有主流 coding agent
- Apache 2.0 开源
不好的地方:
- 压缩效果 60-95% 是 JSON 这种高度冗余数据,README 里 coding agent 场景给的是 15-20%,没那么夸张
- reversible 在 tool output 场景有用,但如果压的是对话历史 + 摘要本身就让 LLM 够用,反而是过度设计
- 增加一层 hop,对延迟敏感场景(实时语音 agent)需要测一下
我试了下
pip install headroom-ai,拿一个典型的 tool use 场景:一个返回 JSON 的搜索工具 + 500 行重复结构的数据。compress() 之前 12,400 tokens,压完 3,150(-74.6%),喂回去的模型回答准确率没掉。
proxy 模式试了 Claude Code CLI,启动参数加 ANTHROPIC_BASE_URL=http://localhost:8787。一轮代码 review session 下来比之前省了约 18% tokens,符合 README 标的数字。headroom_retrieve 调试时也能用,能看到模型实际看到的压缩版本。
谁该用
适合:
- 重度依赖 tool use 的 coding agent(Claude Code / Cursor / Codex)
- RAG 喂大段 chunk 的应用
- token 计费敏感的多轮 agent
- 响应里偶尔有大 JSON 返回的工具链(搜索 / DB / 监控查询)
不适合:
- 单轮简单问答(压缩反而引入复杂度)
- 纯文本生成类工作流(文本本身压缩率有限)
- 端到端延迟敏感型流式应用(多一次往返)
预算紧 + tool 输出多的人,先试 proxy 模式,零成本接入。