10,144 token 压到 1,260 还能找到同一个 Bug——Headroom 的 6 种压缩引擎拆解

qcx23

297人浏览 · 2026-06-22 22:57:10

qcx23 · 2026-06-22 22:57:10 发布

项目：Headroom
GitHub：chopratejas/headroom（43.2k stars）
许可证：Apache-2.0
核心：60-95% Token 压缩 + CCR 可逆缓存 + MCP 集成

📌 为什么你现在应该关注这个项目

Agent 的上下文窗口再大，也有填满的时候。GLM-5.2 的 1M 上下文听起来很多，但一个处理大型代码库的 Agent，几十轮工具调用就能产出几万 token 的中间结果。

Headroom 解决的问题不是"上下文不够大"，而是"上下文里太多水"——在数据到达 LLM 之前做压缩，60-95% 的 token 被削减，但 LLM 仍然能找到同样的答案。

三个关键数字

指标	数据
Token 削减率	60-95%
准确率保持	97%+（GSM8K/TruthfulQA/SQuAD/BFCL）
官方演示	10,144 → 1,260 token（87.6% 削减，LLM 仍找到同一个 FATAL 错误）

六种压缩引擎详解

Headroom 的核心架构是 ContentRouter（内容路由器）——自动检测内容类型，分派到对应的压缩引擎。

引擎一：SmartCrusher — JSON 通用压缩器

目标：JSON 数据（字典、数组、嵌套对象、混合类型）

典型场景：压缩工具返回值、API 响应

为什么需要专门处理 JSON：

JSON 的 key 经常占 50%+ 的 token（"user_account_balance" 这种长 key）
嵌套结构有大量冗余的 {}[]:, 符号
LLM 不需要看到完整 key 名就能理解语义

压缩策略：保留语义结构，压缩冗余标记和冗长 key

引擎二：CodeCompressor — AST 感知代码压缩器

目标：源代码

支持语言：Python, JavaScript, Go, Rust, Java, C++

为什么需要 AST 感知：

行级压缩会破坏代码结构（把 if/else 压成一行就没法读了）
AST 感知可以保留语义结构，同时去除注释、空白、冗余导入
函数签名保留，函数体按重要性裁剪

核心思想：代码的语义在 AST 节点里，不在字符里。压缩 AST 而非压缩文本。

引擎三：Kompress-base — 文本压缩 ML 模型

目标：自然语言文本（prose）

实现：HuggingFace 模型，在 agentic traces 上训练

为什么用 ML 而非规则：

自然语言的冗余方式不固定（啰嗦、重复、离题）
规则压缩会丢失语义（删掉"不重要"的句子可能删掉了关键上下文）
ML 模型可以学习"什么对 LLM 有用"

模型：Kompress-v2-base（已发布在 HuggingFace，可本地部署）

引擎四：CacheAligner — KV 缓存对齐器

目标：稳定前缀，使 Anthropic / OpenAI 的 KV 缓存实际命中

为什么需要对齐：

Anthropic 和 OpenAI 的 API 有 KV 缓存机制——如果 prompt 前缀不变，可以跳过重复计算
但如果前缀有一丁点变化（哪怕一个空格），缓存就失效
CacheAligner 确保前缀稳定，让缓存真正命中

节省：不是直接压缩 token，而是减少重复计算开销——效果等同于节省 token

引擎五：IntelligentContext — 智能上下文适配器

目标：基于评分的上下文拟合

实现：通过学习到的重要性权重进行裁剪 + RollingWindow（滚动窗口）

为什么需要评分：

不是所有上下文都同等重要
当前对话的上下文重要性 > 10 轮前的上下文
与当前任务相关的上下文重要性 > 无关的上下文

策略：给每个上下文片段打重要性分数，按分数裁剪

引擎六：Image Compression — 图像压缩器

目标：图像 token

实现：训练的 ML 路由器

效果：40%-90% 的图像 token 缩减

为什么需要：多模态 Agent 处理的图像可能占 50%+ 的上下文——一张 1024×1024 的图片可能消耗 1000+ token

CCR 机制：压缩后还能找回原始数据

CCR = Cached Compressed Retrieval（缓存压缩检索）

这是 Headroom 最精巧的设计——压缩不是"有损丢弃"，而是"精简呈现 + 原文可查"。

原始数据 → 压缩后发送给 LLM → 原始数据本地缓存
                                      ↓
                          LLM 需要细节时调用 headroom_retrieve 按需检索

特性	说明
本地缓存	压缩前的原始数据存储在本地，不上传
按需检索	LLM 通过 `headroom_retrieve` 工具主动拉取所需原始片段
TTL 控制	原始数据在配置的 TTL 内可检索
无损语义	压缩后仍能获得相同答案，需要细节时可回溯

关键洞察：CCR 把"压缩"从"信息丢弃"变成了"信息分层"——LLM 先看摘要，需要时再看原文。这比"一刀切压缩"安全得多。

MCP 集成：三个工具即插即用

工具名	功能
`headroom_compress`	主动压缩传入的内容
`headroom_retrieve`	检索 CCR 缓存的原始数据
`headroom_stats`	查看压缩统计信息

安装方式：

headroom mcp install    # 为任何 MCP 客户端安装

代理兼容性矩阵：

代理	支持	备注
Claude Code	✅	`--memory` · `--code-graph`
Cursor	✅	打印配置后粘贴一次
Aider	✅	启动代理 + 启动
Copilot CLI	✅	启动代理 + 启动
OpenClaw	✅	作为 ContextEngine 插件安装

Benchmark 数据详解

真实工作负载

工作负载	压缩前	压缩后	节省率
代码搜索 (100条结果)	17,765	1,408	92%
SRE 事故调试	65,694	5,118	92%
GitHub Issue 分诊	54,174	14,761	73%
代码库探索	78,502	41,254	47%

准确率保持

基准测试	类别	基线准确率	Headroom 准确率	变化
GSM8K	数学	0.870	0.870	±0.000
TruthfulQA	事实	0.530	0.560	+0.030
SQuAD v2	问答	—	97%	19% 压缩
BFCL	工具调用	—	97%	32% 压缩

输出 Token 缩减

除了输入压缩，Headroom 还能缩减模型输出 token：

Verbosity steering：在系统提示末尾追加简短指令，引导模型保持简洁
Effort routing：工具结果返回后调低思考深度，新问题和错误保持全力
实测：Reduction: 31.7% (95% CI 27.7% … 35.7%)

与 codebase-memory-mcp 的互补关系

维度	Headroom	codebase-memory-mcp
场景	通用上下文压缩	代码索引专用
削减率	60-95%	99%
保真度	97%+	代码结构完整保留
可逆性	CCR 可逆缓存	索引指向源文件
集成方式	MCP 服务器	MCP 服务器

两者互补：

codebase-memory-mcp 解决"代码索引"场景——把整个代码库压缩成可检索的索引
Headroom 解决"通用上下文"场景——工具输出、日志、对话历史、API 响应

Agent 的 memory 路由层需要两个层次：(1) 代码级索引（codebase-memory-mcp）；(2) 通用上下文压缩（Headroom）。

So What：三类人的行动清单

🔧 工程师

MCP 集成 = 零代码改动——headroom mcp install 一条命令，Agent 立刻享受 60-95% token 节省
CCR 让压缩变安全——不再担心压缩丢信息，LLM 需要时可以 retrieve 原文
明天就能做：pip install "headroom-ai[all]" + headroom mcp install，在现有 Agent 上测试效果