Headroom

[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”它值不值得用、怎么用、什么时候不用”。 底层概念链接到 related_concepts；真实项目落地链接到 used_in_projects。

开源 LLM 上下文压缩层——在应用和 LLM 提供商之间拦截消息，压缩 token 用量，同时保持回答准确度。本地运行，可逆压缩。

为什么需要它

当你使用 LLM 构建应用（Agent、代码助手、多轮对话）时，上下文窗口很快被工具输出、日志、文件内容占满。每次请求的 token 费用随对话轮次线性增长，长对话甚至直接触及上下文上限导致截断。Headroom 的定位就是解决这个问题：它作为中间层拦截发送给 LLM 的消息，执行三阶段压缩管线（Cache Aligner → 内容压缩 → 缓存优化），将 token 消耗降低 40-70%，然后转发压缩后的请求给 LLM 提供商，返回的响应不做修改直接透传给调用方。整个压缩过程是可逆的——你可以还原出原始消息。

核心优势

• 可逆压缩：不同于粗暴截断，压缩后仍可还原原始消息，调试和审计友好
• 广泛的框架集成：一行代码接入 Anthropic SDK、OpenAI SDK、LiteLLM、LangChain、Vercel AI SDK、Agno 等 10+ 框架
• 双模式部署：SDK 模式（直接包装 LLM 客户端）和 Proxy 模式（独立代理服务器），灵活适配不同架构
• 跨 Agent 记忆：SharedContext 机制让多个 Agent 共享压缩上下文，避免重复发送相同内容
• 失败学习：headroom learn 自动挖掘失败的 LLM 会话，将修正写入 CLAUDE.md / AGENTS.md 等文件
• 本地运行，零数据外泄：所有压缩在本地完成，不经过第三方服务

性能表现

官方 benchmark 在 docs/content/docs/benchmarks.mdx 中，仓库 README 声称覆盖所有内容类型的压缩：

快速上手

安装

# Python — 安装全部功能
pip install "headroom-ai[all]"

# Python — 按需安装子集
pip install "headroom-ai[proxy]"    # 代理模式
pip install "headroom-ai[mcp]"      # MCP 工具
pip install "headroom-ai[langchain]" # LangChain 集成
pip install "headroom-ai[agno]"     # Agno 集成

# TypeScript / Node
npm install headroom-ai

# Docker
docker pull ghcr.io/chopratejas/headroom:latest

[!warning] 不要省略 extras 不带 [proxy] 等extras 安装时，用到 FastAPI / OpenTelemetry 的功能会抛 ModuleNotFoundError（#441）。推荐直接用 [all]。

最小示例

# 方式一：SDK 模式 — 包装 Anthropic 客户端
from anthropic import Anthropic
from headroom import withHeadroom

client = withHeadroom(Anthropic())
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

# 方式二：直接压缩消息
from headroom import compress

compressed = compress(messages, model="claude-sonnet-4-6")

// TypeScript — Vercel AI SDK 集成
import { wrapLanguageModel } from 'ai';
import { headroomMiddleware } from 'headroom-ai';

const model = wrapLanguageModel({
  model: yourModel,
  middleware: headroomMiddleware(),
});

# 方式三：代理模式 — 独立运行
headroom proxy --port 8787
# 然后将你的 LLM 客户端指向 http://localhost:8787

# Docker 代理模式
docker run -p 8787:8787 \
  -e OPENAI_API_KEY=sk-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  ghcr.io/chopratejas/headroom:latest

配置要点

• HEADROOM_MODE（默认 optimize）：压缩策略，可选 passthrough（透传不压缩）
• HEADROOM_PORT（默认 8787）：代理监听端口
• HEADROOM_LOG_LEVEL（默认 INFO）：日志级别，调试时设为 DEBUG
• headroom.yaml：高级配置文件，放到 ~/.headroom/config.yaml，可定义压缩规则、缓存策略、Provider 映射等

适用场景

适合：

• 多轮对话 Agent 系统——上下文快速膨胀，需要压缩历史消息
• 代码助手 / IDE 插件——工具输出（文件内容、grep 结果）占大量 token
• LiteLLM 代理网关——一行 callback 接入，对下游 100+ Provider 透明压缩
• 多 Agent 协作——SharedContext 共享压缩上下文，避免跨 Agent 重复传输
• MCP 工具链——headroom mcp install 一键集成

不适合：

• 短对话 / 单轮问答（token 本身就少，压缩收益不明显）
• 已有完善 RAG 检索的系统（检索已过滤了无关内容，压缩空间有限）
• 对延迟极度敏感的实时场景（压缩本身有少量开销）

已知坑 & 注意事项

[!warning] 安装时必须带 extras pip install headroom-ai 不带 extras 时，用到 proxy/mcp 等功能会报 ModuleNotFoundError。始终使用 pip install "headroom-ai[all]" 或按需选择 extras（#441）。

[!warning] 大上下文 / 长超时场景

• Codex wrapper 崩溃：当上下文过大或超时过长时，Headroom 断连可能导致 Codex 包装器崩溃

• Release 发布偶有缺失：v0.6 曾未正式发布到 PyPI（#171），安装时注意确认版本号

• Python 版本：要求 Python 3.10+，不支持 3.9 及更早版本

• pipx 安装：使用 pipx 时需显式指定解释器，参考官方文档的安装指南

竞品对比

选择建议：

• Agent / 多轮对话场景，追求 token 节省 + 可调试 → Headroom（唯一提供可逆压缩 + 跨 Agent 共享的开源方案）
• 只需缓存相似 prompt 的响应 → LangCache 或 Provider 内置的 Prompt Caching
• 已用 Anthropic / OpenAI，只需 KV Cache → 直接用 Provider 的 Prompt Caching（零额外依赖）

生态 & 社区

• 维护状态：活跃。PyPI 最新版本 v0.22.4，持续迭代中
• 文档质量：好。独立文档站 headroom-docs.vercel.app，覆盖 Quickstart、架构、压缩原理、缓存优化、Benchmark 等
• 周边生态：
  • LiteLLM — 100+ Provider 代理，Headroom 作为 callback 一行集成
  • LangGraph — 可通过 LangChain 集成层使用
  • mem0 / supermemory — 记忆层方案，与 Headroom 的 SharedContext 互补
• 社区活跃度：GitHub 3k+ stars，Issues 响应及时，功能请求接受度较高
• License：Apache 2.0，商用友好

引入评估

结论：推荐 — 如果你正在构建多轮对话 Agent 或代码助手，上下文膨胀导致 token 成本居高不下，Headroom 是目前最完善的开源压缩方案。可逆压缩、跨 Agent 共享、10+ 框架集成是真正的差异化优势。注意项目仍在 0.x 阶段，生产环境建议先做小规模验证。

推荐引入版本：headroom-ai[all] >= 0.22（使用 [all] extras 避免缺依赖问题）

相关链接

前置知识：RAG · Embedding向量 竞品：LangCache 使用场景：LLM 应用开发 · Agent 系统 · Token 优化 底层概念：上下文窗口 · Prompt Caching 项目落地： 互补工具：RTK · claude-mem · mem0 · supermemory · LangGraph 对比笔记：Headroom vs RTK vs claude-mem 对比

• Headroom GitHub
• Headroom 文档站
• PyPI: headroom-ai
• 架构文档
• Benchmark

个人备注

{留白，供后续补充实际使用心得}