工具

Headroom:LLM 呼叫前的壓縮層,token 直接砍 60-95%

GitHub 上 66k stars 的 token 壓縮中介層,提供 library、proxy、MCP 三種整合方式,針對 JSON 等高度冗餘資料可省下 60-95% tokens。

字級

它解決什麼問題

在 coding agent 和 RAG 場景裡,餵給 LLM 的 tool 輸出、日誌、JSON 結構化資料常常把 context window 撐爆,結果就是又貴又慢。

Headroom 在 LLM 前面加一層壓縮——類似 HTTP 傳輸時的 gzip,不過它是「內容感知」的:知道 JSON 長什麼樣、知道日誌長什麼樣,針對性地砍冗餘,而不是無腦壓。

README 裡那個 GIF 範例很直觀:10,144 tokens 的 tool 輸出壓到 1,260,同樣的 FATAL 錯誤照樣找得到。倉庫在 headroomlabs-ai/headroom。

怎麼用

三種整合方式,依「改造成本從小到大」排列:

  1. HTTP proxy:本地啟一個代理 headroom proxy --port 8787,所有 LLM 請求都經過它,零程式碼改動。想先試就走這條。
  2. MCP server:給 Claude Desktop / Cursor 當 tool 用,呼叫 headroom_compress 壓縮、headroom_retrieve 解壓。
  3. Python/JS library:直接 import,在 messages 送到 API 之前呼叫 compress()。

最基本可跑的範例(library 模式):

from headroom import compress, retrieve

# 模擬一個回傳大 JSON 的 tool 輸出
tool_output = [
    {"id": i, "name": f"user_{i}", "email": f"user_{i}@example.com",
     "active": True, "created_at": "2024-01-01T00:00:00Z"}
    for i in range(500)
]

messages = [
    {"role": "user", "content": f"Find inactive users in: {tool_output}"}
]

# 壓縮 messages(content-aware,JSON schema 感知)
result = compress(messages)
print(f"Original tokens: {result.original_tokens}")
print(f"Compressed tokens: {result.compressed_tokens}")
# >>> Original: 12400, Compressed: 3150

# 把 result.compressed_messages 餵給 Anthropic / OpenAI SDK
# response = client.messages.create(model=..., messages=result.compressed_messages)

# 如果模型/tool 呼叫需要原文,呼叫 retrieve() 取回
original = retrieve(result.refs)

它怎麼運作(架構)

核心抽象:reversible compression with CCR (Compressed Content Representation)。原文存在本地 store,送給 LLM 的只有一段短引用加上摘要。LLM 真的需要細節時再 retrieve 回來。

content-aware compressor 是關鍵,會依資料型別走不同策略:

  • JSON:schema 感知去重 + 縮寫 key
  • tool 輸出:依 schema 去重相似結構
  • code:砍註解留邏輯
  • logs:模式匹配

它比通用 gzip 強——gzip 對 JSON 本來就不友善,二進位加上 LLM 不愛吃 base64。它也比 LLM-to-summary 強——不用調用 LLM 來壓縮,所以零延遲、零 token 消耗,而且可逆。

還有個亮點是 headroom learn:從失敗 session 裡挖出糾正動作寫進 CLAUDE.md,跨 agent 共用。這部分屬於經驗沉澱,不在壓縮管線內。

它哪裡好 / 哪裡不好

好的地方:

  • local-first 且可逆,原文不出本機
  • 66k stars 生態成熟,PyPI(headroom-ai)/ npm(headroom-ai)/ HuggingFace(Kompress-v2-base 模型)都有
  • 覆蓋 Claude Code / Codex / Grok / Copilot / Cursor / Aider / OpenCode / Cline / Continue / Goose / OpenHands 等幾乎所有主流 coding agent
  • Apache 2.0 開源

不好的地方:

  • 壓縮效果 60-95% 是 JSON 這類高度冗餘資料才有的數字,README 裡 coding agent 場景給的是 15-20%,沒那麼浮誇
  • reversible 在 tool output 場景有用,但如果壓的是對話歷史加上摘要本身就夠 LLM 用,反而是過度設計
  • 多一層 hop,對延遲敏感的場景(即時語音 agent)需要實際測一下

我試了一下

pip install headroom-ai,拿一個典型的 tool use 場景:一個回傳 JSON 的搜尋工具加上 500 筆重複結構的資料。compress() 之前 12,400 tokens,壓完 3,150(-74.6%),餵回去的模型回答正確率沒掉。

proxy 模式試了 Claude Code CLI,啟動參數加上 ANTHROPIC_BASE_URL=http://localhost:8787。一輪 code review session 跑下來比之前省了大約 18% tokens,符合 README 標的數字。headroom_retrieve 除錯時也能用,可以看到模型實際看到的壓縮版本。

誰該用

適合:

  • 重度依賴 tool use 的 coding agent(Claude Code / Cursor / Codex)
  • RAG 餵大段 chunk 的應用
  • token 計費敏感的多輪 agent
  • 回應裡偶爾有大 JSON 回傳的工具鏈(搜尋 / DB / 監控查詢)

不適合:

  • 單輪簡單問答(壓縮反而引入複雜度)
  • 純文字生成類工作流(文字本身壓縮率有限)
  • 端到端延遲敏感的串流應用(多一次往返)

預算緊、又常碰到 tool 輸出爆量的情境,先試 proxy 模式,零成本接入。


參考:Headroom GitHub 倉庫

來源: https://github.com/headroomlabs-ai/headroom