LLM Token 优化实战从 Headroom 看懂上下文压缩为什么是 Agent 成本核心TL;DR场景模型单价持续下降但 AI Coding Agent、RAG、日志分析、多工具工作流把单次任务的输入 tokens 成倍放大,真正决定 LLM 应用成本的是「系统为了回答一句话,把多少冗余上下文反复发给模型」。2026 年开源的 Headroom 把自己定位为 LLM 应用的 context optimization layer,代表工程焦点从 prompt engineering 进入 context engineering。结论Token 优化不是prompt 写短一点,而是一套系统工程,至少包括 Prompt 精简、上下文裁剪、检索前过滤、工具输出压缩、Prompt caching、输出长度控制和模型路由七件事。Headroom 提出的 CacheAligner(稳定缓存前缀)、ContentRouter(按内容类型分路由)和可逆压缩(摘要 本地 cache retrieve handle)是当前最具落地价值的三条工程思路。产出拆解 token 成本公式的四类拆项(input / output / cache_write / cache_read),给出适合压缩的四类场景(AI Coding、RAG、日志分析、DB/API 响应)和不能盲目压缩的五类强约束场景(合规、数学推理、当前修改代码、用户原始意图、短请求),并提供从 token 观测到灰度上线的 7 步工程落地路线与 1 张错误速查卡。版本矩阵功能 / 概念状态说明Headroom 项目定位为 LLM Context Optimization Layer✅ 已验证GitHub 仓库chopratejas/headroomREADME 明确:压缩 tool outputs / logs / RAG chunks / files / conversation history,在内容到达 LLM 之前Headroom Token 压缩比例 60-95%✅ 已验证README 标题「60-95% fewer tokens · library · proxy · MCP · 6 algorithms」Headroom 四种使用模式(Library / Proxy / MCP / Agent wrap)✅ 已验证README 列:compress(messages)库模式、headroom proxy --port 8787代理模式、headroom wrap claudeHeadroom MCP 工具集(headroom_compress/headroom_retrieve/headroom_stats)✅ 已验证README 明示为任意 MCP client 提供三个工具Headroom 内置 6 种压缩算法✅ 已验证README「6 algorithms」Headroom 支持可逆压缩(local-first / reversible)✅ 已验证README「local-first · reversible」与headroom_retrieve工具Headroomheadroom learn自动沉淀失败会话经验✅ 已验证README「mines failed sessions, writes corrections to CLAUDE.md / AG…」Headroom 跨 Agent 共享记忆(Claude / Codex / Gemini,自动去重)✅ 已验证README「Cross-agent memory — shared store across Claude, Codex, Gemini, auto-dedup」Headroom 实测 10,144 → 1,260 tokens 命中同一条 FATAL✅ 已验证README 案例数据Headroom 主仓库语言占比 Python 76.8% / Rust 18.4% / TypeScript 2.7%✅ 已验证博客园「今日开源第5期」统计镜像/二创仓库gglucass/headroom✅ 已验证GitHub 存在,活跃更新 2026-06-07官方文档站headroom-docs.vercel.app✅ 已验证博客园文章引用CacheAligner(系统/工具定义放稳定前缀以命中 provider cache)⚠️ 待验证文章中以Headroom 关键思路提出,Headroom 官方 README 未直接出现该命名,概念对应其「稳定前缀」设计,具体模块名需查官方 docsContentRouter(按内容类型分发到不同压缩器)⚠️ 待验证文章中以Headroom 关键思路提出,README 未直接出现该命名,概念对应其「6 algorithms」分类型压缩,具体模块名需查官方 docs主流 Provider 缓存写入价格高于缓存读取✅ 已验证Anthropic / OpenAI / Google 等主流 Provider 计费规则:cache write 计入更高费率,cache read 显著折扣长上下文不等于不需要压缩(成本、延迟、注意力稳定性)✅ 已验证多篇论文与厂商工程博客(LongBench、Lost in the Middle、NIAH)均印证cache_read价格低于cache_write与普通 input✅ 已验证Anthropic Prompt Caching 公开定价:cache read ≈ 1/10 input price文章正文摘要模型单价下降并不代表 LLM 应用真实成本一定下降。Agent、RAG、AI Coding、日志分析和多工具工作流正在把输入 tokens 成倍放大。Headroom 这类 context optimization layer 的出现说明 LLM 工程已经从 prompt engineering 进入 context engineering。本文从 token 成本公式、Headroom 架构、CacheAligner、ContentRouter、可逆压缩、适用场景和落地路线展开解释 token 压缩为什么会成为生产级 Agent 的基础设施。为什么现在又开始讨论 token 压缩很多人对 LLM 成本的判断还停留在一句话模型越来越便宜所以 token 不用太在意。这个判断只对了一半。单个 token 的价格确实在下降但 Agent 的使用方式正在把 token 消耗成倍放大。普通聊天里一次请求可能只有几千 tokens到了 AI Coding、Deep Research、RAG、日志分析、多工具 Agent 场景一次任务可能包含几十次工具调用。每次工具调用又会把文件内容、搜索结果、终端输出、JSON 响应、报错堆栈和历史对话塞回上下文。真正的成本不再来自用户问了一句话而是来自系统为了回答这一句话把多少机器生成的冗余上下文反复发给模型。Headroom 官方将自己定义为 LLM 应用的 context optimization layer重点处理 tool outputs、DB results、file reads、RAG results 等进入模型前的内容。这个定位很关键它不是模型压缩不是量化不是蒸馏而是解决发给模型之前的上下文太臃肿。一句话概括LLM Token 优化 让模型只阅读高密度上下文而不是所有原始材料Agent 为什么会把 token 成本打爆一个 AI Coding Agent 为了修一个 bug可能要读目录、搜文件、打开源码、跑测试、看日志、分析报错、追调用链、改代码再把新日志交给模型判断。每一步都会产生上下文而且这些上下文不是一次性消费而是在多轮任务里不断累积。第 1 轮可能只有 5K tokens第 3 轮到 30K第 8 轮就可能接近 100K。越往后每次请求携带的历史越长成本越容易滚起来。RAG 也类似。很多系统为了召回更全把 top-k 设置得很大把 chunk 原样塞进 prompt。看似上下文更完整实际上经常把低相关片段、重复内容、HTML 残留、JSON 元数据一起送给模型。日志分析更典型。一个 SRE Agent 读取 5 万行日志大部分都是正常请求、重复 warning、时间戳、线程名、traceId 和固定字段。真正关键的信息可能只有几个 error、exception、timeout 或状态突变。所以第一条原则是不要把 LLM 当压缩软件、grep、数据库、搜索引擎和日志聚合器使用。LLM 应该消费整理后的高密度信息而不是所有原始材料。token 成本公式别只看 input tokensLLM API 成本通常可以拆成四类总成本 输入 token 成本 输出 token 成本 缓存写入成本 缓存读取成本进一步看Cost input_tokens * input_price output_tokens * output_price cache_write_tokens * cache_write_price cache_read_tokens * cache_read_price这里有四个工程要点。第一输出 tokens 往往比输入 tokens 更贵所以不能只盯输入也要限制输出长度避免模型反复生成大段解释。第二Agent 场景的输入 tokens 往往远大于输出 tokens。模型可能只输出几百到几千 tokens但输入可能达到几十万 tokens。第三prompt cache 能降低重复前缀成本但前提是上下文结构稳定。如果每次都把当前时间、随机 sessionId、临时路径和工具输出塞在前缀就会破坏缓存命中。第四压缩和缓存不是替代关系。压缩解决少发无用内容缓存解决重复内容不要重复算。Headroom 解决的是上下文入口问题从架构上看Headroom 位于应用或 Agent 和 LLM Provider 中间可以用 SDK、Proxy、MCP、wrapper 等方式接入。它更像一层 LLM 应用里的 context middleware。过去 Web 系统有 API Gateway、鉴权中间件、缓存中间件、日志中间件。现在 LLM 应用也需要上下文中间件负责压缩工具输出、稳定缓存前缀、识别内容类型、控制上下文预算、保留原始内容以便回溯并统计 token、成本和质量指标。Headroom 的价值不在于某个宣传数字适合所有场景而在于它指出了一个方向在 Provider 之前先做 context optimization。Token 优化不是一种技术而是一套系统工程把 prompt 写短一点只是最浅的一层。真正的 token 优化至少包括七件事。第一Prompt 精简。删除无意义的礼貌语、重复约束、历史遗留说明和过度角色扮演保留任务目标、输出格式、边界条件、工具调用规则和失败处理规则。第二上下文裁剪。多轮任务里保留最近任务、关键决策、用户偏好和当前状态丢弃已经完成的中间探索。不要只用粗暴 rolling window否则可能误删不要改数据库结构必须兼容 Java 8这类早期约束。第三检索前过滤。RAG 不应该召回很多再让 LLM 自己判断。更合理的链路是 query rewrite、多路召回、去重、rerank、chunk 合并、query-aware compression最后只发送高相关片段。第四工具输出压缩。shell 输出、JSON 响应、数据库查询结果、搜索结果、测试日志、文件列表和 API 返回值通常有强结构适合保留 schema、异常项、统计分布、首尾样本、文件路径、行号和命中片段而不是原样塞给模型。第五Prompt caching。system prompt、工具定义、输出格式、长期项目背景、API schema 和用户长期偏好适合放在稳定前缀当前时间、随机 ID、临时路径、当前请求参数和每轮变化的工具输出应该放后面。第六输出长度控制。比如只输出 JSON“只输出 diff”“只输出 5 条以内结论”“错误时只返回 error_code 和 reason”。输出控制不是为了短而是为了符合消费端需要。第七模型路由。不是所有上下文都需要昂贵模型处理。可以先用规则或便宜模型做过滤、分类、去重、摘要、字段提取再把高价值信息交给强模型。原始输入 - 规则过滤 - 小模型压缩 / rerank - 强模型推理 - 结构化输出这相当于把强模型从清洁工变成决策者。Headroom 的几个关键思路CacheAligner让 provider cache 真正命中很多系统明明有大量重复 prompt却命不中缓存是因为前缀里混进了动态内容。例如把当前日期、sessionId 放在工具定义前面就会导致后面的稳定内容也无法复用。更合理的结构是系统规则、工具定义、输出格式放在稳定前缀当前时间、临时状态、工具输出放在后缀。这个优化看似简单但 Agent 场景价值很高因为工具定义和系统规则往往很长而且每一轮都会重复发送。ContentRouter不同内容走不同压缩器压缩不能一刀切。JSON、日志、代码、HTML、普通文本、搜索结果的压缩方式不同。JSON arrays - 结构化摘要 异常项 样本 Build logs - 错误堆栈 前后窗口 exit code Search results - 文件路径 行号 命中片段 Source code - 保守保护当前代码上下文 Plain text - 摘要但保护否定词、数值和条件错误压缩比不压缩更危险。把代码当普通文本压缩可能删掉函数体把日志当文章摘要可能丢掉唯一关键异常把 JSON 随机截断可能破坏结构。可逆压缩压缩但不丢证据普通压缩最大的问题是删掉的内容没了。压缩器不知道哪些信息后面会重要一旦误删模型也未必知道自己缺信息。更可靠的思路是可逆压缩prompt 中只放摘要、异常和代表样本原始内容存入本地 cache并提供 retrieval handle。模型需要时可以调用工具取回原文而不是在压缩摘要上硬猜。原始 JSON 1000 条 - prompt 中放摘要 异常 代表样本 - 原始 1000 条存本地 cache - 模型需要时调用 retrieve(id)长上下文不等于不需要压缩现在很多模型支持 200K、1M 上下文但长上下文解决的是放得下不是用得好更不是用得便宜。长上下文仍然有成本高、延迟高、注意力不稳定三个问题。更工程化的做法是把上下文分成三层第一层必须原样进入 prompt 的核心信息 第二层压缩后进入 prompt 的辅助信息 第三层不进入 prompt但可通过工具按需检索的原始信息用长上下文兜底用压缩提高密度用检索保证召回用缓存降低重复成本。最适合压缩的场景AI Coding Agent 最典型。目录结构、搜索命中、大文件、构建日志、测试日志、package lock、依赖树、Git diff 和历史对话都容易产生大量冗余。优化策略是目录只保留相关路径搜索结果保留文件名、行号和命中片段构建日志保留失败命令、错误堆栈和最后统计当前分析代码默认不压缩。RAG 问答系统的重点是减少低相关 chunk 和重复内容。不要把压缩当成召回质量差的补救应该先解决召回和排序再做 query-aware compression。日志分析 / SRE Agent 天然适合压缩因为日志重复度高、结构固定、异常稀疏。应该保留 error、exception、failed、异常前后窗口、状态变化、慢请求、超时、重试、traceId、requestId、host、pod并聚合重复日志。数据库查询结果 / API 响应也适合压缩。如果返回 1000 行模型未必需要逐行阅读可以压缩为字段说明、总数、分组统计、异常值、top/bottom、首尾样本和与问题匹配的记录。哪些场景不能盲目压缩法律、医疗、金融等强合规场景不能随意摘要后让模型判断必须保留证据链、原文片段和来源位置。数学推理、算法证明、形式化验证不能压缩题干、公式、约束和已知条件。当前正在修改的代码不应该压缩。代码修复需要精确上下文尤其是函数体、条件判断、注解、泛型、事务边界和异常处理。用户原始意图最好不要压缩。用户表达里的限制、偏好、否定、语气和优先级都可能影响最终结果。短请求也没必要压缩。300 tokens 以内的普通对话引入复杂压缩层可能反而增加延迟。好的 token optimizer 不是尽量压缩一切而是知道什么时候压缩、怎么压缩、压缩后怎么回退以及什么时候坚决不压缩。工程落地路线从观测开始如果要给自己的 LLM 应用做 token 优化不建议一上来就接入复杂压缩器。更稳妥的路线是先做 token 观测记录 input_tokens、output_tokens、cached_input_tokens、tool_output_tokens、rag_context_tokens、history_tokens、system_prompt_tokens、latency、TTFT、cost_estimate、compression_ratio 和 answer_quality_score。拆分上下文来源不要只看总 input tokens要拆成 system prompt、tool definitions、conversation history、RAG chunks、tool outputs、user input。给不同内容设置 token budget。超出预算时先去重再裁剪低相关内容再结构化压缩最后才摘要。工具输出先结构化再压缩。不要把原始 stdout 直接塞给模型可以返回 summary、important_lines 和 full_log_ref。缓存稳定前缀。系统提示词、工具定义、项目规范和输出格式放前面当前用户问题、当前工具输出、临时信息放后面。建立质量评测。不要只看 compression ratio还要看准确率、工具调用成功率、RAG 忠实度、引用正确性、JSON 有效性、延迟、成本和回退检索率。灰度上线。压缩层应该支持 off、audit、optimize 三种模式。先 audit只统计不改变请求确认低风险后再 optimize。压缩失败必须 fail open返回原文。结语token 压缩不是抠成本LLM Token 优化会变成 Agent 工程里的基础设施。早期 LLM 应用只要会写 prompt 就能跑起来下一阶段真正的差距会出现在上下文管理上。谁能把有限 tokens 变成高密度信息谁就能获得更低成本、更低延迟和更稳定的答案。Headroom 的被关注不是偶然。它击中的不是小技巧而是 Agent 时代的结构性问题工具越来越多上下文越来越长模型越来越强但发送给模型的信息也越来越脏。不要让模型阅读垃圾。不要为重复上下文付费。不要把长上下文当成无限垃圾桶。真正应该进入模型的是经过筛选、压缩、排序、缓存和可回溯管理的高价值上下文。错误速查卡症状根因定位修复prompt cache 命中率长期为 0成本居高不下稳定前缀中混入了 sessionId / 当前时间 / 临时路径 / 每轮工具输出抓取连续 N 次请求比对 prefix 前 1024 tokens 是否一致引入 CacheAligner:system prompt 工具定义 输出格式放前缀动态内容放后缀用Cache-Control: ephemeral显式控制单次输入 tokens 暴涨但答案质量未提升工具原始输出(shell / JSON / 日志)直接塞进 prompt统计tool_output_tokens与answer_quality_score相关性工具输出结构化:返回summaryimportant_linesfull_log_ref引入 ContentRouter 分类型压缩AI Coding 任务第 8 轮后单次成本翻倍多轮上下文不断累积未做上下文裁剪看 history_tokens 趋势 任务完成度引入任务级 context budget裁剪已完成步骤保留关键决策、用户偏好、当前状态压缩后模型开始答非所问或编造一刀切摘要丢失关键异常 / 数值 / 否定词比对压缩前后 answer_quality_score 引用正确性改用可逆压缩(摘要 本地 cache retrieve handle)压缩失败必须 fail open 返回原文压缩 JSON 后模型报语法错误 / 字段缺失随机截断破坏 JSON 结构看压缩输出是否能 JSON.parseContentRouter 对 JSON 走结构化摘要 异常项 样本不做截断式压缩日志压缩后丢失唯一 FATAL / exception把日志当纯文本摘要grep 关键错误关键字是否在压缩结果中日志走专用压缩:保留 error/exception/failed 前后窗口 exit code 聚合重复行长上下文模型依然贵、慢、注意力飘移误以为上下文长就不用压缩测 TTFT、cost_per_task、长上下文 needle-in-haystack 准确率引入三层上下文:核心原样 / 辅助压缩 / 检索按需当前正在修改的代码被压缩后修复失败代码压缩丢失函数体 / 条件 / 注解 / 事务边界看 diff 是否引用了被压缩片段把当前编辑的代码文件加入禁压列表只压周边文件合规/医疗/金融场景压缩掉证据链一律摘要导致原文丢失审计 prompt 是否含原文引用与来源位置强合规场景走白名单:只压缩可公开字段原文必须可检索RAG 召回质量差寄希望于压缩补救召回和排序未做就压缩看 recallK、context relevance先 query rewrite 去重 rerank chunk 合并再做 query-aware compression引入压缩层后延迟反而上升300 tokens 以内的短请求也走压缩管线看短请求 P50/P99 latency短请求( 1K tokens)直接跳过压缩长请求再启用prompt 中加入压缩层后输出变得更啰嗦未对输出设长度控制看 output_tokens 分布加输出约束:“只输出 JSON”、“最多 5 条结论”、“错误时只返回 error_code 和 reason”模型路由后小模型浪费 token、大模型响应慢所有请求都走强模型 / 所有请求都走弱模型看 task_type → model 分布 cost_per_task按任务分级:过滤/分类/去重走小模型或规则决策/推理走强模型headroom wrap包装后工具调用报错包装器与原 agent CLI 参数不兼容看 wrap 启动日志 工具调用轨迹升级到最新 wrap 模式或在 SDK 模式做最小集成压缩层故障导致整个 Agent 宕机压缩层 fail closed,异常直接抛出看异常日志 链路追踪压缩层必须 fail open:异常时直接返回原文不阻断业务audit 模式看到大量 compress_ratio 接近 1压缩器对高密度内容强行压浪费 CPU 且无收益看 content_type × compression_ratio 分布对压缩收益 5% 的内容直接跳过记录白名单第三方压缩器偷偷把数据外传压缩器无本地化保证看压缩器是否调用外网 / 是否经过审计优先 local-first 方案如 Headroom 的 local-first · reversible外网压缩走严格白名单headroom learn写入的 CLAUDE.md 覆盖了项目原有规则learn 未做变更范围控制diff CLAUDE.md 改动点给 learn 设置写入白名单与 PR review敏感目录加入 exclude参考来源Headroom GitHub 仓库https://github.com/chopratejas/headroomHeadroom 官方文档https://headroom-docs.vercel.app/docs镜像仓库https://github.com/gglucass/headroomHeadroom 实战解读https://blog.csdn.net/forcedRegCsdn/article/details/161802799今日开源第 5 期 Headroomhttps://www.cnblogs.com/zhang-yd/p/20297158作者武子康的个人博客
