省了70万美元token：Netflix工程师开源的AI上下文压缩工具Headroom

省了70万美元token：Netflix工程师开源的AI上下文压缩工具Headroom

前言

你用 Claude Code 排查一个 bug，AI 读了一遍数据库查询结果（500行）、构建日志（8000行）、JSON 返回（90%是无用字段）、RAG 检索回的文档（一大堆）……然后告诉你"没发现问题"。

这些数据 AI 全部读了一遍，全部计费。

有研究指出：AI 应用中约 76% 的 token 消耗，仅仅用于读取用户输入。也就是说，你付的 AI 账单里，可能有一大半是在为"读垃圾"买单。

Netflix 高级工程师 Tejas Chopra 收到一张 287 美元的 API 账单后，仔细分析了一下——发现了同样的问题。于是他做了 Headroom。

截至 2026 年 7 月，Headroom 已累计帮用户省下约 70 万美元，释放超过 2000 亿个 token。

项目简介

Headroom 是一个 AI Agent 上下文压缩层（Context Compression Layer）。核心使命是：在 AI Agent 读取的所有内容到达 LLM 之前进行智能压缩，减少 60-95% 的 token 消耗，同时保持答案质量不变。

• GitHub：https://github.com/headroomlabs-ai/headroom
• GitCode（国内镜像）：https://gitcode.com/GitHub_Trending/head/headroom
• 官方文档：https://headroom-docs.vercel.app/docs
• 作者：Tejas Chopra（Netflix 高级工程师）
• 开源时间：2026 年 1 月
• 当前版本：v0.31.0
• License：Apache 2.0
• 主要语言：Python 76.8% + Rust 18.4% + TypeScript 2.7%

它可以压缩的内容包括：

• 工具调用的返回结果（巨型 JSON）
• 构建日志和错误日志
• RAG 检索回来的文档片段
• 代码文件内容
• 对话历史

一句话：你用 AI 查天气预报，它不用把整个气象局数据库全读一遍。

核心架构

Headroom 在 AI 应用与 LLM 之间建立一个本地运行的透明压缩层：

┌─────────────────────────────────────────────────────┐
│ Your Agent / App                                    │
│ (Claude Code, Cursor, Codex, LangChain, etc.)       │
│ prompts · tool outputs · logs · RAG · files         │
└────────────────────────┬────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────┐
│ Headroom (runs locally)                             │
│  CacheAligner → ContentRouter → CCR                 │
│  ├─ SmartCrusher (JSON)                             │
│  ├─ CodeCompressor (AST)                            │
│  └─ Kompress-base (text, HF model)                  │
└────────────────────────┬────────────────────────────┘
                         ▼
              compressed prompt + retrieval tool
                         ▼
┌─────────────────────────────────────────────────────┐
│ LLM Provider (Anthropic · OpenAI · Bedrock)         │
└─────────────────────────────────────────────────────┘

智能路由：六种压缩算法

Headroom 不是一刀切地压缩，它会自动识别内容类型，选最优压缩算法：

冷启动缓解机制

Kompress（ML 模型）存在冷启动问题：处理 ~1M token 需 ~200-300 秒。Headroom 设计了四阶段缓解机制：

关键设计原则：所有四项功能默认关闭且 fail-open——出错时请求转发（压缩或原样），绝不丢弃。

CCR 机制：可逆压缩

很多压缩工具的问题：压完就回不去了，信息丢了。

Headroom 的 CCR 机制（Compress-Cache-Retrieve）解决了这个问题：

• 压缩时：原始内容缓存在本地（Redis 或 SQLite）
• 压缩后：数据附带 CCR 哈希，体积大幅缩小
• 需要时：AI 可以通过 headroom_retrieve 按需取回原始内容

也就是说：压缩不是删除，是"打包存放"。AI 需要细节时随时能拆开。

CJK 中文支持

Headroom 专门做了 CJK（中日韩）感知压缩，对国内开发者很重要：

• 使用 ICU 分词器（icu_segmenter 2.2, ICU4X），正确处理中文句子边界
• 纯 ASCII 文本输出字节级一致，不会乱码
• CJK 路径使用独立的 relevance_cjk 本地 BM25 评分器

