Headroom 在本機壓縮工具輸出、日誌、檔案與 RAG 片段,再送進 LLM。實測在程式碼搜尋、SRE 除錯等工作上減少 60–95% 的 token,而答案不變。它有三種接入方式:Python / TypeScript 函式庫、零改碼的 HTTP proxy、以及 MCP server。本手冊涵蓋安裝、五個壓縮器、整合介面、一段實戰流程與邊界。
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,答案不變。
環境需求:Python 3.10+。安裝時用 extras 控制要裝哪些功能,常用的是 [all]。最直接的用法是函式庫:在程式裡 import compress,把訊息壓縮後再送給模型。
若不想改任何應用程式碼,啟動 proxy。它是 OpenAI 相容的 drop-in HTTP 代理,把流量導過去即可。MCP server 則用一行安裝,對 agent 暴露 headroom_compress、headroom_retrieve、headroom_stats 三個工具。
[all],Headroom 提供細分的 extras:[proxy]、[mcp]、[ml]、[code]、[memory]、[relevance]、[image]、[agno]、[langchain]、[evals]、[pytorch-mps]。在 Apple Silicon 上可設 HEADROOM_EMBEDDER_RUNTIME=pytorch_mps 把 embedding 運算交給 GPU。
Headroom 把壓縮拆成幾個專門化的壓縮器,各自處理一種內容型態:結構化 JSON、程式碼、自然語言文字、KV-cache 前綴。再加上三種接入點——函式庫、proxy、MCP server——同一組引擎可以從不同層接進你的系統。下面是八張卡片:五個壓縮機制加上三個接入點。
compress(messages) 或 TypeScript await compress(messages, { model })。在程式裡明確控制壓縮點。headroom proxy --port 8787。OpenAI 相容的 drop-in 代理,把流量導過去即可,應用程式碼不用動。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% 的標題數字。
函式庫要你在程式裡呼叫 compress()。若不想動既有程式碼,直接 headroom proxy --port 8787 起一個 OpenAI 相容代理,把流量導過去即可。
CCR 是可還原壓縮:原文快取在本機,可隨需取回,TTL 可設定。需要完整內容(例如回放、稽核)時再 retrieve,平時保持壓縮狀態。
來源 · 官方 README · CCR除了壓 input,設 HEADROOM_OUTPUT_SHAPER=1 再起 proxy,可透過 verbosity steering 與 effort routing 縮減模型輸出。output token 在貴模型上單價約是 input 的五倍。
headroom learn --verbosity 先預覽,加 --apply 才存。它會挖掘失敗的 session,把修正寫進各 agent 專屬的 markdown 檔。
不必每次都 [all]。依需求挑 [proxy]、[mcp]、[code]、[ml]、[langchain] 等,安裝更輕、相依更少。
程式碼壓縮是 AST 感知的,支援 Python、JavaScript、Go、Rust、Java、C++。送進 LLM 的程式碼上下文可以縮得更乾淨。
來源 · 官方 README · CodeCompressorHeadroom 能包住多種 coding agent。對 Claude Code 有特化選項:headroom wrap claude --memory --code-graph,加上跨 session 記憶與程式碼圖。
官方 benchmark 顯示準確度大致保留:GSM8K 數學 0.870、TruthfulQA 0.560、SQuAD v2 在 19% 壓縮率下達 97%。仍建議在你自己的工作負載上量一次。
來源 · 官方 README · benchmarks以下示範一段流程:啟動 proxy、用 MCP 工具壓縮一次程式碼搜尋結果、查 stats 看實際縮減,接著用 output shaper 連模型輸出也一起縮。數字取自官方 benchmark:程式碼搜尋 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 output-savings 與 stats 在自己的流量上量一次。
基本壓縮跑通之後,有幾個方向能把 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 與更新紀錄。