工具

Headroom:给 LLM 调用加一层压缩层,token 砍掉 60-95%

66k stars 的 token 压缩中间件,支持 library / proxy / MCP 三种集成方式,JSON 数据能压掉 60-95% tokens

字号

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。

怎么用

三种集成方式,按'改造代价从小到大'排:

  1. HTTP proxy:本地起一个代理 headroom proxy --port 8787,所有 LLM 请求过它,0 代码改动。想先试就走这条。
  2. MCP server:给 Claude Desktop / Cursor 当 tool 用,调 headroom_compress 压、headroom_retrieve 解压。
  3. 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 模式,零成本接入。


参考:Headroom GitHub 仓库

来源: https://github.com/headroomlabs-ai/headroom