如何用 --no-optimize 基线与优化运行对比测量 Headroom 压缩对本地模型 prefill 的影响

如何用 --no-optimize 基线与优化运行对比测量 Headroom 压缩对本地模型 prefill 的影响

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom

本地模型不按 token 计费，但每次 prompt token 都实打实地消耗在 prefill 上——在 Apple Silicon 等本地推理环境里，长会话的 coding agent 往往瓶颈就在 prompt 处理而不是生成速度。本文的操作是：用同一个任务分别跑一次--no-optimize基线和一次开启优化的运行，通过 proxy dashboard 的 before/after token 计数，量化 Headroom 压缩减少了多少发往本地模型的 prompt token。前提是本地模型服务提供 OpenAI 兼容接口（接受/v1/chat/completions或/v1/responses），例如 MLX/OMLX、vLLM、LM Studio、Ollama 的 OpenAI-compatible endpoint。完整流程见 Local LLM Prefill Benchmark。

准备：本地推理服务与 Headroom 安装

先启动你的本地 OpenAI 兼容模型服务。本文档假定它监听在http://127.0.0.1:8000，下文所有命令按这一地址书写，如果你的服务端口或地址不同，替换对应值即可：

pip install "headroom-ai[proxy]"

--no-optimize是headroom proxy的内置选项（默认false），作用是 Disable optimization (passthrough mode)，即代理只做流量转发、不做任何压缩。选项说明见 Proxy Server 文档 的 CLI options 表。

第一步：--no-optimize 基线运行

以优化禁用的方式启动 Headroom，作为透明代理：

headroom proxy \ --port 8787 \ --openai-api-url http://127.0.0.1:8000 \ --no-optimize

把 agent 或应用的指向从本地服务改到 Headroom 代理：

export OPENAI_BASE_URL=http://127.0.0.1:8787/v1 export OPENAI_API_KEY=local

然后跑一个真实的任务。文档建议选择 coding-agent 的 refactor 类任务作为基准，因为这类任务会产生重复的文件读取、工具结果、lint/测试输出和不断增长的会话上下文。

运行期间打开 dashboard 观察：

headroom dashboard --port 8787 --no-open # 或直接打开 http://127.0.0.1:8787/dashboard

记录基线 session 的 token 总数。判断基线是否可信有一个文档给出的检查点：在--no-optimize下，before 和 after 的 token 计数应当一致，因为 Headroom 此时只是转发流量。

两次运行之间：重置基准状态

第二次运行前必须重置基准状态，否则两次结果不可比。文档列出的重置条件是：

• 回滚第一次运行造成的代码或数据变更（coding-agent 测试中，干净的 git worktree 是最简单的重置点）
• 开一个新的 agent session
• 使用相同的模型和本地服务
• 使用相同的 prompt
• 不改动无关的 flag 或服务端设置

第二步：不带 --no-optimize 的优化运行

重启 Headroom，去掉--no-optimize：

headroom proxy \ --port 8787 \ --openai-api-url http://127.0.0.1:8000

用相同的OPENAI_BASE_URL和 prompt 再跑一次同一任务，在 dashboard 上观察该 session 的 before/after token 计数。

这里的 savings 百分比是发往本地模型的 prompt token 减少量。需要注意它的含义边界：这不会让模型的 prefill kernel 本身变快，而是减少了 kernel 需要处理的 prompt 量。

可选：带 --learn 学习的运行

拿到基线后，可以把启用学习作为第三个独立条件来测：

headroom proxy \ --port 8787 \ --openai-api-url http://127.0.0.1:8000 \ --learn

--learn隐含启用 memory，让 Headroom 从 proxy session 中学习重复出现的流量模式。文档要求把它当作独立的 benchmark 条件处理：passthrough、optimized、optimized-with-learning 三种运行分别对比，不要混在一起归因。

记录与解读基准结果

一份可用的本地 prefill 基准报告，文档给出的字段如下：

解读时有两个文档明确给出的判断依据：

• 本地模型与托管 API 的价值不同：托管 API 下减少输入 token 通常意味着更低的成本和延迟；本地模型下，减少输入 token 主要意味着更少的 prefill 工作和更低的内存压力。
• 长会话的 agent 任务通常比短对话轮次收益更大，因为重复的文件读取、工具输出和日志会产生更多可压缩上下文；如果任务以短自然语言轮次为主，预期收益更小。

最后一条是文档强调的对比纪律：不要用冷启动的第一次运行去对比已经热身的第二次运行，再把全部改善归因于压缩。保持服务、模型、prompt 和 agent 任务稳定，以 dashboard 的 token 计数作为主要测量口径。

【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom