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 技术文档