AI

Headroom：在 LLM 看到之前先壓縮——可還原、不破壞 KV Cache 的 Token 壓縮層

Monday

本內容僅供參考，詳細使用規則與工具安全性與否，建議要進行相關安全性測試與評估

Agent 的 token 帳單裡，真正「有用的思考」往往只佔一小部分；大宗是工具回傳的 JSON、上萬行的 log、搜尋結果與 RAG 片段。Headroom（headroomlabs-ai/headroom）的做法是在這些內容抵達 LLM 之前先壓縮——而且壓縮是可還原的，模型需要時可以把原文拿回來。專案目前約 75.1k stars、5.8k forks，曾登上 Trendshift「當日第一名專案」，近期持續出現在 AI 開源趨勢榜上。

1. 專案背景與定位

Headroom 採 Apache-2.0 授權，以 Python 為主，另有 TypeScript SDK 與 Rust 元件。官方宣稱可讓 Coding Agent 少用約 20% token、JSON 類內容則可減少 60–95%。

它的定位是「模型前面的壓縮層」，提供四種接法：

  • 函式庫：Python／TypeScript 的 compress(messages)
  • Proxy：headroom proxy --port 8787，不需改程式碼
  • Agent 包裝：headroom wrap <tool> 直接套在 Claude Code、Codex 等 Agent 上，headroom unwrap 即可還原
  • MCP Server：提供 headroom_compress、headroom_retrieve、headroom_stats

月初介紹過的 context-mode 是讓 Agent「不要把資料讀進來」；Headroom 則是「讀進來之前先瘦身」，兩者解決的是同一個問題的不同面向。

2. 技術架構與核心設計

  • 三段式管線：CacheAligner → ContentRouter → CCR，依內容類型分派壓縮器：
    • SmartCrusher：專門處理 JSON
    • CodeCompressor：以 AST 理解原始碼（Python、JS/TS、Go、Rust、Java、C/C++、C#、PHP）
    • Kompress-v2-base：在 Agent 執行軌跡上訓練的 HuggingFace 文字壓縮模型
  • CacheAligner 保護 KV Cache：偵測會破壞供應商 prompt cache 前綴的易變內容；README 強調它「從不改寫 prompt」。
  • Live-zone 壓縮：只壓縮新進來的內容，已凍結的前綴保持位元組完全一致——這點很關鍵，否則省下的 token 可能因為 cache miss 又全部賠回去。
  • CCR 可還原壓縮：原文存在本機，模型需要細節時可以透過工具取回，降低「壓縮掉關鍵資訊」的風險。
  • 跨 Agent 共享記憶：多個 Agent 共用一個記憶庫並自動去重。
  • headroom learn：分析失敗的 session，把修正寫回 Agent 的指令檔。
  • 輸出端節省（選用）：HEADROOM_OUTPUT_SHAPER=1 開啟後，透過冗長度引導與 effort 路由減少輸出 token。

3. 社群熱度與生態採用

約 75.1k stars、3,260 commits，headroom wrap 完整支援 Claude Code、Codex、Aider、Copilot CLI、VS Code Copilot、Cline、Continue、Goose、OpenHands、OpenCode 等十多種 Agent，並能整合 LiteLLM、LangChain、Vercel AI SDK 等框架。

README 公布的數據（離線、使用供應商 tokenizer）：

  • 程式碼搜尋（100 筆結果）：17,199 → 13,597（省 21%）
  • SRE 事故除錯：55,957 → 24,340（省 57%）
  • Codebase 探索：58,801 → 33,895（省 42%）
  • GitHub issue 分類：46,067 → 32,429（省 30%）
  • 延遲：10K token 的 JSON 為 0.21 ms（p50），100K token 約 1.4 ms
  • 準確度（N=100）：GSM8K 0.870 → 0.870；TruthfulQA 0.530 → 0.560（README 自己說明在信賴區間內、視為無差異）

值得肯定的是，README 也坦白指出：節省幅度取決於內容重複程度，一般文章與高密度輸出幾乎壓不下來。

4. 局限性與潛在風險

  • Telemetry 預設開啟：會回傳壓縮比、計數、供應商與模型 ID、作業系統等資訊（README 表示不含 prompt、回應、程式碼或檔案路徑）。可用 HEADROOM_BEACON=off、DO_NOT_TRACK=1 或 HEADROOM_OFFLINE=1 關閉——企業環境建議預設關閉。
  • Proxy 是高敏感節點：以 Proxy 模式部署時，所有 LLM 請求與 API 金鑰都會經過它，部署位置與存取控制必須嚴格管理。
  • 壓縮可能遺漏關鍵細節：雖然有 CCR 可取回原文，但模型必須「知道自己需要取回」才有用；評測樣本數（N=100）也偏小。
  • 安全功能放在付費版：prompt injection 偵測與高風險工具呼叫過濾屬於 Enterprise 功能，開源版沒有這層保護。
  • 平台支援不一致：README 對各平台預編譯 wheel 的說法前後不一，Intel Mac 缺少預編譯的 ONNX Runtime 需要手動處理。
  • headroom learn 會改寫指令檔：自動把「修正」寫進 Agent 指令檔，等於改變 Agent 未來的行為，建議納入版本控管並人工審查。

5. 應用價值與適用場景

最受益的是「工具輸出又大又重複」的工作型態：SRE 除錯、大量 log 分析、API 回應處理、程式碼搜尋與 issue 分類。對於每天大量使用 Coding Agent 的團隊，headroom wrap 是導入成本最低的試驗方式，可以先跑一週比較帳單與任務成功率。

如果你的工作主要是撰寫文件或對話，節省幅度會很有限，不一定值得多一層元件。

Monday 的觀點與架構建議

  • Headroom 最值得學的是「壓縮必須與 KV Cache 共存」的設計意識：只壓縮新內容、保持前綴不變。任何在 prompt 上動手腳的中介層，都應該先回答「這會不會打壞 cache」。
  • 「可還原壓縮」是正確方向：與其賭模型不需要細節，不如保留原文並提供取回工具，讓壓縮成為可逆的決策。
  • 導入時建議：先關閉 telemetry、在測試環境比較壓縮前後的任務成功率、Proxy 只綁定內網並加上驗證。
  • Token 成本最佳化正在從「選便宜的模型」轉向「餵模型更少但更準的 context」，壓縮層很可能成為 Agent 基礎設施的標準元件，與 context-mode、Graphify 這類工具形成互補。

參考來源