Headroom 实测:压缩率、无损模式与原文取回

用日志、带类型边界的 JSON 和真实目录测试 Headroom 0.43.1,加入去空白基线,验证无损回退、MCP 原文恢复与重启后的存储边界。

AgentIndex · 发布于 2026-11-07 · 更新于 2026-11-07

Headroom 在上下文进入模型前压缩内容。选型时更有用的问题是:针对你实际发送的格式,它能省多少;哪些信息仍在;需要原文时又能否取回?

离线实测中,重复日志和统一结构的 JSON 节省明显,但 80 条真实目录记录在已经去掉空白后,两种模式的最终节省均为零。无损模式撤销了有损的日志压缩;MCP 原文取回则受到存储后端和条目寿命约束。这些差异比单看最高压缩率更有参考价值。

固定版本与实际输入

测试日期为 2026 年 11 月 7 日,安装 PyPI 发布版 headroom-ai[mcp]==0.43.1。macOS x86_64 wheel 的 SHA-256 为 a35c3bbbe13b8f46abb5e7007d710ce6916c4f028d72fe9e57cba62c7fc9367a;实际安装的原生二进制与核验过的 wheel 一致。选定的九个 Python 文件也与发布提交 2d3ee51846435ef5b320eea4806af14e602b0d8c 一致。固定发布版本

环境为 macOS 26.6.2、Apple M1 Pro,运行的是 x86_64 Python 3.13.1,依赖包括 tiktoken 0.14.0、LiteLLM 1.103.10 和 MCP SDK 2.3.0。首次普通安装尝试编译 cryptography 50.0.2,其依赖要求高于本机 Rust 1.82;改为仅使用预编译包后,解析到 cryptography 48.0.1 并安装成功,pip check 通过。这是本机安装环境的边界,不能推广为所有平台都装不上。

我们执行了 18 个库调用用例,在四个 stdio MCP 进程中进行了 12 次真实工具调用。输入包括人工日志和带类型边界的数组、本站公开目录前 80 条记录的六个字段,以及一份冻结的说明性文章。复现目录、依赖锁与完整结果 保留了输入来源和输出。

分词词表在正式离线运行前准备。执行时设置 HEADROOM_OFFLINE=1、关闭 ML 压缩器,五个进程的 Python socket 审计没有记录到 TCP 连接尝试。没有调用模型或供应商接口,因此不能据此宣称回答质量不变,或证明真实账单下降多少。

基线应包含 JSON 去空白

下表统一使用 o200k_base 计算正文文本 token,不含消息外壳、取回原文或额外工具调用的开销。库调用选择 gpt-4o 只是指定计数路径,没有请求该模型;我们也用发布版计数器重新核对了完整返回消息。MCP 自身的模型计数路径单独记录,没有混进这张表。

输入原正文 token默认模式结果Agent/无损模式结果
1,002 行人工日志15,02210915,022
500 行统一 JSON,带格式化空白20,5145,0295,057
同一数组,已去空白11,0155,0315,067
120 行带类型与引号边界的数组9,3722,8212,351
80 条真实目录记录,带格式化空白7,3634,6264,491
同一目录,已去空白4,5014,5014,501
说明性文章,关闭 ML1,6571,6571,657

统一数组相对于普通去空白仍有明显收益,字段较杂的真实目录则不同:单纯去空白已经达到 4,501 个正文 token。把这份紧凑输入直接交给工具,两种模式都触发膨胀保护并回退原文。因此,相对格式化 JSON 的高节省比例,不代表相对你已经发送的紧凑 JSON 也有同样收益。

这只是固定样本,不是全目录或代表性工作负载基准。解码后保留了全部 80 条记录,包括七条 NOASSERTION 许可信息;六个投影字段的值未作改写。

无损模式要看最终输出

默认日志压缩保留 FATAL 信息、事件编号、中文与异常栈,省略了 997 行 INFO,并附上取回原文的哈希。这是一份带省略信息的短表示,不能视为每一行都仍在。

同一日志交给 densify() 后,返回了原始内容,报告 lossless=True,并计入一次消息回退。其变换列表仍描述尝试过的日志压缩,所以不能只根据变换名判断节省,应核对最终文本和最终计数。

结构化输入表现不同。我们用发布包的解码器展开紧凑表示,再比较规范化 JSON,区分整数、浮点数、布尔值、null、缺失键、空字符串、字面字符串 null、逗号、换行和嵌套值。两种模式的选定结构化输出均与原数据一致,无损模式还报告了校验成功。压缩入口、紧凑格式解码器

紧凑输出并不总是 JSON 数组。若下游要求 json.loads(output) 直接返回列表,需要对应的展开步骤或其他集成约定。程序能够精确还原数据,也不能证明模型一定会正确理解这种更密集的表示。

两个对照说明了配置的影响:短消息保持原样;较大的用户消息默认被保护,显式启用用户消息压缩并设置 protect_recent=0 后才缩小。1,657 个正文 token 的说明文章在关闭 ML 时也没有变化。这不代表启用可选模型后的普通文本压缩已经测试成功或失败。

原文取回验证了存储边界

我们通过真实 stdio 启动发布包原有的 HeadroomMCPServer,关闭可选的本地代理探测。服务列出 headroom_compress、headroom_retrieve、headroom_stats,三个工具都实际调用。压缩返回哈希,取回结果包含完整 Unicode 日志,SHA-256 与原文相同。

默认 SQLite 后端下,第二个 MCP 进程使用相同专用工作目录,可以恢复原文。设置 HEADROOM_CCR_BACKEND=memory 后,原进程内取回成功,重启后的新进程则未命中。这里验证的是所测本机重启行为,不是跨机器持久性或无限期归档。

另做的存储层对照把 TTL 设为一秒,起初取回成功,等待 1.2 秒后过期。所测 MCP 压缩实现为条目设置一小时寿命;我们没有等待一小时验证它的实际过期路径。存储实现、MCP 实现

未知哈希与空压缩内容都在返回 JSON 中带有 error,而 MCP 外层仍为 isError=false。如果只检查协议层错误标志,会漏掉这两种应用层失败。应解析结果后,再判断压缩或恢复是否成功。

适合怎样接入

实际工具输出包含重复日志或结构统一的数组,并且能选择合适的信息保留模式时,值得用自己的数据评估。先拿真实发送的序列化格式与简单去空白比较,再验证压缩视图和恢复路径。该发布版要求 Python 3.11+;本篇依赖锁与结果只覆盖上述环境。

已经紧凑的异构 JSON 可能收益有限,无损检查也可能通过返回原文来保全信息。可选 ML、代理转发、包装 Agent、TypeScript 集成、供应商提示缓存与模型回答质量均未测试。原文可恢复的前提,仍是调用方在它可用时请求正确内容。

会产生浏览器工具输出的流程,可参看 Playwright MCP 表单与会话实测;若要找回以往编码会话中的记录,则可看 ctx 历史检索实测。

若要构建并检查 MCP 工具的服务端契约,可看 FastMCP 校验、超时与权限实测。