2026/06/08/8 分钟/11 阅读/0 评论

Headroom AI — 安装与使用教程

- 3.1 pip 安装（Python） - 3.2 npm 安装（TypeScript） - 3.3 Docker 安装 - 3.4 验证安装 - 4.1 Python — compress() 函数 - 4.2 TypeScript —

面试 #教程

"Same answers, fraction of the tokens."

Headroom 是一个 LLM 上下文优化层，在数据到达大模型之前对 tool outputs、日志、RAG 检索结果、文件内容、API 响应等进行压缩。答案不变，Token 消耗直降 40%~95%。

1. 架构概览

graph TD
    A[你的应用 / Agent] -->|prompts, tool outputs, logs| B[Headroom]
    B --> C[CacheAligner]
    C --> D[ContentRouter]
    D --> E[SmartCrusher<br/>JSON 压缩 70-90%]
    D --> F[CodeCompressor<br/>代码压缩 40-70%]
    D --> G[Kompress-base<br/>文本压缩 30-50%]
    D --> H[Image Compressor<br/>图片压缩 40-90%]
    E & F & G & H --> I[CCR 可逆存储]
    I -->|compressed prompt + retrieve tool| J[LLM Provider<br/>OpenAI / Anthropic / Google / Bedrock]
    J -->|response| A

数据流向：你的 Agent/App → Headroom（本地运行）→ 压缩后 prompt → LLM Provider。

所有数据本地处理，不上传到任何第三方服务。

2. 核心组件

组件	功能	典型压缩率
ContentRouter	自动检测内容类型（JSON/代码/日志/文本/diff/HTML），路由到最佳压缩器	—
SmartCrusher	通用 JSON 压缩器，保留 errors、anomalies、boundaries	70-90%
CodeCompressor	AST 感知的代码压缩（Python/JS/Go/Rust/Java/C++），保留签名、折叠方法体	40-70%
Kompress-base	基于 ModernBERT 的 HuggingFace 模型，用于文本/token 分类	30-50%
Image Compression	ML 路由器选择最优 resize/quality 策略	40-90%
CacheAligner	稳定前缀以命中 provider KV cache（Anthropic/OpenAI），保持 90% 读取折扣	—
IntelligentContext	基于评分的上下文适配，学习重要性权重	—
CCR（Compress-Cache-Retrieve）	可逆压缩存储，原始数据不丢弃，LLM 可通过 `headroom_retrieve` 工具按需取回原文	—

3. 安装

3.1 pip 安装（Python）

前置条件：Python >= 3.10

# 最小化安装（核心功能）
pip install headroom-ai

# 全量安装
pip install "headroom-ai[all]"

# 按需安装常用组合
pip install "headroom-ai[proxy,code,mcp]"

可用的 extras 选项：

Extra	说明	安装命令
`proxy`	代理服务器、MCP 工具、HTTP API	`pip install "headroom-ai[proxy]"`
`ml`	Kompress（ModernBERT 文本压缩，需 PyTorch）	`pip install "headroom-ai[ml]"`
`code`	CodeCompressor（tree-sitter AST 解析）	`pip install "headroom-ai[code]"`
`mcp`	MCP server 工具（compress/retrieve/stats）	`pip install "headroom-ai[mcp]"`
`langchain`	LangChain HeadroomChatModel 包装器	`pip install "headroom-ai[langchain]"`
`agno`	Agno HeadroomAgnoModel 包装器	`pip install "headroom-ai[agno]"`
`strands`	Strands agent 集成	`pip install "headroom-ai[strands]"`
`memory`	持久化记忆支持	`pip install "headroom-ai[memory]"`
`memory-stack`	记忆栈（Qdrant + Neo4j）	`pip install "headroom-ai[memory-stack]"`
`image`	图片压缩	`pip install "headroom-ai[image]"`
`relevance`	相关性评分	`pip install "headroom-ai[relevance]"`
`html`	HTML 压缩	`pip install "headroom-ai[html]"`
`bedrock`	AWS Bedrock 后端	`pip install "headroom-ai[bedrock]"`
`otel`	OpenTelemetry 可观测性	`pip install "headroom-ai[otel]"`
`evals`	评估框架（GSM8K/SQuAD/BFCL 基准）	`pip install "headroom-ai[evals]"`
`all`	以上全部	`pip install "headroom-ai[all]"`

