Headroom SDK 实战指南用 HeadroomClient 透明压缩 LLM 上下文并度量 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本文围绕 Headroom 官方 SDK 指南展开Headroom SDK 通过HeadroomClient包装你现有的 OpenAI / Anthropic / Google 客户端在请求发出前对消息尤其是大型工具输出执行确定性压缩与缓存优化同时保持调用方式与原客户端完全一致。读完本文你将掌握 SDK 的安装接入、三种运行模式optimize / audit / simulate的差异、按请求级别的覆盖参数、会话与历史指标的查询方式、错误处理体系以及底层_create调用链中「解析 → 变换 → 缓存优化 → 统计」的实际工作原理并了解 Python SDK 与 TypeScript SDK、独立代理Proxy三种接入形态的选型边界。一、安装与定位SDK 在 Headroom 中的角色Headroom 的核心卖点是「在内容到达 LLM 之前压缩它」——压缩工具输出、日志、文件与 RAG 分块从而降低每次请求的输入 Token。它提供三种接入形态SDK本文主题在你的应用进程内包装 LLM 客户端控制粒度最细指标在进程内可查Proxy把工具的 API 地址指向 Headroom 代理适合无法改代码的现成工具Claude Code、Cursor 等MCP Server以工具形式挂到支持 MCP 的 Agent 上。官方指南给出的 SDK 选型定位wiki/sdk.md维度SDKProxy接入方式包装客户端指向 URL控制粒度细粒度逐请求参数全局指标进程内集中式适合场景自研应用现成工具也就是说需要细粒度控制用 SDK管理现成工具用 Proxy。安装命令指南原文pip install headroom-ai openai二、快速上手HeadroomClient 如何包装现有客户端HeadroomClient的构造函数签名为源码见 headroom/client.pyHeadroomClient( original_client, # 底层 LLM 客户端OpenAI 风格 provider, # Provider 实例提供模型名/上下文限制/token 计数 store_urlNone, # 指标存储 URLsqlite:// 或 jsonl://默认临时目录 default_modeaudit, # 默认模式audit | optimize model_context_limitsNone, cache_optimizerNone, enable_cache_optimizerTrue, enable_semantic_cacheFalse, configNone, # 完整的 HeadroomConfig优先级高于上面的独立参数 )指南中的快速上手示例from headroom import HeadroomClient, OpenAIProvider from openai import OpenAI # 创建包装客户端 client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeoptimize, ) # 用法与原客户端完全一致 response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: user, content: Hello!}, ], ) print(response.choices[0].message.content)从源码结构看__init__内部依次完成四件事headroom/client.py初始化存储create_storage(store_url)。若未指定store_url默认落到sqlite:///tempdir/headroom.db开箱即用不污染项目目录构建变换管线TransformPipeline(self._config, providerself._provider)这是真正执行压缩的引擎初始化缓存优化器enable_cache_optimizerTrue且未显式传入cache_optimizer时会通过CacheOptimizerRegistry按 provider 名称自动探测OpenAI / Anthropic / Google 各有注册实现见 headroom/cache 模块 的导出列表enable_semantic_cacheTrue时再用SemanticCacheLayer包一层查询级语义缓存暴露两套 API 门面self.chat.completionsOpenAI 风格和self.messagesAnthropic 风格二者最终都汇入同一个内部_create方法只以api_styleopenai / anthropic区分。三、一次请求的完整处理链_create 源码剖析理解 SDK 行为的关键是HeadroomClient._createheadroom/client.py其内部流程为请求进入 │ ├─ 1. parse_messages(messages, tokenizer) # 把消息切成 Blocksystem/user/assistant/tool_call/tool_result/rag… ├─ 2. tokenizer.count_messages(messages) # 统计压缩前 tokens_before ├─ 3. CacheAligner.get_alignment_score(...) # 计算前缀缓存对齐分数 ├─ 4. compute_prefix_hash(messages) # 稳定前缀哈希 │ ├─ 5. 若 mode OPTIMIZE │ TransformPipeline.apply(messages, model, model_limit, output_buffer, tool_profiles) │ → 得到 optimized_messages / tokens_after / transforms_applied │ ├─ 6. 缓存优化 │ 若启用语义缓存 → SemanticCacheLayer.process(...)命中则直接返回缓存响应 │ 否则 → provider 专属 cache optimizer 处理断点/前缀对齐 │ ├─ 7. 通过 provider registry 把优化后的请求转发给 original_client ├─ 8. 写入 RequestMetrics 到存储SQLite并更新内存会话统计 └─ 9. 返回原始格式的响应对象对调用方透明几个要点Block 解析parse_messages将消息切分为带类型的原子块Block.kind包括system/user/assistant/tool_call/tool_result/rag/unknown定义见 headroom/config.py后续变换针对块级内容而非整条消息这保证了 tool_calls、角色顺序等结构不被破坏输出缓冲output_buffer配置项output_buffer_tokens默认 4000见 headroom/config.py为模型输出预留空间压缩预算 模型上下文上限 − 输出缓冲上下文上限解析顺序用户model_context_limits覆盖支持版本化名称的前缀匹配→ Provider 提供值见_get_context_limitheadroom/client.py与HeadroomConfig.get_context_limitheadroom/config.py。四、真正的价值点工具输出压缩指南强调「实际节省发生在工具输出上」。这是一个 500 条搜索结果被压缩的完整示例指南原文import json # 包含大型工具输出的对话 messages [ {role: user, content: Search for Python tutorials}, { role: assistant, content: None, tool_calls: [ { id: call_123, type: function, function: {name: search, arguments: {q: python}}, } ], }, { role: tool, tool_call_id: call_123, content: json.dumps( {results: [{title: fTutorial {i}, score: 100 - i} for i in range(500)]} ), }, {role: user, content: What are the top 3?}, ] # Headroom 将 500 条结果压缩到约 15 条保留得分最高的条目 response client.chat.completions.create(modelgpt-4o-mini, messagesmessages) # 查看节省 stats client.get_stats() print(fTokens saved: {stats[session][tokens_saved_total]}) # 典型输出: Tokens saved: 3500背后的执行者是SmartCrusher变换器它识别 JSON 列表/键值对结构按相关性评分BM25 始终可用embeddings 需要可选依赖 sentence-transformers见 headroom/init.py 的导出注释保留高价值条目、丢弃冗余长尾并保留错误项与异常值。管线完成时会输出日志如SmartCrusher: kept 15 of 1000 items见第七节日志。需要说明的是指南中「500 条 → 约 15 条」「3500 tokens」为示例性典型值实际保留数量取决于评分阈值与内容分布仓库中的 SmartCrusher 单测tests/test_smart_crusher.py覆盖了其保留/丢弃策略的回归行为。五、受支持的 ProviderOpenAIfrom headroom import HeadroomClient, OpenAIProvider from openai import OpenAI client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), )AnthropicAnthropic 走client.messages门面对应_create的api_styleanthropic分支headroom/client.pyfrom headroom import HeadroomClient, AnthropicProvider from anthropic import Anthropic client HeadroomClient( original_clientAnthropic(), providerAnthropicProvider(), ) response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, messages[{role: user, content: Hello!}], )Googlefrom headroom import HeadroomClient from headroom.providers import GoogleProvider import google.generativeai as genai client HeadroomClient( original_clientgenai, providerGoogleProvider(), )三个 Provider 均为懒加载导出headroom/providers/init.py 中按名称解析到headroom.providers.openai / anthropic / google子模块避免import headroom时提前加载各家 SDK。Provider 除提供上下文限制外还提供对应模型的 token 计数能力这直接决定tokens_before / tokens_after统计的精度。六、三种运行模式Optimize / Audit / Simulate模式由HeadroomMode枚举定义headroom/config.pyAUDIT只观察不修改、OPTIMIZE应用确定性变换、SIMULATE只返回变换计划。注意构造函数默认值为default_modeaudit即默认是安全审计模式需要显式传default_modeoptimize才实际压缩headroom/client.py。Optimize指南推荐的默认写法应用全部安全变换client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeoptimize, )Audit只观察和记录、不修改请求。适合上线前量化「如果开启压缩能省多少」client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeaudit, )在_create源码中audit 模式会跳过第 5 步的pipeline.apply但依然完成解析、token 统计、前缀哈希与指标落库——所以即使不改一个字节你也能持续拿到浪费信号waste signals与对齐分数。Simulate不发 API 请求、直接返回压缩计划适合在 CI 或成本预估脚本中离线评估plan client.chat.completions.simulate( modelgpt-4o, messageslarge_conversation, ) print(fWould save {plan.tokens_saved} tokens) print(fTransforms: {plan.transforms})simulate的返回对象是SimulationResult源码_simulateheadroom/client.py中可见其完整字段tokens_before / tokens_after / tokens_saved / transforms / estimated_savings按 provider 价格估算的单请求美元节省、messages_optimized可直接打印查看压缩后内容、block_breakdown、waste_signals、cache_alignment_score。它是真实变换管线的pipeline.simulate分支与 optimize 走同一套变换逻辑只是不落库、不转发。七、按请求覆盖参数headroom_* 系列create/messages.create/simulate均接受一组headroom_前缀的关键字参数headroom/client.py参数作用默认行为headroom_mode覆盖本次请求的模式audit / optimize用default_modeheadroom_cache_prefix_tokens目标缓存对齐前缀大小由管线配置决定headroom_output_buffer_tokens为输出预留的 token 数HeadroomConfig.output_buffer_tokens默认 4000headroom_keep_turns永不丢弃最近 N 轮对话管线默认headroom_tool_profiles按工具名定制压缩配置空 dict指南示例response client.chat.completions.create( modelgpt-4o, messages[...], # 覆盖本次请求的模式 headroom_modeaudit, # 为输出预留更多 token headroom_output_buffer_tokens8000, # 保留最后 5 轮 headroom_keep_turns5, )其余**kwargs原样透传给底层客户端因此temperature、tools等官方参数不受影响。八、验证与观测validate_setup、get_stats、日志验证安装配置result client.validate_setup() if not result[valid]: print(Setup issues:, result[issues])validate_setup的检查项在源码中有明确清单headroom/client.pyprovider 能否计数 token、存储是否可读、default_mode是否为合法枚举、缓存优化器如启用是否加载成功。返回结构为{valid, provider, storage, config, cache_optimizer}四组ok/error字段。会话统计无数据库查询stats client.get_stats() print(stats) # { # session: {requests_total: 10, tokens_saved_total: 5000, ...}, # config: {mode: optimize, provider: openai, ...}, # transforms: {smart_crusher_enabled: True, ...} # }从实现看headroom/client.pyget_stats读的是纯内存字典_session_stats零 I/Orequests_total / requests_optimized / requests_audit / tokens_saved_total / cache_hits五项计数器在每次_create结束时由_update_session_stats累加其中tokens_saved_total只累计 optimize 模式下的max(0, before - after)。配置段则暴露当前模式、provider 名、缓存优化器名与语义缓存开关transforms 段暴露smart_crusher_enabled与cache_aligner_enabled。开启日志import logging logging.basicConfig(levellogging.INFO) # 现在你将看到 # INFO:headroom.transforms.pipeline:Pipeline complete: 45000 - 4500 tokens # INFO:headroom.transforms.smart_crusher:SmartCrusher: kept 15 of 1000 items日志前缀对应源码模块headroom.transforms.pipeline报告每次管线执行的压缩前后 token 数headroom.transforms.smart_crusher报告保留条数是排查「压缩是否真的生效」的最直接手段。九、流式与错误处理流式流式对 SDK 是透明的——压缩发生在请求侧发出之前响应侧原样透传stream client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: Hello!}], streamTrue, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)异常体系Headroom 定义了统一的异常树全部继承自HeadroomError并携带机器可读的details字典headroom/exceptions.py异常触发场景ConfigurationError模式非法、配置缺失或组合不兼容ProviderErrorprovider 未识别、token 计数失败StorageError数据库连接失败、存储 URL 非法、写入失败CompressionError工具输出解析失败、JSON 结构非法TokenizationError未知模型分词、tiktoken 加载失败CacheError缓存存储/取回失败、CCR 错误ValidationErrorvalidate_setup校验失败raise_on_error场景TransformError单个变换SmartCrusher、ContentRouter 等执行失败指南的推荐捕获顺序子类在前、基类兜底from headroom import ( HeadroomClient, HeadroomError, ConfigurationError, ProviderError, ) try: response client.chat.completions.create(...) except ConfigurationError as e: print(fConfig issue: {e}) except ProviderError as e: print(fProvider issue: {e}) except HeadroomError as e: print(fHeadroom error: {e})由于__str__会把details拼进消息如Invalid mode foo (valid_modes...)直接打印异常即可拿到诊断细节无需额外解析。十、历史指标与高级配置历史指标查询与get_stats的内存统计不同get_metrics走的是持久化存储默认 SQLite支持时间/模型/模式过滤headroom/client.pyfrom datetime import datetime, timedelta metrics client.get_metrics( start_timedatetime.utcnow() - timedelta(hours1), limit100, ) for m in metrics: print(f{m.timestamp}: {m.tokens_input_before} - {m.tokens_input_after})返回的RequestMetrics数据模型定义在 headroom/config.py除 token 前后值外还包含变换列表、缓存命中情况等字段。另有get_summary(start_time, end_time)直接返回聚合统计。HeadroomClient同时支持上下文管理器with HeadroomClient(...) as client:退出时自动close()存储连接。高级配置指南指向完整配置文档 wiki/configuration.md并给出典型组合client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeoptimize, enable_cache_optimizerTrue, enable_semantic_cacheFalse, model_context_limits{ gpt-4o: 128000, gpt-4o-mini: 128000, }, )从源码补充几个容易踩的点model_context_limits只做用户覆盖DEFAULT_MODEL_CONTEXT_LIMITS是空字典headroom/config.py未覆盖的模型走 Provider 提供的上下文限制enable_semantic_cache默认关闭语义缓存叠加在 provider 缓存优化器之上带相似度阈值/TTL/条目上限由CacheOptimizerConfig控制开启后命中会直接返回缓存响应而不打上游store_url决定指标落盘位置sqlite://或jsonl://默认在系统临时目录多实例共享建议显式指定避免get_metrics读到的是临时库。十一、延伸TypeScript SDK 与生态除 Python SDK 外仓库在 sdk/typescript 提供了 TypeScript 实现与 Python 版能力对齐src/client.ts是核心包装客户端src/adapters/下提供 OpenAI、Anthropic、Gemini、Vercel AI 四家适配器另有simulate.ts干跑模拟、shared-context.ts多 Agent 共享上下文与 hooks 机制sdk/typescript/examples 目录含工具调用 Agent、流式聊天、结构化输出、多 provider 等可直接参考的示例测试覆盖见 sdk/typescript/test。Python 侧的演示脚本可参考 examples/context_compression_demo.py 与 examples/README.md。十二、小结什么时候用 SDK需求建议自研应用需要逐请求控制模式切换、输出缓冲、工具级 profilePython / TS SDK上线前先量化压缩收益、不动线上行为default_modeaudit或simulate()管理 Claude Code、Cursor 等现成工具Proxy指向 URL需要跨进程、集中式指标看板Proxy 集中存储SDK 的最小接入面只有三行pip install→HeadroomClient(original_client..., provider..., default_modeoptimize)→ 原样调用。压缩在请求侧完成、响应侧透明透传配合get_stats()/get_metrics()/ INFO 日志你可以在不改业务代码的前提下持续观测每次请求省了多少 token、应用了哪些变换从而把「上下文压缩」变成可验证、可回退切回 audit的工程能力。【免费下载链接】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），仅供参考 Headroom SDK 实战指南：用 HeadroomClient 透明压缩 LLM 上下文并度量 Token 节省
Headroom SDK 实战指南用 HeadroomClient 透明压缩 LLM 上下文并度量 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本文围绕 Headroom 官方 SDK 指南展开Headroom SDK 通过HeadroomClient包装你现有的 OpenAI / Anthropic / Google 客户端在请求发出前对消息尤其是大型工具输出执行确定性压缩与缓存优化同时保持调用方式与原客户端完全一致。读完本文你将掌握 SDK 的安装接入、三种运行模式optimize / audit / simulate的差异、按请求级别的覆盖参数、会话与历史指标的查询方式、错误处理体系以及底层_create调用链中「解析 → 变换 → 缓存优化 → 统计」的实际工作原理并了解 Python SDK 与 TypeScript SDK、独立代理Proxy三种接入形态的选型边界。一、安装与定位SDK 在 Headroom 中的角色Headroom 的核心卖点是「在内容到达 LLM 之前压缩它」——压缩工具输出、日志、文件与 RAG 分块从而降低每次请求的输入 Token。它提供三种接入形态SDK本文主题在你的应用进程内包装 LLM 客户端控制粒度最细指标在进程内可查Proxy把工具的 API 地址指向 Headroom 代理适合无法改代码的现成工具Claude Code、Cursor 等MCP Server以工具形式挂到支持 MCP 的 Agent 上。官方指南给出的 SDK 选型定位wiki/sdk.md维度SDKProxy接入方式包装客户端指向 URL控制粒度细粒度逐请求参数全局指标进程内集中式适合场景自研应用现成工具也就是说需要细粒度控制用 SDK管理现成工具用 Proxy。安装命令指南原文pip install headroom-ai openai二、快速上手HeadroomClient 如何包装现有客户端HeadroomClient的构造函数签名为源码见 headroom/client.pyHeadroomClient( original_client, # 底层 LLM 客户端OpenAI 风格 provider, # Provider 实例提供模型名/上下文限制/token 计数 store_urlNone, # 指标存储 URLsqlite:// 或 jsonl://默认临时目录 default_modeaudit, # 默认模式audit | optimize model_context_limitsNone, cache_optimizerNone, enable_cache_optimizerTrue, enable_semantic_cacheFalse, configNone, # 完整的 HeadroomConfig优先级高于上面的独立参数 )指南中的快速上手示例from headroom import HeadroomClient, OpenAIProvider from openai import OpenAI # 创建包装客户端 client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeoptimize, ) # 用法与原客户端完全一致 response client.chat.completions.create( modelgpt-4o-mini, messages[ {role: user, content: Hello!}, ], ) print(response.choices[0].message.content)从源码结构看__init__内部依次完成四件事headroom/client.py初始化存储create_storage(store_url)。若未指定store_url默认落到sqlite:///tempdir/headroom.db开箱即用不污染项目目录构建变换管线TransformPipeline(self._config, providerself._provider)这是真正执行压缩的引擎初始化缓存优化器enable_cache_optimizerTrue且未显式传入cache_optimizer时会通过CacheOptimizerRegistry按 provider 名称自动探测OpenAI / Anthropic / Google 各有注册实现见 headroom/cache 模块 的导出列表enable_semantic_cacheTrue时再用SemanticCacheLayer包一层查询级语义缓存暴露两套 API 门面self.chat.completionsOpenAI 风格和self.messagesAnthropic 风格二者最终都汇入同一个内部_create方法只以api_styleopenai / anthropic区分。三、一次请求的完整处理链_create 源码剖析理解 SDK 行为的关键是HeadroomClient._createheadroom/client.py其内部流程为请求进入 │ ├─ 1. parse_messages(messages, tokenizer) # 把消息切成 Blocksystem/user/assistant/tool_call/tool_result/rag… ├─ 2. tokenizer.count_messages(messages) # 统计压缩前 tokens_before ├─ 3. CacheAligner.get_alignment_score(...) # 计算前缀缓存对齐分数 ├─ 4. compute_prefix_hash(messages) # 稳定前缀哈希 │ ├─ 5. 若 mode OPTIMIZE │ TransformPipeline.apply(messages, model, model_limit, output_buffer, tool_profiles) │ → 得到 optimized_messages / tokens_after / transforms_applied │ ├─ 6. 缓存优化 │ 若启用语义缓存 → SemanticCacheLayer.process(...)命中则直接返回缓存响应 │ 否则 → provider 专属 cache optimizer 处理断点/前缀对齐 │ ├─ 7. 通过 provider registry 把优化后的请求转发给 original_client ├─ 8. 写入 RequestMetrics 到存储SQLite并更新内存会话统计 └─ 9. 返回原始格式的响应对象对调用方透明几个要点Block 解析parse_messages将消息切分为带类型的原子块Block.kind包括system/user/assistant/tool_call/tool_result/rag/unknown定义见 headroom/config.py后续变换针对块级内容而非整条消息这保证了 tool_calls、角色顺序等结构不被破坏输出缓冲output_buffer配置项output_buffer_tokens默认 4000见 headroom/config.py为模型输出预留空间压缩预算 模型上下文上限 − 输出缓冲上下文上限解析顺序用户model_context_limits覆盖支持版本化名称的前缀匹配→ Provider 提供值见_get_context_limitheadroom/client.py与HeadroomConfig.get_context_limitheadroom/config.py。四、真正的价值点工具输出压缩指南强调「实际节省发生在工具输出上」。这是一个 500 条搜索结果被压缩的完整示例指南原文import json # 包含大型工具输出的对话 messages [ {role: user, content: Search for Python tutorials}, { role: assistant, content: None, tool_calls: [ { id: call_123, type: function, function: {name: search, arguments: {q: python}}, } ], }, { role: tool, tool_call_id: call_123, content: json.dumps( {results: [{title: fTutorial {i}, score: 100 - i} for i in range(500)]} ), }, {role: user, content: What are the top 3?}, ] # Headroom 将 500 条结果压缩到约 15 条保留得分最高的条目 response client.chat.completions.create(modelgpt-4o-mini, messagesmessages) # 查看节省 stats client.get_stats() print(fTokens saved: {stats[session][tokens_saved_total]}) # 典型输出: Tokens saved: 3500背后的执行者是SmartCrusher变换器它识别 JSON 列表/键值对结构按相关性评分BM25 始终可用embeddings 需要可选依赖 sentence-transformers见 headroom/init.py 的导出注释保留高价值条目、丢弃冗余长尾并保留错误项与异常值。管线完成时会输出日志如SmartCrusher: kept 15 of 1000 items见第七节日志。需要说明的是指南中「500 条 → 约 15 条」「3500 tokens」为示例性典型值实际保留数量取决于评分阈值与内容分布仓库中的 SmartCrusher 单测tests/test_smart_crusher.py覆盖了其保留/丢弃策略的回归行为。五、受支持的 ProviderOpenAIfrom headroom import HeadroomClient, OpenAIProvider from openai import OpenAI client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), )AnthropicAnthropic 走client.messages门面对应_create的api_styleanthropic分支headroom/client.pyfrom headroom import HeadroomClient, AnthropicProvider from anthropic import Anthropic client HeadroomClient( original_clientAnthropic(), providerAnthropicProvider(), ) response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1024, messages[{role: user, content: Hello!}], )Googlefrom headroom import HeadroomClient from headroom.providers import GoogleProvider import google.generativeai as genai client HeadroomClient( original_clientgenai, providerGoogleProvider(), )三个 Provider 均为懒加载导出headroom/providers/init.py 中按名称解析到headroom.providers.openai / anthropic / google子模块避免import headroom时提前加载各家 SDK。Provider 除提供上下文限制外还提供对应模型的 token 计数能力这直接决定tokens_before / tokens_after统计的精度。六、三种运行模式Optimize / Audit / Simulate模式由HeadroomMode枚举定义headroom/config.pyAUDIT只观察不修改、OPTIMIZE应用确定性变换、SIMULATE只返回变换计划。注意构造函数默认值为default_modeaudit即默认是安全审计模式需要显式传default_modeoptimize才实际压缩headroom/client.py。Optimize指南推荐的默认写法应用全部安全变换client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeoptimize, )Audit只观察和记录、不修改请求。适合上线前量化「如果开启压缩能省多少」client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeaudit, )在_create源码中audit 模式会跳过第 5 步的pipeline.apply但依然完成解析、token 统计、前缀哈希与指标落库——所以即使不改一个字节你也能持续拿到浪费信号waste signals与对齐分数。Simulate不发 API 请求、直接返回压缩计划适合在 CI 或成本预估脚本中离线评估plan client.chat.completions.simulate( modelgpt-4o, messageslarge_conversation, ) print(fWould save {plan.tokens_saved} tokens) print(fTransforms: {plan.transforms})simulate的返回对象是SimulationResult源码_simulateheadroom/client.py中可见其完整字段tokens_before / tokens_after / tokens_saved / transforms / estimated_savings按 provider 价格估算的单请求美元节省、messages_optimized可直接打印查看压缩后内容、block_breakdown、waste_signals、cache_alignment_score。它是真实变换管线的pipeline.simulate分支与 optimize 走同一套变换逻辑只是不落库、不转发。七、按请求覆盖参数headroom_* 系列create/messages.create/simulate均接受一组headroom_前缀的关键字参数headroom/client.py参数作用默认行为headroom_mode覆盖本次请求的模式audit / optimize用default_modeheadroom_cache_prefix_tokens目标缓存对齐前缀大小由管线配置决定headroom_output_buffer_tokens为输出预留的 token 数HeadroomConfig.output_buffer_tokens默认 4000headroom_keep_turns永不丢弃最近 N 轮对话管线默认headroom_tool_profiles按工具名定制压缩配置空 dict指南示例response client.chat.completions.create( modelgpt-4o, messages[...], # 覆盖本次请求的模式 headroom_modeaudit, # 为输出预留更多 token headroom_output_buffer_tokens8000, # 保留最后 5 轮 headroom_keep_turns5, )其余**kwargs原样透传给底层客户端因此temperature、tools等官方参数不受影响。八、验证与观测validate_setup、get_stats、日志验证安装配置result client.validate_setup() if not result[valid]: print(Setup issues:, result[issues])validate_setup的检查项在源码中有明确清单headroom/client.pyprovider 能否计数 token、存储是否可读、default_mode是否为合法枚举、缓存优化器如启用是否加载成功。返回结构为{valid, provider, storage, config, cache_optimizer}四组ok/error字段。会话统计无数据库查询stats client.get_stats() print(stats) # { # session: {requests_total: 10, tokens_saved_total: 5000, ...}, # config: {mode: optimize, provider: openai, ...}, # transforms: {smart_crusher_enabled: True, ...} # }从实现看headroom/client.pyget_stats读的是纯内存字典_session_stats零 I/Orequests_total / requests_optimized / requests_audit / tokens_saved_total / cache_hits五项计数器在每次_create结束时由_update_session_stats累加其中tokens_saved_total只累计 optimize 模式下的max(0, before - after)。配置段则暴露当前模式、provider 名、缓存优化器名与语义缓存开关transforms 段暴露smart_crusher_enabled与cache_aligner_enabled。开启日志import logging logging.basicConfig(levellogging.INFO) # 现在你将看到 # INFO:headroom.transforms.pipeline:Pipeline complete: 45000 - 4500 tokens # INFO:headroom.transforms.smart_crusher:SmartCrusher: kept 15 of 1000 items日志前缀对应源码模块headroom.transforms.pipeline报告每次管线执行的压缩前后 token 数headroom.transforms.smart_crusher报告保留条数是排查「压缩是否真的生效」的最直接手段。九、流式与错误处理流式流式对 SDK 是透明的——压缩发生在请求侧发出之前响应侧原样透传stream client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: Hello!}], streamTrue, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)异常体系Headroom 定义了统一的异常树全部继承自HeadroomError并携带机器可读的details字典headroom/exceptions.py异常触发场景ConfigurationError模式非法、配置缺失或组合不兼容ProviderErrorprovider 未识别、token 计数失败StorageError数据库连接失败、存储 URL 非法、写入失败CompressionError工具输出解析失败、JSON 结构非法TokenizationError未知模型分词、tiktoken 加载失败CacheError缓存存储/取回失败、CCR 错误ValidationErrorvalidate_setup校验失败raise_on_error场景TransformError单个变换SmartCrusher、ContentRouter 等执行失败指南的推荐捕获顺序子类在前、基类兜底from headroom import ( HeadroomClient, HeadroomError, ConfigurationError, ProviderError, ) try: response client.chat.completions.create(...) except ConfigurationError as e: print(fConfig issue: {e}) except ProviderError as e: print(fProvider issue: {e}) except HeadroomError as e: print(fHeadroom error: {e})由于__str__会把details拼进消息如Invalid mode foo (valid_modes...)直接打印异常即可拿到诊断细节无需额外解析。十、历史指标与高级配置历史指标查询与get_stats的内存统计不同get_metrics走的是持久化存储默认 SQLite支持时间/模型/模式过滤headroom/client.pyfrom datetime import datetime, timedelta metrics client.get_metrics( start_timedatetime.utcnow() - timedelta(hours1), limit100, ) for m in metrics: print(f{m.timestamp}: {m.tokens_input_before} - {m.tokens_input_after})返回的RequestMetrics数据模型定义在 headroom/config.py除 token 前后值外还包含变换列表、缓存命中情况等字段。另有get_summary(start_time, end_time)直接返回聚合统计。HeadroomClient同时支持上下文管理器with HeadroomClient(...) as client:退出时自动close()存储连接。高级配置指南指向完整配置文档 wiki/configuration.md并给出典型组合client HeadroomClient( original_clientOpenAI(), providerOpenAIProvider(), default_modeoptimize, enable_cache_optimizerTrue, enable_semantic_cacheFalse, model_context_limits{ gpt-4o: 128000, gpt-4o-mini: 128000, }, )从源码补充几个容易踩的点model_context_limits只做用户覆盖DEFAULT_MODEL_CONTEXT_LIMITS是空字典headroom/config.py未覆盖的模型走 Provider 提供的上下文限制enable_semantic_cache默认关闭语义缓存叠加在 provider 缓存优化器之上带相似度阈值/TTL/条目上限由CacheOptimizerConfig控制开启后命中会直接返回缓存响应而不打上游store_url决定指标落盘位置sqlite://或jsonl://默认在系统临时目录多实例共享建议显式指定避免get_metrics读到的是临时库。十一、延伸TypeScript SDK 与生态除 Python SDK 外仓库在 sdk/typescript 提供了 TypeScript 实现与 Python 版能力对齐src/client.ts是核心包装客户端src/adapters/下提供 OpenAI、Anthropic、Gemini、Vercel AI 四家适配器另有simulate.ts干跑模拟、shared-context.ts多 Agent 共享上下文与 hooks 机制sdk/typescript/examples 目录含工具调用 Agent、流式聊天、结构化输出、多 provider 等可直接参考的示例测试覆盖见 sdk/typescript/test。Python 侧的演示脚本可参考 examples/context_compression_demo.py 与 examples/README.md。十二、小结什么时候用 SDK需求建议自研应用需要逐请求控制模式切换、输出缓冲、工具级 profilePython / TS SDK上线前先量化压缩收益、不动线上行为default_modeaudit或simulate()管理 Claude Code、Cursor 等现成工具Proxy指向 URL需要跨进程、集中式指标看板Proxy 集中存储SDK 的最小接入面只有三行pip install→HeadroomClient(original_client..., provider..., default_modeoptimize)→ 原样调用。压缩在请求侧完成、响应侧透明透传配合get_stats()/get_metrics()/ INFO 日志你可以在不改业务代码的前提下持续观测每次请求省了多少 token、应用了哪些变换从而把「上下文压缩」变成可验证、可回退切回 audit的工程能力。【免费下载链接】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），仅供参考