LLM 应用的上下文优化层，通过确定性压缩与智能缓存实现 40-90% Token 节省，支持 JSON/代码/文本/图像多模态压缩及可逆 CCR 机制
项目概述#
Headroom 是专为 LLM 应用设计的上下文优化中间件，采用确定性压缩算法（非 LLM 压缩）结合 CCR（Compress-Cache-Retrieve）机制，在请求发送至 LLM 前进行上下文优化。
核心价值：
- 零代码改动（代理模式）
- 提供商无关（支持 OpenAI/Anthropic/AWS/Google 等）
- 可逆压缩（按需检索原始数据）
- 确定性压缩（无 LLM 调用，结果可预测）
核心压缩能力#
| 特性 | 描述 | 压缩效果 |
|---|---|---|
| SmartCrusher | 通用 JSON 压缩，统计分析数组模式，保留错误/异常/边界值 | 70-95% |
| CodeCompressor | AST 感知代码压缩，支持 Python/JS/Go/Rust/Java/C++ | - |
| LLMLingua-2 | 基于 ML 的文本压缩（可选） | ~20x |
| Image Compression | 图像 Token 优化，通过训练好的 ML Router 自动选策略 | 40-90% |
| CCR 机制 | 可逆压缩，原始数据缓存，LLM 可通过工具调用按需检索 | - |
上下文管理#
- Intelligent Context Manager：基于多因子重要性评分的消息管理（TOIN 学习模式、语义相似度、错误指标）
- CacheAligner：提取动态内容（日期、UUID）以稳定前缀，优化 KV Cache 命中率
- Rolling Window：基于 Token 限制的滚动窗口管理
- Compression Summaries：生成省略内容摘要（如 "87 passed, 2 failed, 1 error"）
安装与快速开始#
pip install headroom-ai # 核心库
pip install "headroom-ai[all]" # 完整安装（推荐）
pip install "headroom-ai[proxy]" # 代理服务器
pip install "headroom-ai[mcp]" # Claude Code MCP 集成
pip install "headroom-ai[langchain]" # LangChain 集成
代理模式（零代码改动）#
headroom proxy --port 8787
ANTHROPIC_BASE_URL=http://localhost:8787 claude
OPENAI_BASE_URL=http://localhost:8787/v1 cursor
Python SDK#
from headroom import compress
result = compress(messages, model="claude-sonnet-4-5-20250929")
response = client.messages.create(
model="claude-sonnet-4-5-20250929",
messages=result.messages
)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
典型场景与效果#
| 场景 | 压缩前 | 压缩后 | 节省 |
|---|---|---|---|
| 代码搜索（100 结果） | 17,765 tokens | 1,408 tokens | 92% |
| SRE 事件调试 | 65,694 tokens | 5,118 tokens | 92% |
| 代码库探索 | 78,502 tokens | 41,254 tokens | 47% |
| GitHub issue 分类 | 54,174 tokens | 14,761 tokens | 73% |
适用场景：AI Agent 工具输出压缩（日志、搜索结果、数据库查询）、长对话上下文管理、多模态应用图像 Token 优化、RAG 系统上下文预算控制。
运维特性#
- Prometheus metrics 端点
- 请求日志与成本追踪
- 预算限制与速率控制
云提供商支持#
headroom proxy --backend bedrock --region us-east-1 # AWS Bedrock
headroom proxy --backend vertex_ai --region us-central1 # Google Vertex
headroom proxy --backend azure # Azure OpenAI
headroom proxy --backend openrouter # OpenRouter