Headroom - LLM 上下文壓縮層,節省 60-95% Token 成本

解決什麼

AI Agent 和 RAG 應用每次呼叫 LLM 都要為工具輸出、日誌、檢索結果、程式碼檔案等上下文付費。Headroom 在這些內容送入模型前自動壓縮,針對 JSON 資料可減少 60-95% Token,程式碼場景減少 15-20%,同時保持答案質量不變。專案提供可逆壓縮機制(CCR),原文快取在本地,LLM 需要時可通過 headroom_retrieve 工具還原,兼顧成本與可除錯性。

為何火

1. 直擊痛點:Claude/GPT-4 等模型按 Token 計費,長上下文應用(如多輪對話 Agent、大規模 RAG)成本高昂,Headroom 提供即插即用的壓縮層
2. 多種整合方式:支援 Python/TypeScript 庫呼叫、零程式碼改動的代理模式、MCP 伺服器,還能一鍵包裝 Claude Code/Cursor/Aider 等主流 AI 程式設計工具
3. 內容感知壓縮:ContentRouter 自動識別 JSON/程式碼/文本,分別呼叫 SmartCrusher(JSON 壓縮)、CodeCompressor(AST 壓縮)、Kompress-v2-base(HuggingFace 文本模型),比通用壓縮更高效
4. 跨 Agent 記憶:共享儲存層支援 Claude/Codex/Gemini 等多工具自動去重,headroom learn 可從失敗會話中提煉經驗寫入 CLAUDE.local.md

核心功能

• 三種使用模式:庫呼叫 compress(messages)、代理 headroom proxy --port 8787、Agent 包裝 headroom wrap claude(支援 Claude/Cursor/Aider/Cline 等 10+ 工具)
• 智慧壓縮器:JSON 用 SmartCrusher 刪除冗餘欄位,程式碼用 AST 壓縮保留語義,文本用 Kompress-v2-base 模型(需從 HuggingFace 下載)
• CacheAligner:穩定提示詞字首,提高 Anthropic/OpenAI 等廠商 KV 快取命中率
• 輸出 Token 最佳化:不僅壓縮輸入,還能裁剪模型返回的冗餘內容(如重複程式碼、過度"思考"過程)
• MCP 工具:提供 headroom_compress/headroom_retrieve/headroom_stats 供任意 MCP 客戶端呼叫
• 即時監控:headroom dashboard 顯示 Token 節省統計,headroom perf 效能測試

安裝

# 推薦:uv 全域性工具安裝(自帶 CLI)
uv tool install "headroom-ai[all]"

# 或 pip 安裝(含 CLI)
pip install "headroom-ai[all]"

# TypeScript 僅 SDK(無 CLI)
npm install headroom-ai

# Docker 部署
docker compose up -d  # 需配置 Qdrant + Neo4j

可選依賴:[proxy](代理)、[mcp](MCP 伺服器)、[ml](Kompress 模型)、[vector](HNSW 向量庫,需 C++ 編譯器)。TypeScript 包僅提供 import { compress } 庫,不含 headroom 命令。

適合誰

• AI Agent 開發者:Claude Code/Cursor/Aider 等工具的重度使用者,需降低長對話 Token 成本
• RAG 應用:檢索結果動輒數千 Token,壓縮後可在同等成本下檢索更多文件
• 企業級 LLM 應用:日呼叫量大,Token 成本是主要開支,需本地化壓縮方案(資料不出本地)
• 多模型場景:同時使用 Claude/GPT/Gemini,需跨 Agent 共享記憶和去重

中文使用者注意:Kompress-v2-base 模型託管在 HuggingFace,首次使用需梯子下載;Docker 部署需修改 Neo4j 預設密碼(NEO4J_AUTH);壓縮後的中文文本可讀性取決於模型訓練語料,建議先用 headroom perf 測試實際效果。

社群評價

暫無足量社群公開討論,以下為基於專案本身的中立評估:

專案在 GitHub 獲得 5.9 萬 stars,188 名貢獻者參與,顯示較高關注度。504 個 open issues 反映快速迭代但可能存在穩定性問題。技術亮點在於多層次壓縮策略(JSON/AST/文本分治)和可逆設計,避免傳統壓縮"黑盒"問題。Apache 2.0 許可允許商用,但 Docker 部署依賴 Qdrant 和 Neo4j 外部服務,增加運維複雜度。headroom learn 從失敗會話提煉經驗的功能較新穎,但實際效果需長期驗證。

選型對比

vs Anthropic Prompt Caching:Anthropic 官方快取機制免費但僅限相同字首,Headroom 通過 CacheAligner 最佳化字首穩定性,並額外提供內容壓縮,兩者可疊加使用。

vs LangChain 內建壓縮:LangChain 的 ContextualCompressionRetriever 僅針對檢索結果,Headroom 覆蓋工具輸出、日誌、對話歷史等全場景,且支援代理模式無需改程式碼。

vs 自研壓縮方案:Headroom 提供開箱即用的多壓縮器路由和 MCP 整合,省去從零搭建成本;但引入額外依賴(Qdrant/Neo4j),小團隊可能更傾向輕量級自研。

已知坑

1. 模型下載:Kompress-v2-base 託管在 HuggingFace,國內首次使用需配置映象或梯子
2. Docker 複雜度:預設 Compose 配置需同時執行 Qdrant(向量庫)和 Neo4j(圖資料庫),資源佔用較高,單機測試建議調低副本數
3. Neo4j 預設密碼:.env.example 中 NEO4J_AUTH=neo4j/CHANGEME,生產環境必須修改否則存在安全風險
4. TypeScript 限制:npm 包僅提供 SDK,無 headroom CLI,需結合 Python 環境使用代理或 MCP 功能
5. 壓縮不可逆場景:雖然 CCR 支援還原,但若本地快取丟失(如容器重啟未掛載卷),原文無法恢復
6. 504 個 open issues:快速迭代期,部分功能可能不穩定,建議生產環境鎖定特定版本(如 v0.31.0)

來源: GitHub 倉庫 headroomlabs-ai/headroom + README 技術文件