可以组合多个 extras：

pip install "headroom-ai[proxy,langchain,ml]"

Windows 用户注意：如果 pip 安装报 Rust 编译错误（link.exe 冲突），加 --only-binary :all: 强制使用预编译 wheel：

这会安装稍低版本的预编译包，但功能完整，无需本地编译。

pip install "headroom-ai[proxy,code,mcp]" --only-binary :all:

3.2 npm 安装（TypeScript）

前置条件：Node.js >= 18

npm install headroom-ai
# 或
pnpm add headroom-ai
yarn add headroom-ai

重要：TypeScript SDK 本身不执行压缩，需要配合 Python 代理服务使用：

然后在 TypeScript 中连接代理：

# 先安装并启动 Python 代理
pip install "headroom-ai[proxy]"
headroom proxy --port 8787

import { compress } from 'headroom-ai';
const result = await compress(messages, {
  baseUrl: 'http://localhost:8787',
});

3.3 Docker 安装

# 拉取镜像
docker pull ghcr.io/chopratejas/headroom:latest

# 启动代理
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest

镜像标签：

标签	包含 Extras	基础镜像	说明
`latest`	proxy	Debian slim	默认，运行代理
`<version>`	proxy	Debian slim	指定版本
`nonroot`	proxy	Debian slim	非 root 用户
`code`	proxy,code	Debian slim	含 tree-sitter 代码压缩
`code-nonroot`	proxy,code	Debian slim	代码压缩 + 非 root
`slim`	proxy	Distroless	最小化，无 shell
`slim-nonroot`	proxy	Distroless	最小化 + 非 root
`code-slim`	proxy,code	Distroless	代码压缩 + 最小化
`code-slim-nonroot`	proxy,code	Distroless	代码压缩 + 最小化 + 非 root

带环境变量启动：

docker run -p 8787:8787 \
  -e OPENAI_API_KEY=sk-xxx \
  -e HEADROOM_MODE=optimize \
  ghcr.io/chopratejas/headroom:latest

3.4 验证安装

# Python
python -c "import headroom; print(headroom.__version__)"

# TypeScript
node -e "const h = require('headroom-ai'); console.log('headroom-ai loaded')"

4. 快速开始

4.1 Python — compress() 函数

最直接的使用方式，适合任何 Python 应用：

from headroom import compress
import json

# 构造你的消息列表
messages = [
    {"role": "system", "content": "你是一个搜索结果分析助手。"},
    {"role": "user", "content": "搜索 Python 教程。"},
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [{
            "id": "call_1",
            "type": "function",
            "function": {"name": "search", "arguments": '{"q": "python"}'},
        }],
    },
    {
        "role": "tool",
        "tool_call_id": "call_1",
        "content": json.dumps({
            "results": [
                {"title": f"Result {i}", "snippet": f"Description {i}", "score": 100 - i}
                for i in range(500)
            ]
        }),
    },
    {"role": "user", "content": "排名前3的结果是什么？"},
]

# 压缩
result = compress(messages, model="gpt-4o")

# 查看压缩效果
print(f"压缩前 Token: {result.tokens_before}")
print(f"压缩后 Token: {result.tokens_after}")
print(f"节省 Token:   {result.tokens_saved}")
print(f"压缩率:       {result.compression_ratio:.0%}")
print(f"使用的转换器: {result.transforms_applied}")

# 用压缩后的消息调用 LLM
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=result.messages,
)
print(response.choices[0].message.content)

典型输出：

压缩前 Token: 45000
压缩后 Token: 4500
节省 Token:   40500
压缩率:       90%
使用的转换器: ['smart_crusher', 'cache_aligner']

