压缩率虚高怎么破？sqz质量基准测试详解：25个场景359个关键事实100%保留-开发者社区

【免费下载链接】sqz

Context compression for AI coding agents: compresses tool output before it enters the model, dedups repeats to 13-token refs. Claude Code, Cursor, Codex, Kiro, Zed, any MCP client. Rust, zero LLM calls.

项目地址：https://gitcode.com/gh_mirrors/sqz/sqz

点击查看免费下载

「压缩率虚高」是 AI 编程代理上下文压缩领域最容易被忽视的坑：把代理真正需要的那一行删掉，压缩率数字立刻好看，但代价是代理重跑命令、原地打转、甚至给出更差的答案。sqz 是一款用 Rust 编写的开源工具，专为 Claude Code、Cursor、Codex、Kiro、Zed 等 AI 编程代理做"上下文压缩"——在工具输出进入模型之前先压缩、把重复内容去重成 13 个 token 的引用，全程零 LLM 调用。

本文详解 sqz 的质量基准测试（quality benchmark）如何同时守住"压缩率"和"信息保留"两条线：25 个真实命令场景、359 个关键事实 100% 保留、51.6% 的聚合压缩率，且每个数字都由一条可重复运行的回归测试锁定。

为什么"压缩率虚高"是个坑

Token 压缩率是一个极易被"做大"的数字。只要丢掉了代理需要的某一行，表头数字就会上涨，而真实代价在后面：

代理重跑命令，白白浪费一个 turn
反复重试、原地打转
最终给出更差的答案

所以只看压缩率（reduction）的基准测试，天然倾向于"报喜不报忧"。sqz 的做法是在同一个测试里同时度量压缩率和信息保留，并把两者都变成回归门槛（regression gate）——任何一次改动，只要让 359 个关键事实少保留 1 个，测试就失败。完整说明见 docs/quality-benchmark.md。

基准测试怎么测：走真实的二进制路径

很多压缩器的基准测试是在"实验室环境"里跑核心函数。sqz 不同：它把每个测试样例（fixture）当作标准输入，通过真实的sqz二进制、以 shell hook 完全相同的方式（sqz compress --cmd <cmd>）压一遍，再记录五项指标：

指标	含义
Token 压缩率	输入 vs 代理看到的总量（压缩后 stdout + sqz 自己的 stderr 行）
关键事实召回	每个 fact 必须逐字出现在压缩后的 stdout，漏掉一个即失败
丢弃的噪声	预期被压缩删掉的行（进度点、弃用提示、通过的测试）
逐字保留	`git show`、traceback、密钥类内容必须与输入完全一致
字节精确恢复	第二次运行返回`§ref:HASH§`去重引用，`sqz expand`能还原原始字节

关键点：facts 是按"代理行动需要什么"来选的，而不是按"sqz 恰好保留了什么"来选的。开发中两者不一致时，修的是格式化器，不是测试样例。全部样例、事实、门槛都集中在 sqz/tests/quality_bench.rs 这一个文件里。

sqz 内部是一条五阶段压缩流水线，理解它能帮你读懂后面的结果表：

五个阶段：① 按命令格式化 ② 结构化摘要 ③ 去重缓存 ④ JSON 压缩 ⑤ 安全模式。栈跟踪、数据库迁移、密钥行会被提前路由到安全模式，原样放行。

结果一览：51.6% 压缩率，359/359 关键事实保留

下表是 25 个场景中的代表性样本（完整 25 行见 docs/quality-benchmark.md）：

场景	命令	输入 token	输出 token	压缩率	保留事实
重复应用日志	`tail -n 200 app.log`	1025	135	86.8%	3/3
pytest 失败	`pytest`	311	71	77.2%	5/5
npm install	`npm install`	161	39	75.8%	4/4
AWS 实例列表	`aws ec2 describe-instances`	4693	1412	69.9%	80/80
kubectl 服务 JSON	`kubectl get pods -o json`	1671	627	62.5%	13/13
Docker 容器	`docker ps`	193	79	59.1%	6/6
cargo test 失败	`cargo test`	303	154	49.2%	5/5
git status	`git status`	155	82	47.1%	6/6
find 80 个文件	`find . -name '*.py'`	515	515	0.0%	80/80
git diff	`git diff`	148	148	0.0%	7/7
Python traceback	`python app.py`	82	82	0.0%	4/4
合计	12,264	5,932	51.6%	359/359

0.0% 的行才是重点：sqz 的"诚实"设计

表里那一堆 0.0% 不是失败，而是这套基准测试真正想说明的事。在这些场景里 sqz 主动返回了未改动的原始输入——要么没有可安全删除的内容，要么省下的不足 16 个 token，此时净收益门槛（net-win gate）会选择放行原文，而不是"为了压而压"：

