如何用 Headroom 的 simulate 模拟调用预览压缩节省而不发送请求到 LLM【免费下载链接】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如果你想知道 Headroom 对你的一组消息实际能压缩掉多少 token、会应用哪些压缩变换但又不想把消息真正发给 LLM 产生费用和延迟可以用simulate模拟调用。它在本地跑完整个变换管线返回压缩后的消息、节省的 token 数和浪费信号分析全程不调用 LLM APISimulation 文档。本文基于 Headroom Python SDK走通从安装、构造消息、执行模拟到读取结果的完整路径最后给出 TypeScript SDK 的等价做法。安装 Python SDK按 Quickstart 给出的方式安装# Python 项目或 virtualenv pip install headroom-ai[all] # 或者作为独立 CLI 工具安装CLI/proxy/wrap 场景 uv tool install --python 3.13 headroom-ai[all]准备一组消息并执行第一次模拟先用一组 OpenAI 格式的消息作为输入。下面沿用 Quickstart 文档中的示例消息一个系统提示、一条用户消息、一条带tool_calls的 assistant 消息、一条包含 500 条搜索结果 JSON 数组的tool输出以及一条收尾用户消息。工具输出是 Headroom 压缩收益的主要来源所以示例特意放大了这个部分from openai import OpenAI from headroom import HeadroomClient, OpenAIProvider import json messages [ {role: system, content: You analyze search results.}, {role: user, content: Search for Python tutorials.}, { role: assistant, content: None, tool_calls: [{ id: call_1, type: function, function: {name: search, arguments: {q: python}}, }], }, { role: tool, tool_call_id: call_1, content: json.dumps({ results: [ {title: fResult {i}, snippet: fDescription {i}, score: 100 - i} for i in range(500) ] }), }, {role: user, content: What are the top 3 results?}, ] client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), ) plan client.chat.completions.simulate( modelgpt-4o, messagesmessages, )client.chat.completions.simulate()的签名见 API Reference实现位于 ChatCompletions.simulate。model用于 token 计数与上下文限制messages为要预览的会话headroom_mode默认值为optimize其余透传的参数会被忽略。读取 SimulationResultsimulate返回SimulationResult字段定义见 config.py字段含义tokens_before/tokens_after/tokens_saved压缩前后 token 数与节省量transforms本次应用的变换列表list[str]estimated_savings人类可读的费用估算messages_optimized压缩后的完整消息列表block_breakdown按块类型统计的 token 分布dict[str, int]waste_signals各类 token 浪费来源dict[str, int]stable_prefix_hash/cache_alignment_score前缀哈希与缓存对齐评分基本输出print(fTokens before: {plan.tokens_before}) print(fTokens after: {plan.tokens_after}) print(fWould save: {plan.tokens_saved} tokens ({plan.tokens_saved/plan.tokens_before*100:.1f}%)) print(fTransforms: {plan.transforms})Quickstart 中展示的示例输出文档示例数值会随你的消息内容变化Tokens before: 45000 Tokens after: 4500 Tokens saved: 40500 Compression: 90% Transforms: [smart_crusher, cache_aligner]用 waste_signals 定位浪费来源waste_signals告诉你输入里哪些部分贡献了最多的不必要 tokenwaste plan.waste_signals # dict[str, int] print(fJSON bloat: {waste[json_bloat]} tokens) print(fHTML noise: {waste[html_noise]} tokens) print(fWhitespace: {waste[whitespace]} tokens) print(fDynamic dates: {waste[dynamic_date]} tokens) print(fRepetition: {waste[repetition]} tokens)用 block_breakdown 看 token 集中在哪类消息解析器会把会话拆成块block_breakdown给出每类块的 token 数。块类型如下Simulation 文档块类型说明system系统提示user用户消息assistant模型回复tool_call函数调用请求tool_result工具输出最大的浪费来源rag检索文档上下文没有压缩时先查什么如果plan.tokens_saved 0文档给出的排查方向是Simulation 文档if plan.tokens_saved 0: print(No compression applied. Possible reasons:) print(- Messages are too short ( 200 tokens per tool output)) print(- No tool outputs with compressible JSON arrays) print(- Content is already compact (code, grep results)) else: print(fTransforms applied: {plan.transforms}) print(json.dumps(plan.messages_optimized, indent2))即依次对照单条工具输出是否短于 200 token、是否存在可压缩的 JSON 数组合成工具输出、内容是否本来就紧凑代码、grep 结果。有压缩时plan.messages_optimized可以直接查看压缩后的消息长什么样。对一组样本估算整体节省在正式开启压缩前可以用simulate对一份代表性工作负载做批量估算import json total_before 0 total_after 0 for messages in sample_conversations: plan client.chat.completions.simulate( modelgpt-4o, messagesmessages, ) total_before plan.tokens_before total_after plan.tokens_after savings_pct (1 - total_after / total_before) * 100 print(fEstimated savings: {savings_pct:.1f}%) print(fTokens saved: {total_before - total_after:,})其中sample_conversations是你自己准备的消息样本列表。实际节省取决于内容冗余程度Quickstart 指出 savings depend heavily on how repetitive the content is所以估算结果只对所用样本有效。可选对比不同的压缩配置如果想在同一组消息上比较不同配置的压缩强度可以为每个配置单独建一个客户端再模拟from headroom import HeadroomClient, HeadroomConfig, OpenAIProvider from headroom.transforms import SmartCrusherConfig configs [ SmartCrusherConfig(max_items_after_crush10), SmartCrusherConfig(max_items_after_crush25), SmartCrusherConfig(max_items_after_crush50), ] for smart_crusher_config in configs: client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), configHeadroomConfig(smart_crushersmart_crusher_config), ) plan client.chat.completions.simulate(modelgpt-4o, messagesmessages) print(fmax_items{smart_crusher_config.max_items_after_crush}: f{plan.tokens_saved} tokens saved ({plan.tokens_saved/plan.tokens_before*100:.1f}%))这条路径只服务于「找适合自己负载的参数」日常预览不需要。TypeScript SDK 等价做法TypeScript 侧没有simulate方法但compress()返回相同的结果结构直接不把它发给 LLM 就是模拟Simulation 文档import { compress } from headroom-ai; const result await compress(messages, { model: gpt-4o, baseUrl: http://localhost:8787, }); console.log(Would save: ${result.tokensSaved} tokens); console.log(Compression ratio: ${(result.compressionRatio * 100).toFixed(1)}%); console.log(Transforms: ${result.transformsApplied.join(, )});注意前提TypeScript SDK 是通过本地 Headroom proxy 执行压缩管线的必须先启动 proxyQuickstartuv tool install --python 3.13 headroom-ai[proxy] # 或者在 Python 项目内pip install headroom-ai[proxy] headroom proxy --port 8787限制说明模拟永远不会调用 LLM API它在本地运行完整的变换管线并返回结果因此没有 provider 侧的费用和延迟Simulation 文档 的说明。文档中出现的45000 - 4500、90%等均为文档示例数值不是你输入必然得到的结果不同消息的节省比例差异很大。simulate只接受model、messages以及headroom_mode、headroom_output_buffer_tokens、headroom_tool_profiles这几个 Headroom 参数额外传的参数会被忽略见 simulate 实现。想进一步了解压缩管线内部如何工作可以阅读仓库中的 How Compression Works 与 Configuration。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考