7
0
1

AI Agent 的 token 账单爆炸?用 Headroom 在本地装一台「上下文压缩机」

文章摘要
|

你的 Agent 不是在干活,是在「复读」

如果你用 Claude Code、Codex、Cursor 这类编程 Agent 跑过长任务,大概率见过这个场景:任务跑了两小时,账单一拉,几十万 token 没了。翻一下会话明细会发现,真正「值钱」的推理没多少,大头全是垃圾流量——grep 出来的 100 条重复搜索结果、一屏一屏的日志、结构一模一样的 JSON 工具输出,每次调用都原封不动塞回上下文,然后再整个发给模型。模型按 token 收费,复读机模式等于按小时烧钱。

最近 GitHub trending 上有个专门治这个的项目火了:headroomlabs-ai/headroom,拿过 Trendshift 当日仓库第一,star 数早过了四万。它把自己定位成「AI Agent 的上下文压缩层」——所有要进模型的东西(工具输出、日志、RAG 片段、文件、对话历史),先在本地压一遍再发出去,官方口径是同样的答案,零头的 token。

今天就拆一拆它:是什么、怎么接、数据靠不靠谱,最后手写一个 80 行的迷你版,把它的核心思路讲透。

一、先搞清楚:token 都烧在哪了

一个典型 Agent 会话的上下文膨胀路径大概是这样的:

  • 工具输出是大头:一次代码搜索返回 100 条结果,每条都是 {"file": "a.py", "line": 12, "match": "def main"} 这种结构完全一致的 JSON,字段名重复了 100 遍;
  • 日志刷屏:调一个 bug,cat 一下服务日志,几千行 INFO 里可能就 3 行 ERROR 有用,但模型照单全收;
  • 历史越滚越长:多轮对话里,前几轮的工具输出被反复重发,KV 缓存能救一部分,但救不了内容本身;
  • 复读式输出:别忘了模型写回来的 token 更贵——Opus 级模型输出价格是输入的 5 倍,而它经常把读过的代码原样贴回来。

关键认知是:这些内容高度重复且结构化。重复 JSON 数组和日志行是压缩率最恐怖的两种 payload,这正是可压缩的空间。

二、Headroom 是什么:跑在本地的一台压缩机

一句话:它夹在你的应用和 LLM 提供商之间,拦截请求、压缩上下文、转发优化后的 prompt。全程本地运行,prompt 和文件内容不会外发去压缩——这点和托管型压缩 API(如 Compresr、Token Co.)是本质区别。

内部流水线按内容类型自动路由,三台压缩机各管一摊:

  • SmartCrusher:管 JSON。数组、嵌套对象、混合类型都行,基于字段方差统计(而不是关键词表)来决定保什么——错误项、统计上的异常值、首尾边界会保留;
  • CodeCompressor:管源码,AST 感知,支持 Python、JS/TS、Go、Rust、Java、C/C++、C#、PHP;
  • Kompress-v2-base:管自然语言文本,是他们发布在 HuggingFace 上的模型,用 Agent 真实轨迹训练的。

两个设计细节值得单独说:

可逆压缩(CCR):原始内容缓存在本地,模型如果真的需要全文,可以调 headroom_retrieve 按需取回。压缩不是有损赌博,是「先给摘要,想要再给全文」。CacheAligner:只压缩「活跃区」的新字节,冻结前缀保持字节级不变——这样服务商的 prompt KV 缓存不会被打爆,该省的缓存钱照省。

顺带一提,压缩本身的开销官方给的数据是:10K token 的 JSON 上 p50 只要 0.21 毫秒,100K token 也才 1.4 毫秒,基本不会出现在 Agent 延迟里。

三、60 秒接入:三种姿势

安装(需要 Python 3.10+,PyPI 包名是 headroom-ai):

pip install "headroom-ai[all]"          # Python,全功能 + CLI
uv tool install --python 3.13 "headroom-ai[all]"  # 推荐:隔离环境装 CLI
npm install headroom-ai                 # 只要 TS SDK 的话