find/ls -la：没有按命令的格式化器，走通用流水线；这类"每行都是记录"的输出不会低于 16,000 字符就被截断，所以每行都留下。
git diff：每一行变更都是"事实"，格式化器找不到可安全删除的内容，于是原样放行。
源码文件读取（cat）：代理cat一个文件通常是为了编辑它，流水线会识别出源代码并跳过所有"删行"阶段；省 token 靠去重——第二次读取只有 13 个 token。
Python traceback /.env密钥：路由到安全模式，任意大小都原样放行，且从不写入缓存（测试特意验证重复运行不会产生去重引用）。

这正是"压缩率虚高"的对立面：能压则压，不能压就老实不动。

质量基准测试的回归门槛

这些门槛由 sqz/tests/quality_bench.rs 中的测试强制执行，每次改动都会跑：

✅ 每个场景100% 关键事实召回
✅git show、traceback、密钥场景必须逐字与输入一致
✅ 其余场景必须能字节精确恢复
✅ traceback 与密钥场景绝不落盘
✅ 其余（可压缩）场景聚合压缩率≥ 40%

只要其中任意一条不满足，CI 就红。

压缩率虚高是怎么发生的：基准测试揪出的 7 个 Bug

单看压缩率的基准测试会掩盖这类丢失。sqz 的质量基准第一次运行就暴露了下面这些（现已全部纳入回归测试）：

命令	曾经丢了什么	修复
`npm install`	`3 vulnerabilities`行与`npm audit fix`提示——早期在 "added N packages" 行就提前 return	收集全部汇总行
`docker ps`	COMMAND / CREATED 含空格时列错位，状态、端口落到错误单元格	按表头列偏移切分行，而非按空格 split
`git status`	分支名和 ahead/behind 行	保留起始分支与跟踪行，只删 "up to date"
`pytest`	失败的`file:line`、失败源码行、`1 failed, 41 passed`汇总	专用 pytest 格式化器，保留汇总、`>`、`E`行与位置
`tsc`	`--pretty`格式下全丢，"Found 2 errors" 被通用流水线删掉	两种格式都解析，保留 tsc 自己的汇总行
`cat file.py`	import 和`class`声明被熵截断器判为"低信息"删除	源代码检测关闭删行阶段
任意 passthrough	用不同估算器计数输入/输出，`sqz stats`给未改动的输出记了"节省"	用同一 tokenizer 计数，并在格式化器路径同样应用 16-token 净收益门槛

这些就是"只测压缩率"会漏掉的丢失类型——也是为什么 sqz 把事实保留写进门槛。

复现步骤：自己跑一遍质量基准测试

想验证这些数字，一条命令即可（走真实的sqz二进制路径）：

cargo test -p sqz-cli --test quality_bench -- --nocapture

引擎层还有另一套基准（按命令格式化器 + 内容类型），并用真实的cl100k_baseBPE tokenizer 重新校验，防止chars/4高估压缩率：

cargo test -p sqz-engine benchmarks -- --nocapture cargo test -p sqz-engine cmd_formatter_bench -- --nocapture

相关源码：sqz_engine/src/benchmarks.rs、sqz_engine/src/verifier.rs；完整结果见 BENCHMARKS.md。

这套基准测不到什么（诚实声明）

sqz 也明确列出了质量基准不覆盖的部分，避免过度解读：

代理任务成功率：给定压缩后的输出，模型完成任务的概率是否与原始输出一致。这需要真实模型、任务集和大量运行，也是"最重要的那个数字"。此处用"事实召回"作为确定且低成本的代理指标。
真实 tokenizer 计数：上表用bytes/4估算，[sqz] N/M头用的是 cl100k；cmd_formatter_bench会用真实 BPE 复测，并在chars/4高估 cl100k 超过 10 个百分点时失败。
会话级效应：跨会话去重（那个 13-token 引用）才是真实节省的大头，这部分在 docs/benchmark.md 与sqz stats的真实使用数据中单独度量。
缩写损耗：N-gram 缩写把重复短语替换成«A1»符号加图例；若代理不习惯符号，用--no-abbrev或SQZ_NO_ABBREV=1。

小结

"压缩率虚高怎么破"？sqz 的答案是：别让压缩率单独做主。把 25 个真实场景、359 个关键事实、51.6% 压缩率、100% 事实保留全部锁进一条可重复运行的回归测试，任何一次改动只要丢掉一个事实就会立刻暴露。对新手来说，这套质量基准测试也提供了一个很好的范式——度量压缩时，一定要同时度量信息保留。