Headroom Transforms 深度解析SmartCrusher 统计压缩、CacheAligner 缓存前缀对齐与 ContentRouter 智能路由【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroomHeadroomheadroom通过一组可组合的transforms变换层在 LLM 请求发出前对上下文做 token 级压缩用 SmartCrusher 对 JSON 工具输出做统计压缩用 CacheAligner 检测并告警会破坏提示词缓存前缀的易变内容再用 ContentRouter 把不同内容类型路由到最优压缩器。本文基于仓库中的 wiki/transforms.md 参考文档与headroom/transforms/的实际源码展开读完你可以掌握每个 transform 的作用边界、完整的配置参数含源码中的真实默认值、在 pipeline 中的执行顺序以及所有 transform 共同遵循的安全保证。1. Transform 层在 Headroom 中的定位Headroom 的核心命题是压缩进入 LLM 的工具输出、日志、文件与 RAG 块。所有压缩逻辑都实现在 headroom/transforms/ 包中包采用惰性导出设计__init__.py只声明符号表_LAZY_EXPORTS首次访问某个类时才通过__getattr__真正导入对应模块从而避免 import 头文件时拉起 tree-sitter、torch 等重依赖。headroom/transforms/ ├── base.py # Transform 协议 ├── pipeline.py # TransformPipeline 编排 ├── smart_crusher.py # JSON 数组统计压缩Rust 内核 PyO3 桥 ├── cache_aligner.py # 缓存前缀易变内容检测 ├── content_router.py # 内容类型路由 ├── content_detector.py # 内容类型检测 ├── code_compressor.py # AST 代码压缩tree-sitter ├── kompress_compressor.py # KompressModernBERTML 压缩 ├── search_compressor.py # grep/ripgrep 结果压缩 ├── log_compressor.py # 日志压缩 └── ...headroom/transforms/__init__.py的__all__导出了全部公开压缩器SmartCrusher、SearchCompressor、LogCompressor、TabularCompressor、DiffCompressor、CodeAwareCompressor、ContentRouter、CacheAligner、TransformPipeline等HTMLExtractor 仅在安装了trafilatura时才条件性导出。2. SmartCrusher面向 JSON 工具输出的统计压缩2.1 工作原理SmartCrusher 是 Headroom 的默认工具输出压缩器headroom/config.py 中enabled: bool True # Enabled by default — sole tool-output compressor。它分析 JSON 数组选择性保留重要条目首/尾条目—— 保留分页与新近性上下文错误条目—— 错误状态 100% 保留异常值—— 偏离均值超过 2 个标准差的统计离群点相关条目—— 通过 BM25/嵌入对用户的查询打分RelevanceScorer变化点—— 数据中的显著跳变关键设计原则是schema-preserving输出只包含原数组里的条目不包装、不生成文本、不新增元数据键见 headroom/transforms/smart_crusher.py 中SmartCrusherConfig的 docstring。2.2 完整配置参数以当前源码为准headroom/transforms/smart_crusher.py 中的SmartCrusherConfig字段与 Rust 端配置逐字节对齐。wiki 参考文档中出现的早期字段keep_first、keep_last、relevance_threshold、anomaly_std_threshold等在当前实现中已演进为first_fraction/last_fraction/variance_threshold等字段若向 dataclass 传入已废弃字段名Python 会直接抛TypeError请以源码为准参数默认值说明enabledTrue总开关默认启用min_items_to_analyze5小于该规模的数组不做统计分析min_tokens_to_crush200超过该 token 数才压缩variance_threshold2.0变化点/异常检测的标准差倍数uniqueness_threshold0.1低于该值视为近常数列similarity_threshold0.8相似字符串聚类的相似度阈值max_items_after_crush15压缩后最多保留的条目数preserve_change_pointsTrue保留显著变化点factor_out_constantsFalse默认关闭——保证输出 schema 不变include_summariesFalse默认关闭——不生成摘要文本use_feedback_hintsTrue使用 TOIN 学习到的模式反馈toin_confidence_threshold0.5TOIN 反馈置信度门槛dedup_identical_itemsTrue去重完全相同的条目first_fraction0.3保留头部条目的比例对应旧版keep_firstlast_fraction0.15保留尾部条目的比例对应旧版keep_lastlossless_min_savings_ratio0.15无损 Table/CSV 紧凑化路径战胜有损路径所需的最小节省比lossless_onlyFalse严格无损模式任何会输出 CCR 标记的路径改为不压缩compaction_core_field_fraction0.8出现在 ≥80% 行中的字段视为核心列compaction_heterogeneous_core_ratio0.6低于该比例的核心键占比视为异构数组compaction_max_flatten_inner_keys6嵌套均匀展平的内层键数上限compaction_min_buckets/compaction_max_buckets2/8判别字段分桶数的有效区间audit_safeFalse审计安全模式opt-in见 2.5 节protected_patternsNone受保护行的字符串/正则匹配列表fail_closed_on_protected_lossTrue受保护行无法保全时失败关闭返回原始数组构造方式wiki 原始示例参数名需按上表更新from headroom import SmartCrusherConfig config SmartCrusherConfig( min_tokens_to_crush200, # 仅当超过 200 tokens 才压缩 max_items_after_crush50, # 最多保留 50 条 preserve_change_pointsTrue, variance_threshold2.0, # 保留偏离均值 2 个标准差的条目 )2.3 使用示例与什么被保留from headroom import SmartCrusher, SmartCrusherConfig crusher SmartCrusher(SmartCrusherConfig()) # Before: 1000 条搜索结果约 45,000 tokens tool_output {results: [...1000 items...]} # After: 约 50 条重要条目约 4,500 tokens—— 约 90% 缩减 compressed crusher.crush(tool_output)按 wiki/transforms.md 的保留规则表类别保留比例原因错误条目100%调试关键信息首 N 条100%上下文/分页尾 N 条100%新近性异常值全部非常规数值很重要相关条目Top K匹配用户查询其余采样统计代表性headroom/config.py 的文档还补充了两点注意事项统计分析每个工具输出增加约 5–10ms 开销变化点检测使用固定窗口5 条可能错过非常渐进的变化。若数据关键可以调大max_items_after_crush、调低variance_threshold如 1.5来捕捉更多变化点。2.4 实现细节Rust 内核 CCR 行丢弃哨兵从源码结构看SmartCrusher 的压缩主体已经完成 Rust 化Python 侧的SmartCrusher类是PyO3 桥接壳headroom._core.SmartCrusher由crates/headroom-py构建是硬导入没有 Python 回退路径两个实现的字节级一致性曾对 tests/parity/fixtures/smart_crusher/ 下的 17 个录制夹具做过校验见 headroom/transforms/smart_crusher.py 的模块头注。Rust 核心自带 388 个单元测试与属性测试位于 crates/headroom-core/。压缩过程中被丢弃的行不是无声消失。有损路径会向保留数组追加一个哨兵对象{_ccr_dropped: ccr:HASH N_rows_offloaded}LLM 在 prompt 中看到该标记后可通过 CCR 检索工具取回原始内容。下游代码若按统一 schema 遍历数组需要跳过哨兵——模块提供了现成工具函数from headroom.transforms.smart_crusher import is_ccr_sentinel, strip_ccr_sentinels items strip_ccr_sentinels(raw_items) # 过滤掉 _ccr_dropped 哨兵对象此外CCRConfig的enabledFalse或inject_retrieval_markerFalse会同时关闭 Rust 压缩器的enable_ccr_marker——既不发标记文本也不写 CCR 存储没有 prompt 可引用的载荷存储它本身就是意外的副作用。2.5 审计安全模式针对合规/审计场景audit_safeTrueprotected_patterns可保证匹配的行逐字存活在压缩输出中——既不被采样掉也不被替换成ccr:...标记。该字段不进入 Rust 配置是纯 Python 侧的调用 Rust 前后处理当fail_closed_on_protected_lossTrue默认时若受保护行无法完整保全直接失败关闭、返回未压缩的原始数组。3. CacheAligner让缓存前缀稳定3.1 问题动态内容如何击穿提示词缓存LLM 提供商按请求前缀做缓存。只要前缀里有任何每天变化的内容缓存就整体失效You are helpful. Today is January 7, 2025. # 日期每天变 前缀不命中wiki/transforms.md 给出的缓存命中率改善参考原文档数据场景处理前处理后prompt 内嵌日期0% 命中约 95% 命中动态用户上下文约 10% 命中约 80% 命中稳定的 prompt约 90% 命中约 95% 命中3.2 当前实现detector-only绝不改写消息需要注意当前源码中的CacheAligner已从重写型演进为纯检测型 transform。headroom/transforms/cache_aligner.py 的模块文档明确说明早期的把动态内容从 system prompt 里剥离并搬到末尾的写法违反了不变式 I2缓存热区——system prompt——永不改动该路径已被移除。现在的行为是结构性检测全部无正则用 stdlibuuid模块识别 UUID仅接受 36 字符带连字符的标准形避免把无连字符形误判为 MD5用datetime.fromisoformat识别 ISO 8601 时间戳用三段 base64url 点分隔的形状检查识别 JWT不验签用长度字符集32/40/64 位十六进制识别 MD5/SHA1/SHA256 摘要输出可观察性告警在 system 消息中发现易变内容时输出面向用户的 warning 日志CacheAligner: detected volatile content in system prompt (...)提示把动态值移出 system prompt 以恢复缓存命中计算稳定前缀度量填充CachePrefixMetricsstable_prefix_bytes、stable_prefix_tokens_est、stable_prefix_hash、prefix_changed及上一轮哈希并把stable_prefix_hash:hash记入markers_inserted供仪表板追踪前缀漂移对齐评分get_alignment_score()给出 0–100 的粗粒度信号——每条易变发现扣 10 分仅用于仪表板展示不改变任何行为。from headroom.transforms import CacheAligner aligner CacheAligner() result aligner.apply(messages, tokenizer) # result.messages 与输入字节一致仅深拷贝隔离 # result.warnings 中携带易变内容告警 # result.cache_metrics 中携带 stable_prefix_hash / prefix_changed一个容易踩的坑headroom/config.py 中CacheAlignerConfig.enabled的默认值是False注释写明prefix stability gains are marginal in practice且当前 transform 已不再消费 wiki 旧示例里的extract_dates/normalize_whitespace/stable_prefix_min_tokens参数。若你的目标是缓存稳定当前实现给出的工程建议是把动态值日期、会话 ID、用户上下文路由到 live zone最新的用户轮次而不是留在 system prompt 中。4. 上下文管理Headroom 从不删除历史消息wiki 参考文档对此有一条重要边界声明wiki/transforms.md上下文管理在 pipeline 内部自动完成且只压缩live zone最新用户消息 最新工具结果/工具输出类型感知、可通过 CCR 可逆缓存热区system prompt、工具定义、旧轮次永不被改动从而保护 provider 的提示词缓存。早期基于位置的RollingWindow与基于打分的IntelligentContextManager已被移除。headroom/transforms/pipeline.py 的类注释与之一致Phase B PR-B1 retired the IntelligentContextManager / RollingWindow drop messages from history stage. Live-zone-only compression is the sole strategy going forward — message-list mutation no longer happens in the pipeline.5. LLMLingua 已退役ML 压缩由 KompressModernBERT承担wiki 参考文档声明LLMLinguaCompressor、LLMLinguaConfig、headroom-ai[llmlingua]extra 与--llmlinguaproxy 标志已在 0.9.x 退役ML 压缩改由KompressModernBERT提供pip install headroom-ai[llmlingua]不再可解析。pyproject.toml 中的注释佐证了这一点The legacy [llmlingua] extra was removed in 0.9.x — no live code path used it. Use [ml] for the supported ML compression dependencies.pip install headroom-ai[ml] # KompressModernBERTML 压缩依赖[ml]extra 实际钉住torch2.12.1macOS 15 x86_64 除外、transformers5.5.0,6.0、huggingface-hub1.5.0,2.0。Kompress 作为 live-zone pipeline 的 Transform 4 运行架构细节见 wiki/ARCHITECTURE.md早期手拼TransformPipeline([..., LLMLinguaCompressor(), ...])的配方不再受支持。6. CodeAwareCompressor基于 AST 的代码压缩可选6.1 选型与安装Transform适用内容速度压缩率SmartCrusherJSON 数组~1ms70-90%CodeAwareCompressor源代码~10-50ms40-70%KompressML任意文本50-200ms80-95%核心优势输出语法恒有效、保留关键结构imports、函数签名、类型标注、错误处理、多语言支持Python、JavaScript、TypeScript、Go、Rust、Java、C、C、轻量约 50MB 对比 ML 压缩器约 1GB。pip install headroom-ai[code] # 引入 tree-sitter-language-packpyproject.toml 中该 extra 对版本有明确钉扎对应 issue #1216tree-sitter-language-pack0.10.0,1.0且tree-sitter0.25.2,0.27——因为 language-pack 1.0 移除了内置 tree-sitter 并切换到不兼容的内部节点 API代码压缩器的节点遍历逻辑依赖旧 API。6.2 配置与示例配置类为CodeCompressorConfig语言枚举CodeLanguage、docstring 策略枚举DocstringMode均在 headroom/transforms/code_compressor.py 中定义from headroom.transforms import CodeAwareCompressor, CodeCompressorConfig, DocstringMode config CodeCompressorConfig( preserve_importsTrue, # 永远保留 imports preserve_signaturesTrue, # 永远保留函数签名 preserve_type_annotationsTrue, # 保留类型标注 preserve_error_handlersTrue, # 保留 try/except 块 preserve_decoratorsTrue, # 保留装饰器 docstring_modeDocstringMode.FIRST_LINE, # FULL / FIRST_LINE / REMOVE target_compression_rate0.2, # 保留约 20% 的 token max_body_lines5, # 每个函数体保留的行数 min_tokens_for_compression100, # 小于该规模直接跳过 language_hintNone, # None 时自动检测 ) compressor CodeAwareCompressor(config) code import os from typing import List def process_items(items: List[str]) - List[str]: Process a list of items. results [] for item in items: if not item: continue processed item.strip().lower() results.append(processed) return results result compressor.compress(code, languagepython) print(result.compressed) # imports/签名/docstring 首行保留函数体折叠 print(result.compression_ratio) # 约 55% print(result.syntax_valid) # True —— 输出保证可解析语言支持分两个层级wiki 参考文档Tier 1 为 Python、JavaScript、TypeScript完整 AST 分析Tier 2 为 Go、Rust、Java、C、C函数体压缩。6.3 内存管理tree-sitter 解析器是懒加载的用完后可以显式释放from headroom.transforms import is_tree_sitter_available, unload_tree_sitter print(is_tree_sitter_available()) # True/False unload_tree_sitter() # 释放解析器占用的内存对应实现位于 headroom/transforms/code_compressor.py。7. ContentRouter智能压缩编排器ContentRouter 负责内容进、最优压缩器出先检测内容类型JSON、代码、日志、搜索结果、纯文本再参考来源提示文件路径、工具名等高置信信号把每个 section 路由到对应压缩器并记录透明的路由决策日志。实现位于 headroom/transforms/content_router.py模块 docstring 概括了路由策略有来源提示时优先用来源提示置信度最高检查混合内容——拆分后对每个 section 分别路由再重组检测内容类型JSON、代码、search、日志、文本路由到对应压缩器并附带路由元数据返回。from headroom.transforms import ContentRouter router ContentRouter() result router.compress(content) print(result.strategy_used) # 本次使用的策略枚举 print(result.routing_log) # 路由决策记录含 token 前后对比、置信度7.1 策略枚举比 wiki 表格更全当前 headroom/transforms/content_router.py 的CompressionStrategy枚举已扩展到 13 个值wiki 参考文档的表格是早期快照其中LLMLINGUA策略已随集成一起退役策略用途压缩器CODE_AWARE源代码CodeAwareCompressorSMART_CRUSHERJSON 数组SmartCrusherSEARCHgrep/find 输出SearchCompressorLOG日志文件LogCompressorKOMPRESS纯文本MLKompressCompressor[ml]extraTEXT普通文本TextCompressorDIFFdiff 内容DiffCompressorHTML网页内容HTMLExtractor需 trafilaturaTABULAR表格数据TabularCompressorCONFIG配置文件ConfigCompressorMIXED混合内容拆分后分路PASSTHROUGH小内容不压缩内容检测完全基于内容本身源代码按语法模式/缩进/关键词识别JSON 数组按结构识别搜索结果按file:line:模式识别日志按时间戳与日志级别模式识别其余回退为纯文本。无需人工提示。另有两处源码级防护值得注意_is_already_compressed()会拒绝二次压缩仍携带 CCR 标记Retrieve more: hash/ccr:等的文本——二次压缩会把标记本身当成原文哈希入店导致真实字节永远取不回Prometheus 标签只接受^[a-z0-9_]{1,32}$形式的 providerkind防止标签基数爆炸。7.2 TOIN 集成ContentRouter 会把所有策略的压缩记录写入 TOINTool Output Intelligence Network用于跨用户学习用户通过 CCR 取回原文时TOIN 学到哪些压缩需要更激进地展开TOIN 为每种内容类型构建签名以改进后续压缩。SmartCrusher 侧同样保留了这个回路——crush()在真实发生压缩strategy ! passthrough后调用toin.record_compression()见 headroom/transforms/smart_crusher.py 的模块状态注。8. TransformPipeline组合与顺序headroom/transforms/pipeline.py 中的TransformPipeline编排多个 transform。不传自定义列表时默认顺序为CacheAligner—— 缓存前缀归一/检测为缓存命中铺路ContentRouter—— 内容感知的智能压缩内部路由到 Kompress / SmartCrusher / CodeCompressor 等。from headroom import TransformPipeline pipeline TransformPipeline(config) result pipeline.transform(messages) print(fSaved {result.tokens_saved} tokens)wiki 参考文档给出的推荐顺序CacheAligner → SmartCrusher → Kompress 兜底长文本在当前实现中的对应形态即上述两步SmartCrusher/Kompress 的调用由 ContentRouter 按内容类型分发而非手工拼接在 pipeline 列表里。pipeline 还内建了若干工程护栏waste-signal 诊断仅在压缩省下超过 100 tokens 时运行且超过 100,000 tokens 的超大 transcript 会跳过诊断避免重复解析原消息触发 Anthropic 压缩超时、让已算好的压缩被丢弃见 headroom/transforms/pipeline.pyspan 同时输出 OpenTelemetry GenAI 语义约定的gen_ai.request.model属性。9. 安全保证所有 transform 的共同底线wiki/transforms.md 汇总的五条安全规则在源码中均有对应落点绝不移除人类内容—— user/assistant 文本神圣不可侵犯绝不破坏工具配对—— tool call 与 tool result 保持成对解析失败即 no-op—— 畸形内容原样通过保留新近性—— 最近 N 轮永远保留错误条目 100% 保留—— 错误项永不被丢弃。此外还有两条从源码可以确认的结构性不变式I2 不变式——缓存热区system prompt、工具、旧轮次永不被 transform 改动CacheAligner 的apply返回字节等价的消息深拷贝以及CCR 可逆性——live zone 的任何有损压缩都留下检索标记原文可经 CCR 工具取回。10. 延伸阅读架构总览与 live-zone pipelineKompress 作为 Transform 4 的位置wiki/ARCHITECTURE.md压缩机制总述wiki/compression.md文本压缩细节wiki/text-compression.mdCCR可逆检索机制wiki/ccr.mdRust 核心实现与测试crates/headroom-core/SmartCrusher 字节级一致性夹具tests/parity/fixtures/smart_crusher/【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考