4.2 TypeScript — compress() 函数

import { compress } from 'headroom-ai';

const messages = [
  { role: 'system' as const, content: '你是一个搜索结果分析助手。' },
  { role: 'user' as const, content: '搜索 Python 教程。' },
  {
    role: 'assistant' as const,
    content: null,
    tool_calls: [{
      id: 'call_1',
      type: 'function' as const,
      function: { name: 'search', arguments: '{"q": "python"}' },
    }],
  },
  {
    role: 'tool' as const,
    tool_call_id: 'call_1',
    content: JSON.stringify({
      results: Array.from({ length: 500 }, (_, i) => ({
        title: `Result ${i}`,
        snippet: `Description ${i}`,
        score: 100 - i,
      })),
    }),
  },
  { role: 'user' as const, content: '排名前3的结果是什么？' },
];

// 需要代理服务运行中
const result = await compress(messages, {
  model: 'gpt-4o',
  baseUrl: 'http://localhost:8787',
});

console.log(`压缩率: ${result.compression_ratio}%`);

4.3 代理模式（零代码侵入）

适合不想改代码的场景——启动代理，把 LLM 的 base URL 指过来就行：

# 启动代理
headroom proxy --port 8787

# Claude Code 指向代理
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# OpenAI 客户端指向代理
OPENAI_BASE_URL=http://localhost:8787/v1 python your_app.py

查看统计信息：

curl http://localhost:8787/stats
# {"requests_total": 42, "tokens_saved_total": 125000, ...}

4.4 MCP Server 模式

为 Claude Code、Cursor 等 MCP 客户端提供三个工具：

MCP 工具	功能
`headroom_compress`	压缩输入内容
`headroom_retrieve`	取回压缩前的原始内容
`headroom_stats`	查看压缩统计

安装并启动：

headroom mcp install && claude

4.5 Agent Wrap 一键包装

一行命令包装你的 AI 编程工具：

# 包装 Claude Code
headroom wrap claude

# 包装 Codex
headroom wrap codex

# 包装 Cursor
headroom wrap cursor

# 包装 Aider
headroom wrap aider

# 包装 Copilot CLI
headroom wrap copilot

# GitHub Copilot（带订阅 + 指定模型）
headroom wrap copilot --subscription -- --model gpt-4o

兼容的 Agent 列表：

Agent	`headroom wrap`	备注
Claude Code	✅	支持 `--memory`、`--code-graph`
Codex	✅	与 Claude 共享记忆
Cursor	✅	打印配置，粘贴一次即可
Aider	✅	启动代理 + 启动 Aider
Copilot CLI	✅	启动代理 + 启动 Copilot
OpenClaw	✅	安装为 ContextEngine 插件

5. 框架集成

LangChain

from langchain_openai import ChatOpenAI
from headroom.integrations.langchain import HeadroomChatModel

llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"))

Agno

from agno.models.anthropic import Claude
from headroom.integrations.agno import HeadroomAgnoModel
from agno.agent import Agent

model = HeadroomAgnoModel(Claude())
agent = Agent(model=model)

Strands

from headroom.integrations.strands import HeadroomStrandsModel
from strands import Agent

model = HeadroomStrandsModel(...)
agent = Agent(model=model)

Vercel AI SDK（TypeScript）

import { withHeadroom } from 'headroom-ai/vercel-ai'
const model = withHeadroom(openai('gpt-4o'))

LiteLLM

import litellm
from headroom.integrations.litellm import HeadroomCallback

litellm.callbacks = [HeadroomCallback()]

ASGI 中间件

from headroom.integrations.asgi import CompressionMiddleware

app.add_middleware(CompressionMiddleware)

多 Agent 共享上下文

from headroom import SharedContext

ctx = SharedContext()
ctx.put("research", big_output)   # Agent A 存入
summary = ctx.get("research")     # Agent B 取出

6. 配置项

环境变量

LLM Provider 密钥：

