Headroom：为 AI Agent 省下 95% Token 的压缩神器

一句话，Headroom 解决了什么

你在构建 AI Agent 时，每次对话都要把历史消息、工具调用记录、系统提示一股脑塞进 LLM 的上下文窗口。结果 Token 消耗爆炸，成本飙升，长上下文还导致推理变慢。Headroom 是一个专门针对 AI Agent 的 上下文压缩器，它能在保持语义完整的前提下，将对话历史压缩到原来的 5% 大小，直接省下 95% 的 Token 费用。

GitHub 数据

项目背景

Headroom 由独立开发者 Chopratejas 创建。他在构建多轮对话 Agent 时发现，随着对话轮次增加，Token 消耗呈线性增长，而大多数历史消息对当前决策几乎无贡献。传统的滑动窗口或截断策略会丢失关键信息，导致 Agent 频繁犯错。他需要一个能智能识别“哪些历史必须保留、哪些可以压缩”的工具，于是有了 Headroom。

核心功能解析

语义感知的上下文压缩

Headroom 不是简单截断，而是对每条消息做重要性评分。它会保留系统提示、工具调用结果、用户最新指令等关键内容，对中间闲聊、重复信息、无关日志进行压缩或删除。压缩后的输出保留了完整的逻辑链条，但体积大幅缩小。

# 使用 Headroom 压缩对话历史
from headroom import Compressor

compressor = Compressor()
compressed = compressor.compress(messages, max_tokens=2000)
# 原始 40,000 tokens → 压缩后 2,000 tokens

结构化消息保留

许多压缩工具会把消息合并成一段纯文本，丢失了角色（user/assistant/system）和工具调用结构。Headroom 保持 OpenAI 消息格式 不变，压缩后的输出可以直接传给 LLM，无需额外解析。

可配置的压缩策略

提供多种压缩模式：aggressive（激进，适合低成本场景）、balanced（平衡，默认）、conservative（保守，保留更多细节）。你还可以自定义白名单，强制保留某些角色或特定关键词的消息。

# 使用保守模式，并强制保留所有系统消息
compressor = Compressor(
    mode="conservative",
    preserve_roles=["system"],
    preserve_keywords=["error", "critical"]
)

快速上手

# 安装
pip install headroom

# 基本使用（压缩对话历史）
from headroom import Compressor

messages = [
    {"role": "system", "content": "你是一个客服助手"},
    {"role": "user", "content": "我的订单还没到，怎么办？"},
    # ... 几十轮对话
]

compressor = Compressor(max_tokens=500)
compressed = compressor.compress(messages)

# 直接传给 LLM
response = openai.chat.completions.create(
    model="gpt-4",
    messages=compressed
)

技术亮点

Headroom 最让我佩服的设计决策是 不依赖 LLM 做压缩。很多同类项目会调用 GPT-4 来“总结”历史，这反而增加了 Token 消耗和延迟。Headroom 采用纯算法策略：

• TF-IDF + 时间衰减：计算每条消息与当前问题的语义相关性，越久远的消息权重越低。
• 滑动窗口 + 重要性排序：保留最近 N 轮完整对话，对更早的历史按重要性排序后保留关键片段。
• 零外部依赖：不需要调用任何 LLM，压缩速度在毫秒级，适合高并发场景。

这种架构的好处是可预测：无论对话多长，压缩时间都稳定在 10ms 以内，且不产生额外 Token 成本。

同类对比

总结

如果你在开发 多轮对话 Agent、客服机器人、代码助手，并且被 Token 成本困扰，Headroom 是目前最务实的选择。它不炫技，不烧钱，用一个巧妙的算法解决了真实痛点。省下 95% 的 Token，意味着你的 Agent 成本直接降到原来的 5%。

适合人群：任何使用 LLM 做多轮对话的开发者。

不适合：需要完美保留所有语义细节的场景（如法律文档审核）。