姿势一:零改动代理。起一个本地 proxy,任何 OpenAI 兼容客户端把 base URL 指过来就行,不用动一行代码:

headroom proxy --port 8787
headroom doctor        # 健康检查,确认内容路由正常
headroom dashboard     # 实时省量面板(proxy 要在跑)

姿势二:一键包住编程 Agent。这是对个人开发者最省事的一条:

headroom wrap claude    # 包住 Claude Code,也支持 codex/grok/aider/copilot/cursor 等
headroom unwrap claude  # 后悔了,一条命令还原

姿势三:代码内联。在你的 Python 应用里直接调:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o", messages=result.messages
)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

此外它还提供 MCP server 形态(headroom mcp install,暴露 headroom_compress、headroom_retrieve、headroom_stats 三个工具)和跨 Agent 共享记忆——Claude、Codex、Gemini、Grok 共用一个本地记忆库,自动去重。生态适配列表很长,LangChain、LiteLLM、Vercel AI SDK、Agno 都有现成的挂载点。

四、数据靠不靠谱:官方 Proof 与自测

项目 README 里给了一张可复现的评测表(脚本带种子、离线可跑,uv run python benchmarks/index_proof_table.py --seed 20260902),四个用真实 MCP server 输出格式构造的场景:

  • 代码搜索(100 条结果):17,199 → 13,597,省 21%;
  • SRE 事故排障:55,957 → 24,340,省 57%;
  • 代码库探索:58,801 → 33,895,省 42%;
  • GitHub issue 分诊:46,067 → 32,429,省 30%。

注意两个诚实的注脚:一是省量随 payload 重复度线性放大,重复 JSON 和日志行在基准里能压掉 90% 以上,而本就紧凑的散文几乎压不动;二是他们还跑了准确率回归(GSM8K 上基线和压缩后打平,TruthfulQA 的 ±0.03 在置信区间内),没有「压完了模型变傻」的暗坑。

想看自己流量上的真实数字,跑 headroom savings,比任何评测都准。

五、手写一个 80 行迷你版,看懂它为什么有效

Headroom 最核心的两个思路——日志按模板聚类、JSON 保异常压重复——其实不需要任何模型,用纯规则就能复刻个雏形。下面这段代码我跑过,语法正确,你可以直接拿去玩(把两个函数塞进你自己的 Agent 工具调用链路,在结果返回给 LLM 之前过一遍):

import json, re
from collections import Counter

# 1) 日志模板化:时间戳/UUID/IP/hash/数字全部归一成占位符
NOISE = [
    (re.compile(r'\b\d{4}-\d{2}-\d{2}[T ]?\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b'), '<TS>'),
    (re.compile(r'\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b'), '<UUID>'),
    (re.compile(r'\b\d+\.\d+\.\d+\.\d+\b'), '<IP>'),
    (re.compile(r'\b[0-9a-f]{8,}\b'), '<HASH>'),
    (re.compile(r'\d+(?:\.\d+)?'), '<N>'),
]

def template(line: str) -> str:
    for pat, sub in NOISE:
        line = pat.sub(sub, line)
    return line.strip()

def crush_logs(text, keep=('FATAL', 'ERROR', 'WARN')):
    counts, kept = Counter(), []
    for ln in text.splitlines():
        if not ln.strip():
            continue
        if any(k in ln.upper() for k in keep):
            kept.append(ln)          # 关键行原样保留
        else:
            counts[template(ln)] += 1
    merged = [f'{c}x {t}' for t, c in counts.most_common()]
    return '\n'.join(merged + ['--- kept verbatim ---'] + kept)

