headroom

喂给 AI 之前先瘦身，每五次对话省一次钱

在数据进入 LLM 之前压缩工具输出、日志、文件与 RAG 片段，编码 agent 可省 20% Token，JSON 场景最高省 95%，答案不变，以库、代理、MCP server 多种形态提供。

开源 free 开源模型

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 73504

维护状态活跃

是否开源是

定价模式 free

项目数据

分类开源模型

开发团队headroomlabs-ai

所属国家

官网地址https://docs.headroomlabs.ai/docs

GitHubhttps://github.com/headroomlabs-ai/headroom

定价模式free

价格说明开源项目，Apache-2.0 许可证，可免费使用和部署。

访问状态

是否开源是

开源协议Apache-2.0

主要语言Python

技术栈/模型agent,ai,anthropic,claude-code,compression,context-engineering,context-window,cursor,fastapi,langchain,llm,mcp,openai,prompt-engineering,proxy,python,rag,token-optimization,tokens,typescript

GitHub 星标★ 73504

30天Star增速

HF 下载量

上线时间2026-01-07 00:00:00

最近更新2026-09-22 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数8

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

Python 3.10 及以上（建议 3.13，省钱金额统计依赖 LiteLLM，不支持 3.14+）
推荐用 uv tool 安装 CLI，命令会放在独立应用环境
原生 wheel 目前覆盖 macOS Apple Silicon 与 Linux；Intel macOS 请改用 Docker
x86/x86_64 主机的 ONNX 功能（Magika 内容检测、嵌入相关性）需要 AVX2 指令集
Docker 方式需可拉取 ghcr.io 镜像

安装与启动步骤

1用 uv 安装 CLI

官方推荐方式，命令装在隔离的应用环境里，避免污染系统 Python。
```
uv tool install --python 3.13 "headroom-ai[all]"
```
2或用 pip 安装

已有 Python 环境时可直接 pip 安装，会一并带上 headroom 命令行。
```
pip install "headroom-ai[all]"
```
3或拉取 Docker 镜像

不想装 Python 环境时用镜像；注意 Intel macOS 目前只能走 Docker 方式。
```
docker pull ghcr.io/headroomlabs-ai/headroom:latest
```
4把命令加入 PATH

仅当 ~/.local/bin 不在 PATH 中时执行，否则终端找不到 headroom 命令。
```
uv tool update-shell
```
5验证安装

能打印出版本号就说明 CLI 安装成功，可以继续后续配置。
```
headroom --version
```
6启动本地代理

代理默认监听指定端口，用于在数据进入 LLM 前做压缩；启动后保持运行。
```
headroom proxy --port 8787
```
7取命令绝对路径

MCP 客户端常继承不到交互式 shell 的 PATH，需要把这个绝对路径填进配置。
```
command -v headroom
```
8配置 MCP 客户端

在客户端配置里把 command 写成上面的绝对路径，args 设为 mcp serve 两个参数。
```
command -v headroom
```

关键配置

配置项	必填	说明	示例
`HEADROOM_TLS_STRICT`	否	设为 0 关闭 X.509 严格校验，绕过企业 CA 的 basicConstraints 报错	`0`
`HEADROOM_UPDATE_CHECK`	否	设为 off 可关闭启动时的 PyPI 更新提示检查	`off`
`HEADROOM_EMBEDDER_RUNTIME`	否	Apple GPU 内存嵌入卸载，安装 [pytorch-mps] 后可用	`pytorch_mps`
`ORT_STRATEGY`	否	设为 system 使用系统 ONNX Runtime，跳过下载	`system`
`ORT_LIB_LOCATION`	否	指向 onnxruntime 的 lib/ 目录，不能只写前缀路径	`$(brew --prefix onnxruntime)/lib`
`ORT_DYLIB_PATH`	否	运行时 dlopen 加载的 onnxruntime 动态库完整路径	`$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib`

如何确认成功

执行 headroom --version 能输出版本号；headroom proxy --port 8787 启动后代理在 8787 端口运行、无报错退出。

常见问题

Q：pip 安装报 CERTIFICATE_VERIFY_FAILED 怎么办？

A：说明网络走了 SSL 检查。构建后端 maturin 会下载 rustup，先自行装好 Rust 让构建不再联网获取；若是 CA 证书未标 critical 的错误，可用 HEADROOM_TLS_STRICT=0 启动。

Q：为什么代理面板显示的省钱金额一直是 $0.00？

A：省钱金额由 LiteLLM 计算，而它无法在 Python 3.14+ 安装。改用 Python 3.13：pipx reinstall headroom-ai --python python3.13，然后重启代理。

Q：MCP 客户端提示找不到 headroom 命令？

A：Codex 等客户端拿不到交互式 shell 的 PATH。执行 command -v headroom 取绝对路径，写进 mcp_servers.headroom 的 command 字段，args 用 ["mcp", "serve"]。

Q：安装 [all] 后没有 LangChain 适配器？

A：[all] 只覆盖核心栈，不含框架适配器。需另行安装，如 pip install "headroom-ai[langchain]"，同理还有 [agno]、[strands]、[anyllm]、[bedrock]。

Q：x86 机器上 ONNX 相关功能不可用？

A：不带 AVX2 的 x86 主机（部分 Docker/QEMU、旧云主机）会自动回退到非 ONNX 路径：BM25 相关性、启发式检测，不会崩溃。

注意事项

需要 Python 3.10+；只有 Python 3.13 能看到面板上的省钱金额。
[all] 不含框架适配器，langchain/agno/strands/anyllm/bedrock 需单独安装。
npm install headroom-ai 只提供 TypeScript SDK，不包含命令行工具。
升级用 headroom update（自动识别 pip/pipx/uv tool 并原地升级），加 --check 只查看最新版本。

核心亮点

针对LLM输入做智能压缩，可显著降低token消耗（JSON场景最高减少95%），直接降低API成本
提供多种集成方式（库、代理、MCP服务器），适配Claude Code、Cursor、LangChain等主流工具链
压缩后保持语义完整性，官方宣称不影响回答质量，适合高频调用场景

不足之处

压缩过程可能引入额外延迟，对实时性要求极高的场景需权衡
文档/社区待观察

适用场景

编程助手（如Claude Code、Cursor）的上下文压缩，减少长对话token开销
RAG系统中对检索块进行预压缩，提升大规模知识库查询效率
日志和文件分析场景，降低海量文本输入LLM的成本

替代项目

LLMLingua、LangChain's Text Splitters、semantic-text-compressor

项目介绍

headroom 是基础设施领域的开源项目，由 headroomlabs-ai 开发，是 2026 年新上线的项目。

在全站 13,090 个收录项目中，它的 GitHub 星标数（73,504）位列前 1%，在基础设施分类的 1,132 个项目里位列前 1%。

近 42 天，它的 GitHub 星标从 66,047 增加到 73,504，净增 7,457。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-22。Apache-2.0 许可证，可免费使用和部署。

它主要面向的使用场景是：编程助手（如ClaudeCode、Cursor）的上下文压缩，减少长对话token开销。同类可对比的替代方案包括 LLMLingua、LangChain's Text Splitters、semantic-text-compressor。

上一篇：vllm

下一篇：mlflow