Headroom × LangChain 实战用 SmartCrusher 压缩 Agent 工具输出节省 74% Token 且 100% 保留 ERROR【免费下载链接】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本文以仓库examples/langchain_demo/下的 LangChain 演示套件为核心讲解 Headroom 如何在 LangChain Agent 的工具调用链路上做上下文压缩先通过三个可直接运行的脚本无需 API Key 即可演示看到 SmartCrusher 对大 JSON 工具输出的 before/after 效果再结合 smart_crusher 源码、SmartCrusherConfig 配置 与 HeadroomChatModel 集成层 拆解其保 ERROR、保首尾、保异常点、按相关性打分的压缩策略最后给出完整 Agent 前后对比的运行方式与成本测算方法。为什么工具输出是 Agent 的 Token 大头examples/langchain_demo/是一个面向真实场景的演示模拟一个客服/运维 Agent它通过 5 个工具查用户库、搜文档、翻日志、看指标、拉 API 数据——每个工具都返回 50~200 条记录的 JSON。这类数据库查询返回上百行、日志搜索返回几百条的输出正是 Agent 对话中 token 膨胀的主要来源。演示目录的完整文件布局见 examples/langchain_demo/README.md文件作用mock_tools.py5 个仿真工具生成真实感的大体积 JSON 输出show_compression.py独立压缩演示无需 API Keyverify_errors_kept.py验证 ERROR 条目 100% 保留run_comparison.py完整 Agent before/after 对比需 OPENAI_API_KEY演示工具集mock_tools.py 输出了什么mock_tools.py 用随机数据模拟 5 类真实 API 响应并在 TOOL_FUNCTIONS 字典 中统一注册工具模拟场景条数顶层 JSON 键search_users用户库查询部门、状态、角色、偏好元数据100resultssearch_logs日志检索DEBUG/INFO/WARN/ERROR按时间倒序200entriesget_metrics5 分钟粒度时序指标CPU、内存、延迟、错误率5% 概率注入异常点100metricssearch_docs文档/知识库检索按 relevance_score 排序50resultsfetch_api_data分页 API含 pagination 元信息75data几个细节值得注意日志生成器 generate_log_entries 用权重列表[DEBUG, INFO, INFO, INFO, WARN, ERROR]让大多数条目是 INFO只有少数是 ERROR——这正好复现几百条日志里只有几条是错误的真实排查场景。指标生成器 generate_metrics_data 以 5% 概率注入 CPU 60-95%、错误率 5-15% 的异常点用于验证 SmartCrusher 的统计异常检测能力。search_docs的返回会按relevance_score降序排序fetch_api_data带pagination.total_pages10用来考察保留首尾条目 相关性 Top-N策略。快速开始三个脚本的运行方式以下命令均在仓库根目录下执行依赖tiktoken以及完整对比所需的 LangChain# 1. 演示压缩效果无需 API Key PYTHONPATH. python -m examples.langchain_demo.show_compression # 2. 验证 ERROR 条目 100% 保留 PYTHONPATH. python -m examples.langchain_demo.verify_errors_kept # 3. 完整 Agent 对比需要 OPENAI_API_KEY export OPENAI_API_KEYyour-key-here PYTHONPATH. python -m examples.langchain_demo.run_comparisonshow_compression单工具 before/after 压缩演示show_compression.py 的核心流程在 demonstrate_compression() 中值得逐段看因为它展示了 Headroom 的transform 级用法不经过完整 pipeline直接调用 SmartCrusher第一步构造 SmartCrusher 并注入上下文。脚本用 SmartCrusherConfig 配置压缩器并通过OpenAIProvider().get_token_counter(gpt-4o)获取真实 tokenizertoken 计数接口定义见 providers/base.pyfrom headroom.config import SmartCrusherConfig from headroom.providers import OpenAIProvider from headroom.transforms import SmartCrusher smart_config SmartCrusherConfig( enabledTrue, min_tokens_to_crush200, # 只有超过 200 token 才压缩 max_items_after_crush20, # 压缩后最多保留 20 条 ) provider OpenAIProvider() tokenizer provider.get_token_counter(gpt-4o) crusher SmartCrusher(configsmart_config)第二步把工具输出放进标准 Agent 对话消息序列。脚本构造了 system → user带问题上下文→ assistant(tool_calls) → tool 四条消息模拟真实 Agent 中用户提问后工具返回大 JSON的形态messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: context}, # 用户问题作为相关性上下文 {role: assistant, content: None, tool_calls: [{id: call_1, function: {name: tool_name, arguments: ...}}]}, {role: tool, content: raw_output, tool_call_id: call_1}, ] result crusher.apply(messages, tokenizertokenizer)关键点SmartCrusher 的apply()接收的是整条消息序列token 计数由调用方以tokenizer参数传入压缩后的结果从result.messages最后一条 tool 消息取出。第三步五个演示场景。main() 依次运行 5 个场景每个场景的用户上下文都刻意指向数据中存在的特征活跃工程用户、ERROR 日志、CPU 尖峰、认证文档、pending 订单让相关性打分有命中目标最后汇总输出各工具的前后 token 数与总成本。README 记录的实测结果README 的 Token Savings 表 给出了该演示的基准运行结果token 计数基于 cl100k_base工具压缩前压缩后节省search_users (100 items)15,4532,01487%search_logs (200 items)25,6793,21387%get_metrics (100 items)11,5178,42527%search_docs (50 items)6,9122,12769%fetch_api_data (75 items)15,7863,62277%合计75,34719,40174%注意get_metrics只有 27% 的节省率——因为时序指标每条记录字段少、数值密度高且异常点必须保留而日志/用户库这类长文本 大量无关行的结构压缩率最高。按 gpt-4o $2.50/1M 输入 token 计价单请求约 $0.19 → $0.05按每天 1000 次请求估算每月可节省约 $4,196。这些数字来自演示脚本自身的输出逻辑show_compression.py 的成本段实际节省取决于你的真实工具输出分布。SmartCrusher 的五大保留策略与配置参数SmartCrusherConfig 的 docstring 写明了设计目标保留原始 JSON Schema 不变——输出只包含原数组中的条目不包装、不生成文本、不加元数据。README 概括的五条压缩策略与其配置一一对应100% 保留 ERROR 条目——错误项永不丢弃源码中 Error items never dropped保留首/尾条目——first_fraction: 0.3/last_fraction: 0.15控制 Kneedle 自适应 K 值中首尾各占的比例默认 30%/15%其余名额给重要性打分用于分页上下文保留统计异常点——数值偏离均值超过variance_threshold默认 2.0 个标准差的条目保留捕获 CPU 尖峰、内存飙升等相关性打分——通过RelevanceScorerConfigrelevance字段让匹配用户查询的条目优先入坑变化点保留——preserve_change_points: True在数据发生显著跳变的位置留样。完整参数表默认值均来自 config.py参数默认值说明enabledTrue工具输出压缩的默认实现min_items_to_analyze5小于该条数的小数组不做统计分析min_tokens_to_crush200仅当输出超过该 token 数才压缩variance_threshold2.0变化点检测的标准差倍数调低如 1.5 更保守uniqueness_threshold0.1低于该值视为近常量字段similarity_threshold0.8相似字符串聚类阈值max_items_after_crush15压缩后目标最大条数演示中调为 20preserve_change_pointsTrue保留数据跳变点factor_out_constantsFalse不抽取常量保持原 schemainclude_summariesFalse不生成摘要文本dedup_identical_itemsTrue多种保留机制选中同一条目时只保留一份lossless_min_savings_ratio0.15无损表格化路径相对有损路径的最小字节节省比lossless_onlyFalse严格无损模式宁可放弃压缩也不产生 CCR 标记docstring 同时列出了已知边界GOTCHAS统计分析每条约 5-10ms 开销变化点检测用固定窗口5 条可能漏掉缓慢渐变Top-N 策略假设分数越高越相关。官方建议关键数据可调高max_items_after_crushvariance_threshold调低。实现入口是 headroom/transforms/smart_crusher.py 中的SmartCrusher类第 242 行它作为Transform接入 Headroom 的TransformPipeline。verify_errors_keptERROR 保留的自动化验证verify_errors_kept.py 是一个可直接执行的不变量检查流程为用generate_log_entries(test-service, count200)生成 200 条日志统计其中level ERROR的原始条数以相同配置min_tokens_to_crush200,max_items_after_crush20构造 SmartCrusher把日志作为 tool 消息压缩用户上下文设为 Find ERROR entries in the logs解析压缩后 JSON若 SmartCrusher 附加了标记文本脚本会用正则(\{.*\})兜底提取 JSON 主体见 第 59-73 行比对 ERROR 条数。判定逻辑在 第 84-91 行压缩后 ERROR 条数 ≥ 原始则输出SUCCESS: All ERROR entries were preserved部分保留输出PARTIAL一条不留输出FAILURE。README 记录的测试运行结果是 27/27 全部保留同时 200 条日志被压到约 20 条——即数量砍到 10%关键信息 100% 存活。这也是该演示最想传达的工程原则压缩的验收标准不是压缩率而是关键数据的不丢失。run_comparison完整 Agent 的 before/after 对比run_comparison.py 把对比拉到完整 Agent 层面同一个支持 Agent、同一组工具、同一批用户问题分别以 baseline裸模型和 headroom包装后模型各跑一遍。三个对比场景SCENARIOS 定义了三个贴近真实工单的问题User Account Investigation——某用户无法登录查账户状态 日志认证错误 相关文档Service Performance Investigation——payment-service 变慢查指标异常 近期错误日志 性能排障文档Multi-User Issue——工程部门多名用户报错搜工程用户 查 user-service 日志 查文档。两侧的运行方式Baseline 侧run_agent_baseline是标准 LangChain 工具循环ChatOpenAI(modelgpt-4o-mini, temperature0).bind_tools(tools)最多 5 轮迭代每轮累加输入 token本地计数、执行模型请求的工具调用、把结果作为ToolMessage追加回对话。Headroom 侧run_agent_headroom唯一区别是用HeadroomChatModel包装同一模型压缩在invoke()内部发生工具循环代码完全不变from headroom import HeadroomConfig from headroom.integrations import HeadroomChatModel base_model ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) config HeadroomConfig( smart_crusher_threshold500, # 工具输出 500 tokens 才压缩 smart_crusher_max_items20, # 最多保留 20 条 cache_alignmentTrue, # 稳定 system prompt 提升缓存命中 rolling_windowTrue, ) headroom_model HeadroomChatModel( wrapped_modelbase_model, headroom_configconfig, ).bind_tools(tools)跑完后脚本用headroom_model.get_total_tokens_saved()取 Headroom 自报的节省量从累计输入 token 中扣除得到实际发送给上游的 token 数。两点版本说明需要留意以当前仓库源码为准从 headroom/config.py 的 HeadroomConfig 结构看当前版本采用嵌套配置smart_crusher: SmartCrusherConfig字段承载压缩参数即min_tokens_to_crush/max_items_after_crush示例脚本中扁平的smart_crusher_threshold500, smart_crusher_max_items20写法属于演示脚本自身的历史 API在当前源码上运行前建议以HeadroomConfig(smart_crusherSmartCrusherConfig(...))的写法为准具体以 headroom/integrations/langchain/chat_model.py 对HeadroomConfig的消费方式为准。对比脚本调用的get_total_tokens_saved()方法在当前 chat_model.py 中对应的是total_tokens_saved属性与get_savings_summary()方法运行新版源码时注意按属性访问。输出与成本核算print_comparison() 为每个场景输出对照表输入/输出 token、工具调用次数、消息数、耗时以及按 gpt-4o-mini 价格$0.15/1M 输入、$0.60/1M 输出估算的美元成本与节省百分比。无 API Key 时脚本自动降级为 SIMULATION 模式只统计 3 个工具输出的 token 体量并给出约 5 倍压缩的估算max 20 items 上限下的粗略值。集成层原理为什么 Headroom 选择包装 ChatModelheadroom/integrations/langchain/chat_model.py 的模块 docstring 解释了架构动机LangChain 的 callback 机制按设计不能修改消息所以 Headroom 不挂 callback 改消息而是直接包装BaseChatModel本身——HeadroomChatModel第 118 行继承自BaseChatModel对外表现为一个普通 LangChain 模型。关键实现点懒加载 pipeline 与 provider 自动探测pipeline property 在首次调用时根据wrapped_model的类路径探测上游厂商ChatOpenAI → OpenAIProvider 等再构建TransformPipeline(config, provider)保证 token 计数与目标 provider 一致工具调用兼容bind_tools()被重写第 512 行返回包装后的HeadroomChatModel因此对比脚本里.bind_tools(tools)后依然能继续被 Headroom 拦截可观测性每次优化产生一条OptimizationMetricstokens_before/after、savings_percent、transforms_applied累积在metrics_history与total_tokens_savedget_savings_summary()提供汇总第 522 行多入口除HeadroomChatModel外integrations/langchain/init.py 还导出 Agent/Retriever/Streaming/LangGraph 等封装并有独立的optimize_messages()函数第 916 行供手工调用依赖方面pyproject.toml提供langchainextralangchain-core1.3.3、langchain-openai1.1.14见 pyproject.toml 第 212-214 行演示脚本则额外要求tiktoken。测试与回归验证LangChain 集成的回归测试集中在 tests/test_integrations/langchain/ 目录包含 test_chat_model.py、test_evals.py、test_agents.py、test_streaming.py、test_langgraph.py 等。README 提到的 12 项 eval 覆盖ERROR 保留100%、异常检测、相关性匹配、压缩效率、schema 保留与边缘用例。需要说明README 中给出的 eval 命令pytest tests/test_integrations/test_langchain_evals.py -v对应的文件在当前仓库中不存在实际为 tests/test_integrations/langchain/test_evals.py运行前请以目录内实际文件名为准PYTHONPATH. pytest tests/test_integrations/langchain/ -v适用前提与小结环境仓库根目录运行PYTHONPATH.show_compression/verify_errors_kept仅需tiktokenrun_comparison需要langchain-core、langchain-openai与OPENAI_API_KEY真实模式会产生 API 费用数据边界演示 token 数字基于 mock 数据与 cl100k_base 计数README 中的 74% 总节省率与成本折算是该仿真场景下的结果不代表所有工作负载get_metrics类高密度时序数据节省率明显低于长文本类输出核心结论这套演示展示了一条完整的落地路径——用 SmartCrusher 的统计保真压缩错误/首尾/异常点/相关性/变化点五重保留处理工具输出用 HeadroomChatModel 以包装 ChatModel方式零侵入接入 LangChain Agent最终在 token 大幅下降的同时维持关键信息 100% 可达。【免费下载链接】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 × LangChain 实战：用 SmartCrusher 压缩 Agent 工具输出，节省 74% Token 且 100% 保留 ERROR
Headroom × LangChain 实战用 SmartCrusher 压缩 Agent 工具输出节省 74% Token 且 100% 保留 ERROR【免费下载链接】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本文以仓库examples/langchain_demo/下的 LangChain 演示套件为核心讲解 Headroom 如何在 LangChain Agent 的工具调用链路上做上下文压缩先通过三个可直接运行的脚本无需 API Key 即可演示看到 SmartCrusher 对大 JSON 工具输出的 before/after 效果再结合 smart_crusher 源码、SmartCrusherConfig 配置 与 HeadroomChatModel 集成层 拆解其保 ERROR、保首尾、保异常点、按相关性打分的压缩策略最后给出完整 Agent 前后对比的运行方式与成本测算方法。为什么工具输出是 Agent 的 Token 大头examples/langchain_demo/是一个面向真实场景的演示模拟一个客服/运维 Agent它通过 5 个工具查用户库、搜文档、翻日志、看指标、拉 API 数据——每个工具都返回 50~200 条记录的 JSON。这类数据库查询返回上百行、日志搜索返回几百条的输出正是 Agent 对话中 token 膨胀的主要来源。演示目录的完整文件布局见 examples/langchain_demo/README.md文件作用mock_tools.py5 个仿真工具生成真实感的大体积 JSON 输出show_compression.py独立压缩演示无需 API Keyverify_errors_kept.py验证 ERROR 条目 100% 保留run_comparison.py完整 Agent before/after 对比需 OPENAI_API_KEY演示工具集mock_tools.py 输出了什么mock_tools.py 用随机数据模拟 5 类真实 API 响应并在 TOOL_FUNCTIONS 字典 中统一注册工具模拟场景条数顶层 JSON 键search_users用户库查询部门、状态、角色、偏好元数据100resultssearch_logs日志检索DEBUG/INFO/WARN/ERROR按时间倒序200entriesget_metrics5 分钟粒度时序指标CPU、内存、延迟、错误率5% 概率注入异常点100metricssearch_docs文档/知识库检索按 relevance_score 排序50resultsfetch_api_data分页 API含 pagination 元信息75data几个细节值得注意日志生成器 generate_log_entries 用权重列表[DEBUG, INFO, INFO, INFO, WARN, ERROR]让大多数条目是 INFO只有少数是 ERROR——这正好复现几百条日志里只有几条是错误的真实排查场景。指标生成器 generate_metrics_data 以 5% 概率注入 CPU 60-95%、错误率 5-15% 的异常点用于验证 SmartCrusher 的统计异常检测能力。search_docs的返回会按relevance_score降序排序fetch_api_data带pagination.total_pages10用来考察保留首尾条目 相关性 Top-N策略。快速开始三个脚本的运行方式以下命令均在仓库根目录下执行依赖tiktoken以及完整对比所需的 LangChain# 1. 演示压缩效果无需 API Key PYTHONPATH. python -m examples.langchain_demo.show_compression # 2. 验证 ERROR 条目 100% 保留 PYTHONPATH. python -m examples.langchain_demo.verify_errors_kept # 3. 完整 Agent 对比需要 OPENAI_API_KEY export OPENAI_API_KEYyour-key-here PYTHONPATH. python -m examples.langchain_demo.run_comparisonshow_compression单工具 before/after 压缩演示show_compression.py 的核心流程在 demonstrate_compression() 中值得逐段看因为它展示了 Headroom 的transform 级用法不经过完整 pipeline直接调用 SmartCrusher第一步构造 SmartCrusher 并注入上下文。脚本用 SmartCrusherConfig 配置压缩器并通过OpenAIProvider().get_token_counter(gpt-4o)获取真实 tokenizertoken 计数接口定义见 providers/base.pyfrom headroom.config import SmartCrusherConfig from headroom.providers import OpenAIProvider from headroom.transforms import SmartCrusher smart_config SmartCrusherConfig( enabledTrue, min_tokens_to_crush200, # 只有超过 200 token 才压缩 max_items_after_crush20, # 压缩后最多保留 20 条 ) provider OpenAIProvider() tokenizer provider.get_token_counter(gpt-4o) crusher SmartCrusher(configsmart_config)第二步把工具输出放进标准 Agent 对话消息序列。脚本构造了 system → user带问题上下文→ assistant(tool_calls) → tool 四条消息模拟真实 Agent 中用户提问后工具返回大 JSON的形态messages [ {role: system, content: You are a helpful assistant.}, {role: user, content: context}, # 用户问题作为相关性上下文 {role: assistant, content: None, tool_calls: [{id: call_1, function: {name: tool_name, arguments: ...}}]}, {role: tool, content: raw_output, tool_call_id: call_1}, ] result crusher.apply(messages, tokenizertokenizer)关键点SmartCrusher 的apply()接收的是整条消息序列token 计数由调用方以tokenizer参数传入压缩后的结果从result.messages最后一条 tool 消息取出。第三步五个演示场景。main() 依次运行 5 个场景每个场景的用户上下文都刻意指向数据中存在的特征活跃工程用户、ERROR 日志、CPU 尖峰、认证文档、pending 订单让相关性打分有命中目标最后汇总输出各工具的前后 token 数与总成本。README 记录的实测结果README 的 Token Savings 表 给出了该演示的基准运行结果token 计数基于 cl100k_base工具压缩前压缩后节省search_users (100 items)15,4532,01487%search_logs (200 items)25,6793,21387%get_metrics (100 items)11,5178,42527%search_docs (50 items)6,9122,12769%fetch_api_data (75 items)15,7863,62277%合计75,34719,40174%注意get_metrics只有 27% 的节省率——因为时序指标每条记录字段少、数值密度高且异常点必须保留而日志/用户库这类长文本 大量无关行的结构压缩率最高。按 gpt-4o $2.50/1M 输入 token 计价单请求约 $0.19 → $0.05按每天 1000 次请求估算每月可节省约 $4,196。这些数字来自演示脚本自身的输出逻辑show_compression.py 的成本段实际节省取决于你的真实工具输出分布。SmartCrusher 的五大保留策略与配置参数SmartCrusherConfig 的 docstring 写明了设计目标保留原始 JSON Schema 不变——输出只包含原数组中的条目不包装、不生成文本、不加元数据。README 概括的五条压缩策略与其配置一一对应100% 保留 ERROR 条目——错误项永不丢弃源码中 Error items never dropped保留首/尾条目——first_fraction: 0.3/last_fraction: 0.15控制 Kneedle 自适应 K 值中首尾各占的比例默认 30%/15%其余名额给重要性打分用于分页上下文保留统计异常点——数值偏离均值超过variance_threshold默认 2.0 个标准差的条目保留捕获 CPU 尖峰、内存飙升等相关性打分——通过RelevanceScorerConfigrelevance字段让匹配用户查询的条目优先入坑变化点保留——preserve_change_points: True在数据发生显著跳变的位置留样。完整参数表默认值均来自 config.py参数默认值说明enabledTrue工具输出压缩的默认实现min_items_to_analyze5小于该条数的小数组不做统计分析min_tokens_to_crush200仅当输出超过该 token 数才压缩variance_threshold2.0变化点检测的标准差倍数调低如 1.5 更保守uniqueness_threshold0.1低于该值视为近常量字段similarity_threshold0.8相似字符串聚类阈值max_items_after_crush15压缩后目标最大条数演示中调为 20preserve_change_pointsTrue保留数据跳变点factor_out_constantsFalse不抽取常量保持原 schemainclude_summariesFalse不生成摘要文本dedup_identical_itemsTrue多种保留机制选中同一条目时只保留一份lossless_min_savings_ratio0.15无损表格化路径相对有损路径的最小字节节省比lossless_onlyFalse严格无损模式宁可放弃压缩也不产生 CCR 标记docstring 同时列出了已知边界GOTCHAS统计分析每条约 5-10ms 开销变化点检测用固定窗口5 条可能漏掉缓慢渐变Top-N 策略假设分数越高越相关。官方建议关键数据可调高max_items_after_crushvariance_threshold调低。实现入口是 headroom/transforms/smart_crusher.py 中的SmartCrusher类第 242 行它作为Transform接入 Headroom 的TransformPipeline。verify_errors_keptERROR 保留的自动化验证verify_errors_kept.py 是一个可直接执行的不变量检查流程为用generate_log_entries(test-service, count200)生成 200 条日志统计其中level ERROR的原始条数以相同配置min_tokens_to_crush200,max_items_after_crush20构造 SmartCrusher把日志作为 tool 消息压缩用户上下文设为 Find ERROR entries in the logs解析压缩后 JSON若 SmartCrusher 附加了标记文本脚本会用正则(\{.*\})兜底提取 JSON 主体见 第 59-73 行比对 ERROR 条数。判定逻辑在 第 84-91 行压缩后 ERROR 条数 ≥ 原始则输出SUCCESS: All ERROR entries were preserved部分保留输出PARTIAL一条不留输出FAILURE。README 记录的测试运行结果是 27/27 全部保留同时 200 条日志被压到约 20 条——即数量砍到 10%关键信息 100% 存活。这也是该演示最想传达的工程原则压缩的验收标准不是压缩率而是关键数据的不丢失。run_comparison完整 Agent 的 before/after 对比run_comparison.py 把对比拉到完整 Agent 层面同一个支持 Agent、同一组工具、同一批用户问题分别以 baseline裸模型和 headroom包装后模型各跑一遍。三个对比场景SCENARIOS 定义了三个贴近真实工单的问题User Account Investigation——某用户无法登录查账户状态 日志认证错误 相关文档Service Performance Investigation——payment-service 变慢查指标异常 近期错误日志 性能排障文档Multi-User Issue——工程部门多名用户报错搜工程用户 查 user-service 日志 查文档。两侧的运行方式Baseline 侧run_agent_baseline是标准 LangChain 工具循环ChatOpenAI(modelgpt-4o-mini, temperature0).bind_tools(tools)最多 5 轮迭代每轮累加输入 token本地计数、执行模型请求的工具调用、把结果作为ToolMessage追加回对话。Headroom 侧run_agent_headroom唯一区别是用HeadroomChatModel包装同一模型压缩在invoke()内部发生工具循环代码完全不变from headroom import HeadroomConfig from headroom.integrations import HeadroomChatModel base_model ChatOpenAI(modelgpt-4o-mini, api_keyapi_key, temperature0) config HeadroomConfig( smart_crusher_threshold500, # 工具输出 500 tokens 才压缩 smart_crusher_max_items20, # 最多保留 20 条 cache_alignmentTrue, # 稳定 system prompt 提升缓存命中 rolling_windowTrue, ) headroom_model HeadroomChatModel( wrapped_modelbase_model, headroom_configconfig, ).bind_tools(tools)跑完后脚本用headroom_model.get_total_tokens_saved()取 Headroom 自报的节省量从累计输入 token 中扣除得到实际发送给上游的 token 数。两点版本说明需要留意以当前仓库源码为准从 headroom/config.py 的 HeadroomConfig 结构看当前版本采用嵌套配置smart_crusher: SmartCrusherConfig字段承载压缩参数即min_tokens_to_crush/max_items_after_crush示例脚本中扁平的smart_crusher_threshold500, smart_crusher_max_items20写法属于演示脚本自身的历史 API在当前源码上运行前建议以HeadroomConfig(smart_crusherSmartCrusherConfig(...))的写法为准具体以 headroom/integrations/langchain/chat_model.py 对HeadroomConfig的消费方式为准。对比脚本调用的get_total_tokens_saved()方法在当前 chat_model.py 中对应的是total_tokens_saved属性与get_savings_summary()方法运行新版源码时注意按属性访问。输出与成本核算print_comparison() 为每个场景输出对照表输入/输出 token、工具调用次数、消息数、耗时以及按 gpt-4o-mini 价格$0.15/1M 输入、$0.60/1M 输出估算的美元成本与节省百分比。无 API Key 时脚本自动降级为 SIMULATION 模式只统计 3 个工具输出的 token 体量并给出约 5 倍压缩的估算max 20 items 上限下的粗略值。集成层原理为什么 Headroom 选择包装 ChatModelheadroom/integrations/langchain/chat_model.py 的模块 docstring 解释了架构动机LangChain 的 callback 机制按设计不能修改消息所以 Headroom 不挂 callback 改消息而是直接包装BaseChatModel本身——HeadroomChatModel第 118 行继承自BaseChatModel对外表现为一个普通 LangChain 模型。关键实现点懒加载 pipeline 与 provider 自动探测pipeline property 在首次调用时根据wrapped_model的类路径探测上游厂商ChatOpenAI → OpenAIProvider 等再构建TransformPipeline(config, provider)保证 token 计数与目标 provider 一致工具调用兼容bind_tools()被重写第 512 行返回包装后的HeadroomChatModel因此对比脚本里.bind_tools(tools)后依然能继续被 Headroom 拦截可观测性每次优化产生一条OptimizationMetricstokens_before/after、savings_percent、transforms_applied累积在metrics_history与total_tokens_savedget_savings_summary()提供汇总第 522 行多入口除HeadroomChatModel外integrations/langchain/init.py 还导出 Agent/Retriever/Streaming/LangGraph 等封装并有独立的optimize_messages()函数第 916 行供手工调用依赖方面pyproject.toml提供langchainextralangchain-core1.3.3、langchain-openai1.1.14见 pyproject.toml 第 212-214 行演示脚本则额外要求tiktoken。测试与回归验证LangChain 集成的回归测试集中在 tests/test_integrations/langchain/ 目录包含 test_chat_model.py、test_evals.py、test_agents.py、test_streaming.py、test_langgraph.py 等。README 提到的 12 项 eval 覆盖ERROR 保留100%、异常检测、相关性匹配、压缩效率、schema 保留与边缘用例。需要说明README 中给出的 eval 命令pytest tests/test_integrations/test_langchain_evals.py -v对应的文件在当前仓库中不存在实际为 tests/test_integrations/langchain/test_evals.py运行前请以目录内实际文件名为准PYTHONPATH. pytest tests/test_integrations/langchain/ -v适用前提与小结环境仓库根目录运行PYTHONPATH.show_compression/verify_errors_kept仅需tiktokenrun_comparison需要langchain-core、langchain-openai与OPENAI_API_KEY真实模式会产生 API 费用数据边界演示 token 数字基于 mock 数据与 cl100k_base 计数README 中的 74% 总节省率与成本折算是该仿真场景下的结果不代表所有工作负载get_metrics类高密度时序数据节省率明显低于长文本类输出核心结论这套演示展示了一条完整的落地路径——用 SmartCrusher 的统计保真压缩错误/首尾/异常点/相关性/变化点五重保留处理工具输出用 HeadroomChatModel 以包装 ChatModel方式零侵入接入 LangChain Agent最终在 token 大幅下降的同时维持关键信息 100% 可达。【免费下载链接】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），仅供参考