# 2) JSON 数组:去重 + 保留异常和首尾边界
def crush_json_array(items, keep_n=2):
    seen, uniq = {}, []
    for it in items:
        fp = json.dumps(it, sort_keys=True)
        if fp not in seen:
            seen[fp] = 0
            uniq.append(it)
        seen[fp] += 1
    if len(uniq) <= keep_n * 2 + 1:   # 本来就没几条,别压了
        return json.dumps(items, ensure_ascii=False)

    def is_outlier(it):
        s = json.dumps(it).lower()
        return any(k in s for k in ('error', 'fail', 'fatal', 'timeout'))

    interesting = [it for it in uniq if is_outlier(it)]
    normal = [it for it in uniq if not is_outlier(it)]
    head, tail = normal[:keep_n], normal[-keep_n:]
    rest = max(len(normal) - len(head) - len(tail), 0)
    out = {'total': len(items), 'unique': len(uniq)}
    if interesting:
        out['anomalies'] = interesting   # 异常一条不丢
    out['head'] = head                   # 首尾边界帮模型定位
    if rest:
        out['omitted'] = f'{rest} repetitive records suppressed'
    out['tail'] = tail
    return json.dumps(out, ensure_ascii=False)

拿一段模拟日志实测,效果立竿见影——4 行 INFO 归并成 2 个模板(3x/1x 前缀标注次数),ERROR 和 FATAL 一字不动:

3x INFO <TS> request id=<HASH> path=/api/users latency=<N>ms
1x INFO <TS> request id=<HASH> path=/api/posts latency=<N>ms
--- kept verbatim ---
ERROR 2026-10-22T01:12:06 payment gateway timeout after 3000ms txn=5f3c
FATAL 2026-10-22T01:12:08 db pool exhausted, 32 connections leaked

JSON 那半边更狠:81 条搜索结果压成「异常 + 头 2 + 尾 2 + 一句省略说明」,按粗略的 4 字符/token 估算,压掉约 91%——而模型排障真正需要的那条 raise ValueError 完整保留。这就是 SmartCrusher 思路的极简版:砍掉的是统计意义上的噪音,留下的是信息量。Headroom 真正的护城河在于 AST 级的代码压缩、训练过的文本模型、以及可逆取回机制,但「为什么规则压缩就能起效」,上面 80 行已经说明白了。

编辑器里的代码
迷你压缩器可以直接塞进你现有 Agent 的工具调用链路

六、什么时候不该用

README 自己列了「跳过它」的条件,照抄过来,免得你白折腾:

  • 短对话、散文、本来就很紧凑的输出——压缩率趋近于零,白跑一遍;
  • 低于 min_input_words 阈值的块直接原样返回,字节不变;
  • 只用单一提供商的原生 compaction(比如 OpenAI 的对话历史压缩)且不需要跨 Agent 记忆的,没必要再叠一层;
  • 沙箱环境跑不了本地进程的,无缘。

它的甜点位是:长会话 + 重工具输出的日常编程 Agent 使用。另外两个实用细节——遥测信标默认开启(只上报压缩比和计数,不含 prompt 内容,HEADROOM_BEACON=off 可关);想连「模型写回来的废话」一起治,HEADROOM_OUTPUT_SHAPER=1 打开输出侧削减,官方对输出省量的估算是约 32%(带置信区间,且明确标注为 estimated)。

写在最后

Agent 时代的「context engineering」正在变成一门显学:上下文不是越多越好,而是在正确的时刻装正确密度的信息。Headroom 把这件事做成了免改代码的基础设施,而它背后的判断——工具输出是最大的可压缩冗余——你用 80 行 Python 就能验证。今天就把 headroom wrap 跑起来,明天看看 dashboard 上的省量数字,比看任何评测都直观。

项目地址:github.com/headroomlabs-ai/headroom(Apache 2.0,文档在 docs.headroomlabs.ai)。本文事实与数据来自其 GitHub 仓库 README 及 PyPI 页面,选题灵感来自近期 GitHub trending 与社区讨论。

以上内容为 GLM 5.3 Agent 整合定时发布。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

AI Agent 的 token 账单爆炸?用 Headroom 在本地装一台「上下文压缩机」
/archives/tech-blog-2026-10-22
作者
番茄酱唉
发布于
2026-10-22
许可协议
CC BY-NC-SA 4.0

评论

欢迎来到我的博客!