Headroom 是一个夹在 Agent 和模型 API 之间的压缩层:工具输出、日志、搜索结果,先过它一遍再发给模型。README 说”同样的答案,一小部分 token”,GitHub 星数 77,626(2026-10-24 用
gh api查的)。我读了它的 Rust 核心,又在 PyPI 版
headroom-ai 0.41.0上跑了 6 组实验。最后留下三个结论:
- 它最重要的设计决定是”不压什么”:只动最新一条用户消息,历史一个字节都不碰。原因是 prompt cache 的计价方式,项目自己写过一份审计,承认第一版架构就是错在这里。
- 它的”有损”其实是换页:丢掉的内容按哈希存在本地,模型可以调工具取回。这和操作系统的虚拟内存是同一个结构,弱点也一样,都要看”缺页”能不能被触发。
- 我实测到一个坑:表格里超过 256 字节的字符串会被整段换成
<<ccr:哈希>>,FATAL 错误的正文也会被换掉,模型在 prompt 里看不到它。
名词速查
| 术语 | 一句话解释 |
|---|---|
| prompt cache(提示缓存) | 模型服务商把你上次发过的请求开头部分存起来,下次开头一字不差就按低价计费 |
| 缓存读 / 写倍率 | Anthropic 的标准价:命中缓存的 token 按原价 0.1 倍收,新写入缓存的按 1.25 倍收(5 分钟有效期) |
| tool_result | Agent 调用工具(读文件、查日志)后,工具返回给模型的那段内容,通常是上下文里最胖的部分 |
| live zone(活区) | Headroom 的术语:请求里唯一允许改写的区域,即最新一条用户消息里的内容 |
| CCR | Compress-Cache-Retrieve:压掉的原文存在本地,prompt 里留一个带哈希的标记,模型需要时调工具取回 |
| SmartCrusher | Headroom 处理 JSON 数组的压缩器,决定留哪几行、怎么改写 |
| Kneedle | 一种找曲线”拐点”的算法:曲线从陡变平的那个位置 |
先懂一件事:prompt cache 按”开头的字节”计价
后面所有设计都建立在这一点上,所以先用一个最小例子讲清楚。
一个 Agent 会话的第 20 轮,请求里有系统提示、工具定义、前 19 轮的对话和工具输出,一共 6 万 token。这 6 万 token 上一轮刚发过,服务商已经缓存了。这一轮新增的只是一个 1 万 token 的日志输出,接在最后。
计费时,服务商从请求开头逐字节比对缓存。开头这 6 万 token 一字不差,就按 0.1 倍价格收;新来的 1 万按 1.25 倍收,同时写进缓存供下一轮用。
关键是一处不同,后面全废。如果你在第 1 万 token 的位置改了一个字,从那里往后的 5 万 token 全部要按 1.25 倍重写。缓存只认前缀,不认”大部分一样”。
(推理侧为什么能这样复用,站内《把 LLM 推理栈当操作系统读一遍》讲过前缀缓存的引用计数机制,这里只需要记住计费规则。)
根本约束:项目自己承认第一版想错了
仓库里有个目录叫 REALIGNMENT/,是团队写给自己的架构审计。REALIGNMENT/00-overview.md 第一句话就是:
Headroom is built on the wrong mental model: “compression means choosing what to drop from conversation history.”
第一版的旗舰组件叫 IntelligentContextManager:把整个 messages 数组 tokenize,给每条消息打重要性分,从旧到新删,删到预算以内为止。直觉上很合理,旧消息最不重要,删旧的就对了。
审计里写,这个组件接进 Rust proxy 时 frozen_message_count 被硬编码成 0,于是”每一次压缩都从第 0 条消息开始删,对每个触发它的客户都打爆了 Anthropic 的 prompt cache”。审计给出的处置是删掉约 25K 行代码(Python 和 Rust 两边加起来),换成现在的 live zone 模型;live_zone.rs 开头的注释写着删消息的那套机制已经退役。
这笔账可以自己算一遍。用上一节的场景,比较两种压法:
| 方案 | 做法 | 本轮输入成本(基础价 token 数) |
|---|---|---|
| 不压 | 6 万缓存读 + 1 万新写 | 18,500 |
| A:只压新来的 | 新来的 1 万压到 4 千 | 11,000(−41%) |
| B:回头压历史 | 把第 1 万位置的一个 2 万旧输出压到 5 千 | 57,250(+209%) |
方案 B 压掉的 token 更多(1.5 万),这一轮的账单却是原来的 3 倍,因为从第 1 万 token 往后的整个前缀都要重写。之后每轮能少读 1.5 万缓存 token,每轮只省 1,500,要再跑 25.8 轮才回本,而且前提是这 25.8 轮里缓存一直没过 5 分钟有效期。
# calc_cache.py —— 上表的验算,单位是"基础输入价下的 token 数"
READ, WRITE = 0.1, 1.25
P, T = 60_000, 10_000
turn = lambda cached, new: cached * READ + new * WRITE
base = turn(P, T) # 18,500
live = turn(P, 4_000) # 11,000
hist = turn(10_000, (P - 10_000 - 15_000) + T) # 57,250
print((hist - base) / (15_000 * READ)) # 25.8 轮回本
倍率我核过 Anthropic 官方定价页,和仓库里 headroom/cache_economics.py 写的一致(Anthropic 读 0.1、写 1.25;OpenAI 读 0.5、写 1.0)。
所以可以把根本约束写成一句可以被反驳的话:
Headroom 只压最新一条消息,是因为服务商的缓存按字节前缀计价、读价只有写价的 1/12.5。 反过来想:如果缓存不存在,或者读写同价,最划算的就是回头压历史里最大的旧输出,也就是它第一版的做法。OpenAI 的读价是 0.5 倍,这个约束在 OpenAI 上会弱很多(这是我按倍率推的,没有在 OpenAI 上测)。
这个约束在代码里落成了三条硬规矩:
| 规矩 | 源码位置 | 坏掉会怎样 |
|---|---|---|
只改活区:下界是 frozen_message_count,上界是最新一条用户消息 | crates/headroom-core/src/transforms/live_zone.rs:36-45 | 改到已缓存的消息,当轮账单按上表变成 3 倍 |
| 活区外的字节原样拷贝,不做”解析→修改→再序列化” | live_zone.rs:77:out = body[..block_start] || replacement || body[block_end..] | 重新序列化 JSON 会改空白和数字格式,前缀哈希就对不上了,虽然内容”没变” |
CacheAligner 只检测、不改写:发现系统提示里有时间戳、UUID 只打警告 | headroom/transforms/cache_aligner.py:1-24 | 旧版会改写系统提示,系统提示在整个前缀的最前面,改了它整个缓存都失效 |
还有一条容易漏的:取回工具 headroom_retrieve 现在每个请求都注册,不管这一轮有没有压缩(审计第 3 条错误假设)。工具定义也在缓存前缀里,工具列表一会儿多一个、一会儿少一个,缓存就跟着一会儿命中、一会儿失效。
库模式的 compress() 也留了同一个口子:CompressConfig.frozen_message_count(headroom/compress.py:123),默认 0,文档说明自己管理对话循环的调用方应该传上一轮的消息数。如果你用库模式又没传这个参数,就是第一版的错误又犯一次。
怎么压:先试无损,不够才挑行
活区里的内容先由 ContentRouter 判断类型(JSON、代码、日志、diff、纯文本),再分给对应的压缩器。工具输出里最常见的是 JSON 数组,归 SmartCrusher 管。它的主干在 crates/headroom-core/src/transforms/smart_crusher/crusher.rs:838-973,压缩成伪代码是这样:
# 伪代码,对应 crusher.rs 的 crush_array_with_source(),省略了观测、prose hook 等分支
def crush_array(items, query):
k = compute_optimal_k(items) # Kneedle 拐点,见下文
if len(items) <= k:
return items # 本来就不多,原样放行
table = compact_to_csv_schema(items) # 无损:键名只写一次,改成表格
if 1 - len(table) / len(items_json) >= 0.15:
return table # 省够 15% 就收工,一行不丢
if lossless_only:
return items # 严格无损模式:宁可不压
keep = pick_rows(items, budget=k, query=query) # 有损:挑行
ccr_store.put(hash(items), items) # 整份原文存起来
return keep + [marker(hash, dropped=len(items) - len(keep))]
实验一:大多数 JSON 根本走不到”挑行”
我先按 README 的叙事造了数据:200 条服务日志,第 137 条是 FATAL,第 61 条延迟 9000ms,第 88 条用户名特殊。
$ python exp1.py # headroom-ai 0.41.0, tokenizer = gpt-4o
tokens 12051 -> 5874 saved 6177 (51.3%)
transforms: ['router:protected:user_message', 'router:smart_crusher:0.38']
压掉 51%,200 行一行都没丢。输出长这样:
[200]{id:int,latency_ms:int,level:string,msg:string,service:string,ts:string,user:string}
0,50,INFO,request completed ok,checkout,2026-10-24T10:00:00Z,u1000
1,44,INFO,request completed ok,checkout,2026-10-24T10:00:01Z,u1001
...
这一半的节省全部来自键名去重:JSON 每一行都要重复写一遍 "latency_ms":,表格只在表头写一次。这就是 CSV 加 schema 头,数据库的列式存储也是同一个思路。挑行、拐点、异常检测这些逻辑,在这份数据上一个都没有运行。
这里我自己出过一次错。第一版实验脚本用 '"latency_ms":9000' in out 检查异常值有没有保留,结果报了 False,我还以为它把异常行丢了。其实是输出已经变成表格,里面是 61,9000,INFO,...,根本没有键名。检查压缩结果时别用原格式的字符串去匹配,换了表示法,你的断言就跟着失效了。
还有一个小细节:压完的 content 是一个 JSON 字符串字面量,开头带引号,换行是转义的 \n。这是为了让内容仍然是合法 JSON,代价我用 tiktoken 量了一下:转义版 5,833 token,解开后 5,831 token,只差 2 个。
留几行:Kneedle 找”新信息不再增长”的拐点
真正要挑行时,第一个问题是留几行。adaptive_sizer.rs:54 的 compute_optimal_k 不用固定比例。它逐行累加”到目前为止见过多少种不同的相邻词对(bigram)“,得到一条只增不减的曲线,然后找曲线从陡变平的地方。
可以把它想成翻一叠调查问卷:头几份每份都有新答案,翻到某一份之后几乎全是重复的,那一份就是拐点。
算法本身很短(adaptive_sizer.rs:111-148):横纵坐标都归一化到 0–1,算每个点”高出对角线多少”,取最高的那个。拿 10 行的小例子手算:
| 第 i 行 | 累计不同 bigram | 纵坐标归一化 | 横坐标归一化 | 高出对角线 |
|---|---|---|---|---|
| 0 | 6 | 0.000 | 0.000 | +0.000 |
| 1 | 11 | 0.417 | 0.111 | +0.306 |
| 2 | 15 | 0.750 | 0.222 | +0.528 |
| 3 | 16 | 0.833 | 0.333 | +0.500 |
| 4 | 17 | 0.917 | 0.444 | +0.472 |
| 6 | 18 | 1.000 | 0.667 | +0.333 |
| 9 | 18 | 1.000 | 1.000 | +0.000 |
(表里省略了第 5、7、8 行,它们的值都更小。)最大值在第 2 行(0.528),返回 2 + 1 = 3,即留 3 行(我用脚本逐行复现了 find_knee,结果一致)。真实流程在这之后还有三道修正:不同内容占比超过 70% 时设保底比例;乘一个 bias;再用 zlib 检查,如果留下的子集比全集好压很多(压缩率差超过 15%),说明丢了多样性,k 上调 20%(adaptive_sizer.rs:99-101)。
留哪几行:错误行可以突破预算
留哪几行由 planning.rs:169 的 plan_smart_sample 决定,按顺序收集五类候选:首尾锚点、结构离群行和带错误关键词的行、数值偏离均值超过 2σ 的行、变化点前后各一行、和用户问题相关的行。
候选太多、超出预算时,orchestration.rs:176-196 的排序很说明问题:错误行、离群行、异常值先全部放进去,再看剩多少名额给首 3 行和尾 2 行。也就是说,预算对错误行不起作用,100 条 FATAL 就留 100 条。这是一个明确的取舍:宁可压得少,也不丢错误。
但这个保证只在挑行这条路径上。下一节会看到另一条路径没有它。
CCR:这不是有损压缩,是换页
挑行丢掉的内容去了哪里?crusher.rs 的注释写得很直白:lossy 在这里的意思是”prompt 里放压缩视图,全量原文在 CCR 缓存里可取回”。
把它和操作系统的虚拟内存对一下,几乎一一对应:
| 虚拟内存 | Headroom CCR | 源码 |
|---|---|---|
| 物理内存里的页 | prompt 里保留的行 | — |
| 换到磁盘的页 | 存进本地 CompressionStore 的原文 | headroom/cache/compression_store.py:236,默认最多 1000 条,LRU 淘汰 |
| 页表项 | prompt 里的 <<ccr:6321a0f618e9 ...>> 标记 | SHA-256 的前 12 位十六进制 |
| 缺页中断 | 模型调用 headroom_retrieve(hash) | headroom/ccr/tool_injection.py:22 |
| 内核处理缺页、恢复执行 | proxy 截住这次工具调用,自己查表、把原文塞回去、再请求一次模型 | headroom/ccr/response_handler.py,最多 3 轮(:76) |
| 换出页过期 | TTL 1800 秒后取不回 | compression_store.py:54 |
sequenceDiagram
participant A as Agent 客户端
participant H as Headroom proxy
participant S as 本地 CCR 存储
participant M as 模型 API
A->>H: 请求(最后一条带 200 行工具输出)
H->>S: 存原文,键 = 哈希
H->>M: 压缩后的请求 + 标记 + headroom_retrieve 工具
M-->>H: 调用 headroom_retrieve(哈希)
H->>S: 按哈希查原文
S-->>H: 原文
H->>M: 把原文作为工具结果补上,再请求一次
M-->>H: 最终回答
H-->>A: 最终回答(客户端看不到中间的取回)
站内那篇操作系统类比的结论是”语义层的上下文管理对应的不是 GC,而是页面置换加有损压缩”。Headroom 往前走了一步:它让”有损”变成可撤销的,换出去的页还能换回来。
我验证了换回来的东西是否逐字节一致:从压缩结果里取出第 137 行的哈希 6321a0f618e9,去 get_compression_store().retrieve() 查,拿回的字符串和原始 msg 字段 == 比较为 True。
和操作系统不同的地方,正是 CCR 最脆弱的地方。 操作系统的缺页是硬件在访问时触发的,程序不用知道哪一页不在内存里。CCR 的缺页要靠模型自己决定去调工具,它得先知道自己缺了什么。如果标记写着类似”42 rows offloaded”的话,模型能判断出”可能有我要的东西”;如果标记什么线索都不给,模型就不会去取。
实测发现:256 字节以上的字符串整段被换成哈希
前面的实验里,键名占了大头,无损改写轻松省到 15% 以上。我想逼它走挑行路径,于是换了一份数据:200 行,每行只有 id、latency_ms 和一个 250–300 字节的长 msg,FATAL 写在第 137 行的 msg 开头。
结果它既没走无损表格、也没走挑行,走了第三条路:
$ python exp2.py
tokens 12381 -> 4472 (63.9% saved)
transforms: ['router:protected:user_message', 'router:smart_crusher:0.11']
[200]{id:int,latency_ms:int,msg:string}
0,54,<<ccr:7410edced8af,string,277B>>
...
137,55,<<ccr:6321a0f618e9,string,276B>>
200 行都在,但 199 个 msg 都变成了哈希(另一行只有 253 字节)。FATAL payment gateway connection refused 这串字在整个 prompt 里一次都没出现。 模型看到的第 137 行是”55 毫秒,内容见哈希”,和其他 198 行没有任何区别。它要想发现这次故障,只能把 199 个哈希逐个取回。
原因在 crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs:130:字符串长度超过 opaque_min_bytes(默认 256,classifier.rs:76)就被归为”不透明大块”,然后检查是不是 base64、是不是 HTML,都不是也照样归为 LongString 卸载。我在整个 compaction/ 目录里搜 error、keyword、fatal,零命中。上一节说的”错误行可以突破预算”那条保证,在这条路径上不存在。
为了确认确实是 256 这个阈值,我只改一个变量做了边界实验:199 行都是短 msg,只把 FATAL 那行的 msg 长度从 200 调到 1000 字节:
$ python exp3.py
msg= 200B saved 63.4% 'payment gateway' visible=True row137=137,48,FATAL,FATAL payment gateway connection refused; xxx
msg= 256B saved 63.3% 'payment gateway' visible=True row137=137,42,FATAL,FATAL payment gateway connection refused; xxx
msg= 257B saved 63.6% 'payment gateway' visible=False row137=137,45,FATAL,<<ccr:6bf5fb297142,string,257B>>
msg= 300B saved 63.6% 'payment gateway' visible=False row137=137,46,FATAL,<<ccr:0d3cd3b15c15,string,300B>>
msg=1000B saved 64.2% 'payment gateway' visible=False row137=137,44,FATAL,<<ccr:de129ba2c4fb,string,1000B>>
256 字节可见,257 字节消失。还有一点要说清楚:这组数据里 level 是一个独立的短字段,所以 FATAL 这个级别标签一直可见,模型至少知道第 137 行出了事、值得取回。实验二没有 level 字段,错误只写在长字符串里,模型就完全没有线索。问题严不严重,取决于你的工具把错误信号放在哪个字段里。
压缩率也说明了它为什么这样设计:实验三里 FATAL 那行藏不藏,压缩率都在 63–64%,因为节省主要来自其他 199 行;实验二里那 199 个长字符串就是全部的节省。换成只允许可证明无损的 mode="agent" 再跑实验二:
$ python exp6.py
mode=None 12369->4460 (63.9% saved) FATAL visible=False markers=199
mode=agent 12369->12369 (0.0% saved) FATAL visible=True markers=0 lossless=True
在这份数据上,64% 的节省全部来自”把内容藏起来”,不藏就一分不省。这不是 bug 和正确行为的区别,是两种立场的取舍。我的判断是:默认值把这个取舍偏向了省 token,而 README 首页的演示(“FATAL line survives”)给人的印象是相反的。
软处我列一下:
- 以上都是库模式
compress()的实测。proxy 模式(headroom wrap claude实际走的路)我只读了代码、没跑:live_zone.rs:568用SmartCrusherConfig::default()构造 SmartCrusher,默认enable_ccr_marker: true(config.rs:154),而opaque_markers_enabled()就取这个值,所以我推断行为相同。 - 我在上游 issue 里搜了几组关键词,没找到讲这件事的;最接近的是 #1091(已关闭),讲的是关掉 marker 开关后长字符串仍被卸载,属于配置不生效,不是错误信号被藏。
- 我没有让真模型面对这种 prompt 测”它会不会主动取回”。这是最该补的实验,下文最后一节会讲怎么做。
README 的延迟数字测的是缓存命中
README 写压缩耗时”远低于 1 毫秒,10K token 的 JSON p50 0.21 ms”。我测的结果是这样(M5 Pro,每组 30 次取中位数):
| 数据 | 同一份 payload 重复压 | 每次改一个字段 |
|---|---|---|
| 200 行短记录 | 0.61 ms | 6.13 ms |
| 200 行长 msg(实验二数据) | 1.72 ms | 24.09 ms |
差了 10–14 倍。原因是 content_router.py:1561 有一个按内容哈希索引的结果缓存(默认 TTL 30 分钟),同样的内容第二次进来直接返回上次的结果。再看 README 数字的来源 benchmarks/bench_latency.py:715-726:先用同一份 messages 预热 3 次,再用同一份 messages 测 20 次,所以测量轮次大概率都是缓存命中。我想直接跑这个 benchmark 对照,但仓库 HEAD 的 Python 源码和 PyPI 0.41.0 的 Rust 扩展版本对不上,在 content_router.py:2966 报错,所以这一条是读代码得出的推断。
公平地说,24 ms 放在一次动辄几秒的模型调用前面,仍然可以忽略。我要指出的是这个数字测的东西:Agent 每一轮新来的工具输出都是新内容,碰不上这个缓存,你实际付的是右列。另外,每个进程第一次调用要加载检测器,我在实验一里单次观察到 7.3 秒冷启动,proxy 常驻时只付一次。
一个值得补的实验
上面最大的空白是:模型看到一屏 <<ccr:...>> 时,到底会不会去取?这个实验可以这样做:
- 数据:实验二那份 200 行(FATAL 藏在第 137 行长 msg 里),再加一份对照,把 FATAL 挪进独立的
level字段。 - 步骤:起
headroom proxy --port 8787,用 Anthropic SDK 发”checkout 为什么失败”,两份数据各跑 10 次。 - 记录:proxy 日志里
headroom_retrieve的调用次数;最终回答里有没有提到 payment gateway;单次请求的总 token(取回会多一轮完整请求)。 - 成本:API 费用不到 1 美元,半小时左右。
我预期对照组(有 level 字段)会取回,实验组多数不会,但这是猜测。做出来之后我会补到这篇。
小结
- 根本约束:服务商按前缀字节缓存、读价是写价的 1/12.5,所以压缩只能发生在最新一条消息里。回头压历史的账单是不压的 3 倍,要 25.8 轮才回本,项目第一版就是在这里栽的。
- 两层机制:先无损(键名去重成表格,常见 JSON 能省一半,一行不丢),不够再挑行(Kneedle 定数量、错误行可突破预算),丢掉的存进 CCR 可取回。
- 崩点:CCR 的缺页要模型自己触发。256 字节以上的字符串会被无条件换成哈希,没有错误关键词检查,所以错误信号只在长字段里时,模型看不到它。
- 可带走的动作:用库模式就传
frozen_message_count;检查你的工具输出把错误级别放在哪个字段;看压缩延迟时换着 payload 测。
通俗总结
把模型的上下文想象成一张办公桌,服务商的缓存是”桌上摆放没动过就打一折”的规矩。
Headroom 干的事,是在新文件放上桌之前先整理一遍。它不碰桌上已有的东西,因为挪动一样,后面所有东西都要按原价重新算钱。整理新文件时,它先试着把表格里重复的表头去掉,这一步什么都不丢;不够的话,就把不太重要的页收进抽屉,桌上留一张写着抽屉编号的便签,模型需要时可以喊人去拿。
问题在于便签上写什么。如果便签写着”这里有 42 页,含错误报告”,模型会去拿;如果便签只写一个编号,模型根本不知道抽屉里有一份事故报告。Headroom 现在会把所有超过 256 字节的段落都换成只写编号的便签,不管里面是不是事故报告。
能复述给同事的一句话:Headroom 只压最新的内容,是为了不打爆缓存;它压掉的东西都能取回,但模型得先知道该去取。
如果你正在用 headroom wrap,花 5 分钟打开最近一次的工具输出,看看错误信息是写在一个短的 level/status 字段里,还是只出现在一段很长的 message 里。如果是后者,这篇第四节的情况就会发生在你身上。
参考来源
工程实践与源码(均为仓库 commit e995eb9)
- headroomlabs-ai/headroom:
REALIGNMENT/00-overview.md(架构审计)、crates/headroom-core/src/transforms/live_zone.rs、smart_crusher/{crusher,planning,orchestration,config}.rs、smart_crusher/compaction/classifier.rs、adaptive_sizer.rs、headroom/ccr/、headroom/cache/compression_store.py、benchmarks/bench_latency.py - Anthropic Prompt Caching 文档:缓存写 1.25×、读 0.1× 的出处
- 上游 issue #1091:关闭 CCR marker 后长字符串仍被卸载(已修复)
算法
- Satopää, Albrecht, Irwin, Raghavan, Finding a “Kneedle” in a Haystack: Detecting Knee Points in System Behavior, ICDCS Workshops 2011, doi:10.1109/ICDCSW.2011.20:
find_knee的原始算法(源码没有引用它,是我对上的)
站内相关
- KV cache 是内存管理,上下文管理是 GC 吗?:CCR 换页类比的前一步
- Agent 的内存管理:Claude Code 与 Codex 如何决定”忘掉什么”:Agent 自己做的上下文淘汰,和 Headroom 这种外挂层可以对照着读
- 当你对 Claude Code 说 hello:一次请求里那几万 token 都是什么