变量	说明
`OPENAI_API_KEY`	OpenAI API Key
`ANTHROPIC_API_KEY`	Anthropic API Key
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`	AWS 凭证（Bedrock 后端）
`GOOGLE_APPLICATION_CREDENTIALS`	Google Cloud 凭证（Vertex AI 后端）

代理配置：

变量	默认值	说明
`HEADROOM_PORT`	`8787`	代理监听端口
`HEADROOM_HOST`	`0.0.0.0`	代理绑定地址
`HEADROOM_MODE`	`optimize`	运行模式：`optimize`（压缩）、`audit`（审计）、`passthrough`（透传）
`HEADROOM_LOG_LEVEL`	`INFO`	日志级别

TypeScript SDK：

变量	默认值	说明
`HEADROOM_BASE_URL`	`http://localhost:8787`	代理地址
`HEADROOM_API_KEY`	(无)	代理认证 Key

运行模式说明

模式	行为
`optimize`	默认模式，启用全量压缩管线
`audit`	审计模式，记录可压缩内容但不实际压缩，用于评估压缩潜力
`passthrough`	透传模式，不做任何处理，用于对比基线

7. 压缩效果参考

真实业务场景

场景	压缩前 Token	压缩后 Token	节省率
代码搜索（100 条结果）	17,765	1,408	92%
SRE 事件调试	65,694	5,118	92%
GitHub Issue 分类	54,174	14,761	73%
代码库探索	78,502	41,254	47%

按内容类型

内容类型	压缩器	典型节省
JSON 数组（tool outputs）	SmartCrusher	70-90%
源代码	CodeCompressor	40-70%
构建/测试日志	LogCompressor	80-95%
搜索结果	SearchCompressor	60-80%
纯文本	Kompress	30-50%
Git Diff	Diff 处理	40-60%
图片	ML 路由器	40-90%

基准测试准确度

基准	类别	样本数	基线准确率	Headroom 准确率	变化
GSM8K	数学	100	0.870	0.870	±0.000
TruthfulQA	事实	100	0.530	0.560	+0.030
SQuAD v2	问答	100	—	97%	压缩 19%
BFCL	工具调用	100	—	97%	压缩 32%

复现基准测试：python -m headroom.evals suite --tier 1

8. 常见问题

Q: Windows 上 pip 安装报 Rust 编译错误怎么办？

原因：Git 的 /usr/bin/link.exe（GNU coreutils）和 MSVC 的 link.exe 冲突，Rust 链接器找到了错误的 link.exe。

解决方案：

# 方案1：强制使用预编译 wheel（推荐）
pip install "headroom-ai[proxy,code,mcp]" --only-binary :all:

# 方案2：用 Docker
docker pull ghcr.io/chopratejas/headroom:latest
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest

Q: 压缩后 LLM 回答质量会下降吗？

官方基准测试显示，在 GSM8K（数学）上准确率完全不变，TruthfulQA 上甚至略有提升。Headroom 的策略是"可逆压缩"——原始数据不丢弃，LLG 需要细节时可通过 headroom_retrieve 工具取回原文。

Q: TypeScript SDK 可以独立使用吗？

不行。TypeScript SDK 只是一个客户端，实际的压缩管线由 Python 代理执行。你需要先启动 Python 代理（headroom proxy），TypeScript SDK 通过 HTTP 连接它。

Q: 数据安全吗？

所有数据本地处理，不发送到任何第三方服务。压缩完全在你自己的机器上完成。

Q: 支持哪些 LLM Provider？

通过 LiteLLM 支持 100+ Provider：OpenAI、Anthropic、Google、AWS Bedrock、Azure、Vertex AI 等。

9. 参考链接

资源	链接
官方文档	https://headroom-docs.vercel.app
GitHub 仓库	https://github.com/chopratejas/headroom
PyPI 包	https://pypi.org/project/headroom-ai/
npm 包	https://www.npmjs.com/package/headroom-ai
Docker 镜像	`ghcr.io/chopratejas/headroom`
安装指南	https://headroom-docs.vercel.app/docs/installation