headroomlabs-ai / headroom

headroomlabs-ai/headroom

open_in_new前往仓库

在数据到达LLM之前压缩工具输出、日志、文件和RAG分块，为编码代理减少20%的令牌，为JSON减少60-95%的令牌，同时保持答案不变。提供库、代理和MCP服务器。

项目概览

项目概述

Headroom 是一个面向 AI 代理的上下文压缩层，旨在减少发送给大语言模型（LLM）的令牌数量，同时保持答案质量。它支持多种部署模式：作为 Python/TypeScript 库、本地代理服务器、MCP 服务器，以及命令行工具。Headroom 能够压缩工具输出、日志、文件、RAG 分块和对话历史，声称对 JSON 数据可减少 60-95% 的令牌，对编码代理可减少 15-20% 的令牌。项目采用 Apache-2.0 许可证，主要使用 Python 编写，并提供 TypeScript SDK。

核心功能

  • 多模式部署：支持库模式（compress(messages)）、代理模式（headroom proxy）、代理包装（headroom wrap）和 MCP 服务器。
  • 内容感知压缩：通过 ContentRouter 检测内容类型，并使用 SmartCrusher（JSON）、CodeCompressor（AST）和 Kompress-v2-base（文本）等压缩器。
  • 可逆压缩（CCR）：原始内容被本地缓存，LLM 可通过 headroom_retrieve 按需检索。
  • 跨代理记忆：共享存储，支持 Claude、Codex、Gemini、Grok 等，自动去重。
  • 输出令牌减少：通过代理调整模型输出，减少冗余表述和深度思考。
  • headroom learn：从失败会话中挖掘经验，写入 CLAUDE.local.md 等文件。
  • 缓存对齐：检测可能破坏提供商 KV 缓存前缀的易变内容，并发出警告。
  • 实时区域压缩：仅压缩新增字节，保持冻结前缀不变，避免缓存失效。

适用与不适用场景

适用场景：

  • 日常使用 AI 编码代理，希望在不修改代码的情况下节省令牌。
  • 跨多个代理工作，需要共享记忆。
  • 需要可逆压缩，原始内容可在 TTL 内检索。

不适用场景：

  • 仅使用单一提供商的原生压缩，且不需要跨代理记忆。
  • 在沙盒环境中运行，无法启动本地进程。

技术架构与依赖

  • 核心组件：CacheAligner、ContentRouter、CCR、SmartCrusher、CodeCompressor、Kompress-v2-base。
  • 语言：Python 3.10+（核心），TypeScript SDK（headroom-ai npm 包）。
  • 依赖：FastAPI（代理）、LiteLLM（定价）、ONNX Runtime（内容检测）、HuggingFace 模型（文本压缩）。
  • 可选扩展：[proxy]、[mcp]、[ml]、[code]、[memory]、[vector]（HNSW）、[relevance]、[image]、[agno]、[langchain]、[evals]、[pytorch-mps]。
  • 平台支持：macOS Apple Silicon、Linux（x86_64/aarch64）、Windows（部分）。

安装与快速开始

# 安装 CLI（推荐使用 uv）
uv tool install --python 3.13 "headroom-ai[all]"

# 或使用 pip
pip install "headroom-ai[all]"

# TypeScript SDK（仅库，无 CLI）
npm install headroom-ai

# 快速开始
headroom deploy                         # 一键本地部署
headroom wrap claude                    # 包装编码代理
headroom proxy --port 8787              # 启动代理
headroom doctor                         # 健康检查

典型使用方法

库模式（Python）：

from headroom import compress
compressed = compress(messages, model="claude-3-5-sonnet")

代理模式：

headroom proxy --port 8787
# 配置客户端使用 http://127.0.0.1:8787 作为 API 端点

MCP 服务器：

headroom mcp install
# 在 MCP 客户端中配置 headroom 服务器

包装代理：

headroom wrap claude
headroom unwrap claude

