Headroom 实战：AI Agent 上下文压缩教程

Headroom 实战：AI Agent 上下文压缩教程

跑 RAG 管道或 AI Agent 时，一次长对话吃掉几万 token 是常态。月底看账单，交互 Token 开销占了大头，而其中大部分是重复日志、完整 JSON 数组和已经读过的代码片段。

LLM 按 token 计费，但塞给它的上下文里，真正关键的往往不到一半。Headroom 能在请求到达 LLM 之前，自动压缩工具输出、日志、RAG chunk 和对话历史。所有处理在本地完成，无需上传任何代码或数据到第三方。

完成本教程后，你将能够：

1. 安装 Headroom 并理解三种接入方式
2. 用 Python Library 模式完成上下文压缩并验证节省效果
3. 启动本地 Proxy，实现零代码改动自动压缩

前置条件

• Python 3.10+（推荐 3.13），或 Node.js 环境
• pip、uv 或 npm 之一
• 可用的 LLM API key（OpenAI / Anthropic）
• 了解基本的 Python 调用 OpenAI SDK 流程

Proxy 模式零代码改动，Java、Go 等语言的开发者同样适用。

安装与健康检查

推荐使用 pip 全量安装：

pip install "headroom-ai[all]"

习惯用 uv 的话：

uv tool install --python 3.13 "headroom-ai[all]"

安装完成后执行健康检查：

headroom doctor

这一步会检查路由、压缩器和网络连通性。全绿输出表示安装成功。提前运行 doctor 能发现 ONNX Runtime 依赖、AVX2 指令集等潜在问题，避免后续编码时踩坑。

内网环境若遇 SSL 证书拦截，可 pip install --only-binary headroom-ai headroom-ai 使用预编译 wheel 跳过 Rust 构建，并参考 README 设置 HEADROOM_CA_BUNDLE。

快速上手：三种接入方式

Headroom 提供三种使用方式，对应不同开发场景：

下面重点实操 Library 和 Proxy 模式，这两条路径对大多数开发者最实用。

实战：Library 模式压缩对话上下文

假设有一段包含工具输出、日志片段和 JSON 的对话消息，我们来看看压缩效果：

from headroom import compress
from openai import OpenAI

messages = [
    {"role": "system", "content": "You are a helpful debugging assistant."},
    {"role": "user", "content": "分析以下服务日志:\n" + 
     "[2026-10-10 09:00:01] INFO  Starting service...\n" * 50 +
     "[2026-10-10 09:00:02] FATAL NullPointerException at UserService.java:42\n"},
    {"role": "assistant", "content": "{\"files\": [\"UserService.java\"], \"status\": \"failed\"}"}
]

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

print(f"压缩前: {result.original_tokens} tokens")
print(f"压缩后: {result.compressed_tokens} tokens")
print(f"节省: {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=result.messages
)

代码做了三件事：

1. 构造包含重复日志和 JSON 的 messages，对应 Agent 常见场景中最常见的冗余内容
2. 调用 compress()，ContentRouter 自动识别内容类型——日志交由 Kompress-v2-base 处理，JSON 交由 SmartCrusher 保留关键字段和异常值
3. 使用 result.messages 发请求，结构与原始完全一致，无缝对接 OpenAI SDK

测试环境压缩率约 60%~70%，大量重复的 INFO/ERROR 行被识别为可压缩内容。压缩采用智能保留式策略：FATAL 行等关键信息被标记保留，重复字段被折叠。配合 CCR 机制，LLM 如需更多信息可通过 headroom_retrieve 检索原始内容。

零代码模式：启动 Proxy

不想在每个请求里手动调用 compress() 的场景，Proxy 模式更合适：

headroom proxy --port 8787

修改 base_url 指向本地 Proxy：

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="http://localhost:8787/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "分析日志..."}]
)

Proxy 拦截所有 OpenAI 兼容请求，转发给真实 LLM 前完成压缩。仅改一行 base_url，Java、Go 等任意 HTTP 调用 LLM 的代码均可受益。

运行期间随时查看实时节省：

headroom dashboard

本地 Web 页面展示每次请求的压缩率和累计节省，方便监控 Token 消耗变化。

打包编码代理

日常使用 Claude Code、Codex、Cursor 等编码代理，一条命令搞定：

headroom wrap claude

该命令会启动本地 Proxy、自动安装 Serena（语义代码导航 MCP 服务器）、配置路由到 Headroom。运行 headroom unwrap claude 即可恢复。支持的代理包括 claude、codex、grok、copilot、cursor、aider、cline、continue 等十多个。不带参数运行 headroom wrap 查看完整列表。

常见问题

Q1：压缩会降低模型回答质量吗？

GSM8K、TruthfulQA、SQuAD v2 等基准测试显示，准确率变化在 ±0.03 统计误差内。关键信息不会丢失，重复内容被压缩，重要数据被保留。

Q2：x86 CPU 安装失败？

不支持 AVX2 的旧云服务器，ONNX Runtime 无法运行。Headroom 自动降级为 BM25 启发式压缩。需要完整 ONNX 功能可换支持 AVX2 的机器或使用 Docker 镜像。

Q3：Intel Mac 安装失败？

Intel macOS 无预编译 ONNX Runtime：

ORT_STRATEGY=system \
ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
ORT_PREFER_DYNAMIC_LINK=1 \
  pip install "headroom-ai[all]"

Q4：上下文很短需要压缩吗？

不需要。低于 min_input_words 阈值的请求直接放行。长日志、大 JSON 数组、RAG 多 chunk、Agent 积累的长对话历史才需要压缩。

Q5：Proxy 启动后改环境变量不生效？

Proxy 启动时快照环境变量。需重启 Proxy，或通过 headroom wrap 热同步，它通过 loopback POST /admin/runtime-env 动态推送配置。

小结

回顾今天完成的操作：

1. 安装 Headroom，一条 pip install 加 headroom doctor 检查
2. Library 模式：Python 代码完成压缩，实测节省 60%+
3. Proxy 模式：修改 base_url，所有语言零代码改动
4. Agent Wrap：一条命令包裹编码代理

长对话、大批量工具输出和 RAG 场景中效果最明显。运行 headroom dashboard 监控 Token 节省，或执行 headroom perf 做性能基准测试。

仓库信息：headroomlabs-ai/headroom