中文压缩效果

multi-wiki-qa 答案保留率（n=80/语言，target_ratio=0.3）：

CMRC2018 中文 QA 数据集：30% 压缩率下，答案保留率从 34% → 93%，端到端聚合节省从 16% → 40%。

安装与使用

系统要求

安装方式

# 方式1：pip 安装（推荐）
pip install "headroom-ai[all]"       # 完整功能
pip install "headroom-ai[proxy]"     # 仅代理模式
pip install "headroom-ai[ml]"        # 含 ML 压缩模型

# 方式2：uv 安装（macOS Apple Silicon / Linux）
uv tool install --python 3.13 "headroom-ai[all]"

# 方式3：npm 安装（TypeScript）
npm install headroom-ai

# 方式4：Docker
docker pull ghcr.io/headroomlabs-ai/headroom:latest

# 方式5：pipx（隔离安装）
pipx install --python python3.13 "headroom-ai[all]"

四种集成模式

① CLI 包装模式（最简单）

一行命令包装现有的 AI 编程工具，零代码改动：

headroom wrap claude
headroom wrap codex
headroom wrap cursor

② 代理模式

起一个本地代理，拦截所有 LLM 请求，自动压缩。任何语言都能用：

headroom proxy --port 8787

③ 库模式

在 Python 代码里直接调用：

from headroom import compress

# 最简单的使用方式
result = compress(messages, model="gpt-4o")
print(f"节省 {result.tokens_saved} tokens ({result.compression_ratio*100:.1f}%)")

# SDK 包装模式
from headroom import HeadroomClient, OpenAIProvider
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
)
response = client.chat.completions.create(model="gpt-4o", messages=messages)

TypeScript 版本：

import { compress } from "headroom-ai";

const result = await compress(messages, { model: "gpt-4o" });
console.log(`节省 ${result.tokens_saved} tokens`);

④ MCP 服务器模式

提供三个 MCP 工具，任何 MCP 客户端都能调用：

• headroom_compress：压缩消息
• headroom_retrieve：检索原始内容
• headroom_stats：查看节省统计

环境变量配置

HEADROOM_KOMPRESS_MAX_TOKENS=50000      # Phase 0 大小门控
HEADROOM_COMPRESSION_DEADLINE_MS=20000   # Phase 1 截止时间
HEADROOM_TEXT_CRUSHER=1                  # Phase 2 启用 TextCrusher
HEADROOM_BACKGROUND_COMPRESSION=1        # Phase 3 后台压缩

性能基准测试

实际工作负载节省

质量评估基准

TextCrusher 在 30% 大小下保留 ~94% 的 SQuAD 埋藏答案，对比 truncate/random 仅保留 ~36%。

速度：~333k 词在 ~76ms 内完成（单次 O(n) 遍历）。

作者自己的账单从 287 美元降到了 110 美元。

与 Caveman 对比

说到 token 省钱，还有一个值得关注的项目 Caveman——让 AI 说"穴居人话"，去掉客套废话，平均省 65% 的输出 token。两个项目从不同角度解决同一个问题：

最省钱的方案是两个一起用：Headroom 管输入端，Caveman 管输出端，两头掐：

你的输入 → [Headroom 压缩] → AI 读取（少吃垃圾）
                                    ↓
                              AI 思考处理
                                    ↓
                          [Caveman 压缩] → AI 输出（少说废话）

总结

Headroom 代表了一个趋势：AI 应用的成本优化，正在成为独立赛道。

过去一年，所有人都在卷模型能力——谁的参数更大、谁跑分更高。但 2026 年下半年，一个新的问题浮出水面：AI 太贵了，用不起。

Uber 的 CTO 说公司全年 AI 预算 4 个月就花完了；微软开始限制内部工程师用 Claude Code。成本正在成为 AI 落地的最大障碍。

Headroom 证明了一件事：在模型能力不变的前提下，光靠压缩就能省下大部分成本。 当 AI 的使用成本降下来，更多的应用场景才会真正爆发。