在 token 進入 LLM 前, 先做一層本機壓縮。
Headroom 解決一個具體的成本問題:AI agent 要處理大量冗長的上下文——指令輸出、API 回應、日誌、檢索到的文件。每一個 token 都要花錢,而在較貴的模型上,output token 的單價約為 input 的五倍。Headroom 在這些內容送進 LLM 之前,先在你的本機把它們壓縮掉。
它是一個 Python 專案(Apache-2.0 授權),以 headroom-ai 套件發布,並提供三種接入方式:函式庫(Python 與 TypeScript)、proxy(零改碼、OpenAI 相容的 HTTP 代理)、MCP server(把壓縮功能當成工具暴露給 agent)。三者共用同一組壓縮引擎,你可以依專案改動的成本選擇接入點。
壓縮本身由幾個專門化的壓縮器分工:SmartCrusher 壓 JSON、CodeCompressor 做 AST 感知的程式碼壓縮、Kompress-base 是在 agentic trace 上訓練的文字壓縮模型、CacheAligner 穩定前綴以提高 KV-cache 命中、CCR 做可還原壓縮(原文快取在本機、可隨需取回)。官方一句話定位:壓縮工具輸出、日誌、檔案與 RAG 片段,減少 60–95% 的 token,答案不變。
工具輸出 / 日誌 / RAG
本機壓縮器
compress()
LLM
需要時 retrieve 還原
壓縮工具輸出、日誌、檔案與 RAG 片段,在它們進入 LLM 之前。token 少 60–95%,答案不變。
函式庫、proxy、MCP, 挑一種接入。
環境需求:Python 3.10+。安裝時用 extras 控制要裝哪些功能,常用的是 [all]。最直接的用法是函式庫:在程式裡 import compress,把訊息壓縮後再送給模型。
# Python 函式庫(裝齊全部 extras)
pip install "headroom-ai[all]"
# 在程式裡壓縮訊息後再送給模型
from headroom import compress
compressed = compress(messages, model="...")
# TypeScript / Node 同樣有函式庫
npm install headroom-ai
await compress(messages, { model })零改碼:用 proxy
若不想改任何應用程式碼,啟動 proxy。它是 OpenAI 相容的 drop-in HTTP 代理,把流量導過去即可。MCP server 則用一行安裝,對 agent 暴露 headroom_compress、headroom_retrieve、headroom_stats 三個工具。
# 零改碼的 HTTP proxy(OpenAI 相容)
headroom proxy --port 8787
# 安裝 MCP server,暴露三個壓縮工具
headroom mcp install壓縮怎麼運作。
Headroom 把壓縮拆成幾個專門化的壓縮器,各自處理一種內容型態:結構化 JSON、程式碼、自然語言文字、KV-cache 前綴。再加上三種接入點——函式庫、proxy、MCP server——同一組引擎可以從不同層接進你的系統。下面是八張卡片:五個壓縮機制加上三個接入點。
Compressor · 01
SmartCrusher
壓縮 JSON
針對結構化 JSON 的壓縮器。API 回應、工具輸出常是大塊 JSON,這層專門縮減它們。
Compressor · 02
CodeCompressor
AST 感知程式碼壓縮
以 AST 為基礎壓縮程式碼,涵蓋 Python、JavaScript、Go、Rust、Java、C++ 六種語言。
Compressor · 03
Kompress-base
文字壓縮模型
一個發布在 HuggingFace 的模型,在 agentic trace 上訓練,用於壓縮自然語言文字。
Compressor · 04
CacheAligner
穩定 KV-cache
穩定前綴以提高 KV-cache 命中率。命中越多,重算越少,延遲與成本一起降。
Compressor · 05
CCR
可還原壓縮
reversible compression。原文快取在本機,可隨需取回,TTL 可設定。需要完整內容時再還原。
Entry · 06
Library
函式庫接入
Python compress(messages) 或 TypeScript await compress(messages, { model })。在程式裡明確控制壓縮點。
Entry · 07
Proxy
零改碼 HTTP 代理
headroom proxy --port 8787。OpenAI 相容的 drop-in 代理,把流量導過去即可,應用程式碼不用動。
Entry · 08
MCP server
agent 工具
headroom mcp install,暴露 headroom_compress、headroom_retrieve、headroom_stats 三個工具給 agent。
三種接入方式,怎麼選
| 接入方式 | 啟動指令 / 介面 | 需要改碼 | 適用情境 |
|---|---|---|---|
Library | compress(messages, model=…) | 是(明確呼叫) | 要精準控制壓縮點 |
Proxy | headroom proxy --port 8787 | 否 | 不想動既有程式碼 |
MCP server | headroom mcp install | 否(工具呼叫) | 讓 agent 自行壓縮 / 取回 |
實務上的八條要點。
以下整理自 Headroom 官方 README 與文件站。重點是依你的接入成本選對方式、需要時把原文取回、以及在自己的工作負載上量測實際縮減,而不是只看 60–95% 的標題數字。
不想改碼就用 proxy
函式庫要你在程式裡呼叫 compress()。若不想動既有程式碼,直接 headroom proxy --port 8787 起一個 OpenAI 相容代理,把流量導過去即可。
來源 · 官方 README
CCR 讓你把原文取回
CCR 是可還原壓縮:原文快取在本機,可隨需取回,TTL 可設定。需要完整內容(例如回放、稽核)時再 retrieve,平時保持壓縮狀態。
來源 · 官方 README · CCR
output shaper 連模型輸出也縮
除了壓 input,設 HEADROOM_OUTPUT_SHAPER=1 再起 proxy,可透過 verbosity steering 與 effort routing 縮減模型輸出。output token 在貴模型上單價約是 input 的五倍。
來源 · 官方 README · output shaper
headroom learn 從失敗 session 學設定
headroom learn --verbosity 先預覽,加 --apply 才存。它會挖掘失敗的 session,把修正寫進各 agent 專屬的 markdown 檔。
來源 · 官方 README · learn
只裝你需要的 extras
不必每次都 [all]。依需求挑 [proxy]、[mcp]、[code]、[ml]、[langchain] 等,安裝更輕、相依更少。
來源 · 官方 README · extras
CodeCompressor 覆蓋六種語言
程式碼壓縮是 AST 感知的,支援 Python、JavaScript、Go、Rust、Java、C++。送進 LLM 的程式碼上下文可以縮得更乾淨。
來源 · 官方 README · CodeCompressor
包 claude 時帶 --memory --code-graph
Headroom 能包住多種 coding agent。對 Claude Code 有特化選項:headroom wrap claude --memory --code-graph,加上跨 session 記憶與程式碼圖。
來源 · 官方 README · agent wrapping
準確度有實測,但要自己驗
官方 benchmark 顯示準確度大致保留:GSM8K 數學 0.870、TruthfulQA 0.560、SQuAD v2 在 19% 壓縮率下達 97%。仍建議在你自己的工作負載上量一次。
來源 · 官方 README · benchmarks
從起 proxy 到看見 token 真的少掉。
以下示範一段流程:啟動 proxy、用 MCP 工具壓縮一次程式碼搜尋結果、查 stats 看實際縮減,接著用 output shaper 連模型輸出也一起縮。數字取自官方 benchmark:程式碼搜尋 100 筆結果從 17,765 壓到 1,408 token(省 92%)。
$ pip install "headroom-ai[all]"
$ headroom proxy --port 8787
ok: Headroom proxy listening on http://127.0.0.1:8787
$ headroom mcp install
hl: 17,765 → 1,408 tokens · saved 92%
ok: restored original from local cache
$ export HEADROOM_OUTPUT_SHAPER=1
$ headroom proxy --port 8787
$ headroom output-savings
ok: estimated output reduction reported with confidence intervals
程式碼搜尋 100 筆結果:17,765 → 1,408 token,省 92%。準確度大致保留。
這段流程為什麼成立
token 變少,靠的不是丟資訊,而是在送進 LLM 之前先在本機做型態感知的壓縮:JSON 走 SmartCrusher、程式碼走 CodeCompressor、文字走 Kompress-base、前綴走 CacheAligner。需要完整內容時,CCR 再把原文從本機快取取回。資料流是受控的:壓縮與還原都發生在你的機器上。
值得留意的是 output shaper 改的是 prompt 與 effort。它透過 verbosity steering 與 effort routing 縮減輸出 token,但會動到 system prompt 與思考量。上線前在你自己的工作負載上量一次品質與縮減,再決定要不要長期開。
壓縮很省, 先弄懂邊界再接上。
把 Headroom 接進你的工作流。
基本壓縮跑通之後,有幾個方向能把 Headroom 接得更深:輸出端縮減、從失敗中學設定、各家框架的整合介面、以及包住你日常用的 coding agent。
進階設定地圖
1. 開 output shaper 縮輸出。export HEADROOM_OUTPUT_SHAPER=1 後起 proxy。它用 verbosity steering 在 system prompt 加上簡潔指引、用 effort routing 在例行步驟(如處理 tool 結果)降低思考量,並可用 headroom output-savings 量測估計縮減。
2. 用 learn loop 自動調設定。headroom learn --verbosity 先預覽,加 --apply 才存最佳設定。它挖掘失敗的 session,把修正寫進各 agent 專屬的 markdown 檔。
**3. 接你的框架。**整合介面包含:Anthropic SDK withHeadroom(new Anthropic())、OpenAI SDK withHeadroom(new OpenAI())、LangChain HeadroomChatModel(your_llm)、Vercel AI SDK 的 wrapLanguageModel() middleware、以及 LiteLLM 的 HeadroomCallback()。
**4. 包住你的 coding agent。**Headroom 能包 Claude Code、Codex、Cursor、Aider、Copilot CLI、OpenClaw、Cortex Code。對 Claude Code 有特化:headroom wrap claude --memory --code-graph,加上跨 session 記憶與程式碼圖。
**5. 用 extras 矩陣控制安裝面。**依需求挑 [proxy]、[mcp]、[ml]、[code]、[memory]、[relevance]、[langchain] 等;Apple Silicon 上設 HEADROOM_EMBEDDER_RUNTIME=pytorch_mps 把 embedding 交給 GPU。
官方資源
① 官方文件站——安裝、壓縮器、整合介面、benchmark 的完整說明。 ② github.com/headroomlabs-ai/headroom——原始碼、README、issue 與更新紀錄。
壓縮工具輸出、日誌、檔案與 RAG 片段,在它們進入 LLM 之前。Library、proxy、MCP server 三選一。