配置与部署要点

  • 环境变量：HEADROOM_OUTPUT_SHAPER=1 启用输出缩减，HEADROOM_TLS_STRICT=0 处理严格 TLS，HEADROOM_UPDATE_CHECK=off 禁用更新检查。
  • 代理配置：可通过 --backend bedrock 等参数指定后端，支持 AWS Bedrock。
  • MCP 配置：对于 Codex 等客户端，需使用绝对路径配置 command。
  • 企业部署：支持 Docker 镜像（ghcr.io/chopratejas/headroom:latest），提供托管服务。
  • 平台注意事项：Intel macOS 需手动安装 ONNX Runtime；x86 主机需 AVX2 支持。

限制、风险与许可证

  • 许可证：Apache-2.0。
  • 限制：需要本地进程运行；某些功能（如 ONNX 检测）依赖特定硬件；输出节省为估计值。
  • 风险：压缩可能丢失细节，但 CCR 提供可逆性；代理可能引入延迟；企业环境需注意 SSL 检查。
  • 安全：本地优先，数据不离开机器；但代理会处理敏感数据，需确保环境安全。

官方链接

安装和使用 Headroom 主要有三种方式，你可以根据自己的技术栈和使用习惯来选择。对于大多数用户，最推荐的方式是通过 uv 或 pip 进行安装，然后以代理（Proxy）模式快速开始。

安装指南

Headroom 支持多种安装方式，核心要求是 Python 3.10+。

方式一：使用 uv 工具安装（推荐）

如果你在 macOS (Apple Silicon) 或 Linux 上，并希望拥有一个全局的 headroom 命令，这是最干净的方式。它会将 Headroom 安装在一个独立的环境中。

# 安装包含所有功能的完整版本，并指定使用 Python 3.13
uv tool install --python 3.13 "headroom-ai[all]"

# 验证安装
headroom --version

如果安装后系统找不到 headroom 命令，可以运行 uv tool update-shell 来更新 PATH。

方式二：在 Python 项目中使用 pip

如果你更习惯在 Python 的虚拟环境中管理包，可以使用 pip 进行安装。

  • 仅核心包（基础压缩功能）：

    pip install headroom-ai

  • 安装特定功能（例如代理服务器、代码压缩等）：

    pip install "headroom-ai[proxy]"  # 代理模式必须
pip install "headroom-ai[code]"   # 启用AST感知的代码压缩
pip install "headroom-ai[all]"    # 安装所有功能

方式三：其他安装方式

  • Node.js/TypeScript 项目：npm install headroom-ai
  • Docker 原生模式：
    • Linux/macOS: curl -fsSL https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.sh | bash
    • Windows PowerShell: irm https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.ps1 | iex

快速开始：代理模式

安装完成后，最快速的体验方式就是启动一个本地代理服务器，然后将你的 AI 客户端指向它。

  1. 启动 Headroom 代理： 在终端中执行以下命令，Headroom 会在 8787 端口启动一个本地代理。

    headroom proxy --port 8787

  2. 配置你的 AI 工具： 将你的 AI 编码工具（如 Claude Code、Cursor 等）的 API 请求地址指向这个本地代理。

    • 对于 Claude Code： 
      ANTHROPIC_BASE_URL=http://localhost:8787 claude
    • 对于任何 OpenAI 兼容客户端： 
      OPENAI_BASE_URL=http://localhost:8787/v1 your-app

    如果使用 Claude Code 且觉得手动设置麻烦，也可以直接运行 headroom wrap claude，它会自动完成配置。

完成这两步后，所有经过代理的 API 请求和工具输出都会被 Headroom 自动压缩优化。

💡 补充信息：全局工具 HeadroomSwitch

如果你在 Windows 系统上使用多个 AI Agent，并希望更直观地管理 Headroom 的开关，可以关注社区开发的图形化工具 HeadroomSwitch。

它并非官方工具，但可以帮你一键开启/关闭对 Claude Code、Cursor 等 17 种 Agent 的压缩代理，并实时统计节省的 Token 数量。你可以在其 GitHub 仓库找到更多信息。