在任意 Python 应用内联调用 compress() 压缩消息再送 OpenAI 接口

方案简介

本方案以库方式使用 Headroom：在 Python 应用中直接调用 compress(messages)，在消息送入 LLM（如 OpenAI gpt-4o）之前完成压缩。适用于自建应用、LangChain 等框架或任何希望在代码内精确控制压缩时机的场景。压缩在本地运行，提示词与文件内容不会被发送到别处压缩，结果可逆，原文缓存在本地可按需取回。

亮点与能力

• 一行 compress(messages) 内联接入任意应用
• 指定目标模型（如 gpt-4o）进行压缩
• 返回 tokens_saved 与 compression_ratio 统计
• ContentRouter 自动按内容类型选择压缩器
• 可逆压缩（CCR），原文本地缓存按需取回
• TypeScript 侧也有对应 SDK（import { compress } from 'headroom-ai'）

组成与分工

• Headroom：压缩库，提供 compress() API
• OpenAI：LLM 提供方，接收压缩后的消息
• Python：运行环境，通过 pip 安装

前置要求

安装 Python 包：

bash
pip install "headroom-ai[all]" # Python — ships the headroom CLI

需要 OpenAI 客户端库以发起聊天补全请求。

实施步骤

1. 安装

bash
pip install "headroom-ai[all]"

2. 在代码中调用 compress

python
from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

compress 返回压缩后的 result.messages，直接替换原始 messages 传给 OpenAI 客户端即可。

使用与配置要点

• 用 result.tokens_saved 与 result.compression_ratio 在应用内监控节省情况
• 也可运行 headroom savings 对自身流量测量实际节省数字
• 压缩率取决于负载重复度：重复 JSON 与日志可达 90%，散文压缩有限

优缺点

• ✓ 内联嵌入任意应用
• ✓ 返回节省 token 统计

出处

本方案挖掘自开源项目 headroomlabs-ai/headroom，方案内容与实施命令均来自其 README 原文。