模型版本迭代后很多在单一请求里看起来“差不多”的改动放到真实 Agent 工程里会被放大成成本和延迟差异。最近看到有人讨论一个现象在 GPT-5.5 上Tools 列表里删掉一个工具prompt cache 直接失效但在 GPT-5.2 上同样的操作却能继续命中缓存。这个细节看起来很小实际影响却不小。对于一个每秒要处理几十个请求的 Agent 服务prompt cache 失效意味着每次请求都要重新计算整段 system prompt 和工具定义的注意力账单和响应时间都会明显变化。这篇文章想把这个现象讲清楚prompt cache 到底缓存了什么为什么工具列表改动会影响缓存命中不同模型版本在这个问题上为什么会有差异以及我们做工程的时候应该怎么规避这类坑。1. 为什么 prompt cache 对 Agent 工程这么关键先明确一个前提在 API 计费模型下输入 token 和输出 token 的成本结构不同而一个 Agent 请求的输入常常是几万甚至十几万 token。原因很简单——我们通常会把大量上下文塞进 system prompt角色设定、业务规则、工具定义、历史对话摘要、检索结果等等。在没有缓存的情况下每个新请求都要把这些 token 重新过一遍 Transformer 计算。这带来两个问题费用高单次请求可能消耗几千到几万输入 token高并发时累积起来非常可观。延迟高首 token 生成时间受输入长度影响输入越长prefill 耗时越长。Prompt cache 就是为了解决这个问题出现的。它的思路是如果多个请求在开头部分完全一致服务端可以把这段内容的 Key 和 Value 缓存下来新请求直接复用只计算变化的部分。这也是为什么它叫 “prompt cache” 而不是 “conversation cache”。它缓存的是模型内部计算出来的中间状态而不是你发的消息文本。你看起来只是改了几个字但如果这个改动发生在缓存前缀覆盖的范围内服务端就无法复用旧的 KV 状态。在 Agent 场景里工具定义往往占据很大一段前缀空间。一个复杂工具可能有几百甚至上千 token 的参数描述。Tools 列表一改等于这段公共前缀变了缓存自然就断了。所以对任何做 Agent 服务的团队来说prompt cache 不是“锦上添花”而是降低成本、降低延迟的基础设施级别的问题。2. Prompt Cache 的核心原理前缀匹配与自动失效要理解“为什么删一个 tool 会导致缓存失效”先要理解 prompt cache 的基本工作方式。从机制上说目前的 prompt cache 普遍采用前缀精确匹配逻辑。服务端把请求文本编码成 token 序列然后检查这个 token 序列的前缀是否与某个缓存条目一致。如果一致就直接复用这批 token 对应的 KV 缓存如果不一致就重新计算。这里有两个关键点容易误解2.1 缓存匹配的不是“语义”而是“文本”很多人以为 prompt cache 是智能的能理解“你只是删了一个工具其余内容没变”。不是这样的。缓存匹配基本是机械的token 序列前缀是否完全一致。也就是说只要删除一个工具后工具列表在文本层面发生了任何变化——哪怕只是删掉了最后一个工具——那从变化位置开始所有后续 token 在缓存里就找不到了。不过这里有一个细节值得注意如果删除的是列表末尾的工具且前面的工具定义完全不变那么理论上缓存仍然能覆盖前面的部分。真正让整段缓存失效的往往是实现上把整个 Tools 列表作为一个整体参与前缀匹配或者工具定义会按某种规则被重新排序、重新序列化。2.2 变化的“粒度”由服务端决定有些模型服务把 system prompt、tools、messages 分别处理有些则把它们拼成一个超长字符串统一计算。这种实现差异直接导致“删一个 tool 是否影响缓存”的结果不同。回到标题里的现象GPT-5.5 上删一个 tool 导致缓存失效而 GPT-5.2 不会。从机制上讲可能的原因就是两个版本在处理 Tools 列表时采用了不同的缓存键生成策略。3. 现象拆解5.5 失效而 5.2 不失效意味着什么我们先把标题描述的现象当作一个待分析的技术问题而不是一个已经定论的结论。实际上这是一个很典型的“不同版本模型行为差异”问题。它背后至少有三种可能的解释。3.1 版本间对 Tool 的序列化方式不同GPT-5.2 可能对工具定义做了更稳定的规范化处理比如按工具名称排序、对参数描述做固定格式整理。那么即使你删掉一个工具剩余工具的规范化输出仍然和之前一致缓存可以继续命中。GPT-5.5 可能改成了更接近原始文本的序列化方式。这样一来只要 Tools 列表在文本上发生变化序列化结果就变了缓存失效哪怕删掉的工具和剩余工具毫无关系。3.2 版本间缓存键的粒度不同另一个可能是缓存键的设计。如果 5.2 按照“system prompt 消息”来生成缓存键而 Tools 被单独缓存、单独匹配那么删除一个 tool 只影响该 tool 对应的缓存片段不影响其他部分复用。而 5.5 可能把 Tools 直接拼接进主 prompt 序列作为前缀的一部分。这样删一个 tool 会导致整个前缀长度变化从变化点开始全部重新计算。3.3 版本间的 Tokenization 可能存在差异还有一种可能两个版本虽然对外 API 一致但服务端使用的 tokenizer 或预处理流程不同。不同 tokenizer 对相同文本会切出不同的 token 序列即使文本完全一致token 序列不一致缓存也无法共享。从工程角度说我们不需要精确知道 OpenAI 内部用的是哪一种方案。我们需要的是一个能快速判断“当前模型版本 当前请求结构下缓存是否命中的方法”以及一套尽量让缓存多命中的请求组织方式。4. 如何复现与验证用 API 的 usage 字段判断缓存是否命中先说明一个原则要讨论缓存是否命中不能靠“感觉变快了”或“感觉账单变贵了”要看返回结果里的 usage 字段。在 OpenAI 兼容接口的返回结构中常见字段包括{ usage: { prompt_tokens: 12000, completion_tokens: 320, total_tokens: 12320, prompt_tokens_details: { cached_tokens: 0 } } }关键是prompt_tokens_details.cached_tokens。这个字段表示本次请求中有多少输入 token 命中了缓存。如果cached_tokens是 0说明缓存完全没命中所有输入 token 都重新计算了。 如果cached_tokens接近prompt_tokens说明缓存命中情况良好。要注意不同版本、不同接口可能用不同字段名实际调试时先打印一次完整的 usage确认字段结构。下面我给出一个最小验证脚本逻辑很简单构造一个固定的请求system prompt 两个工具。连续发送两次相同请求观察第二次是否命中缓存。修改 Tools 列表删除或新增一个工具再次发送请求观察缓存是否命中。用同一套代码分别在 5.5 和 5.2 环境上跑对比结果。5. 完整实验代码测试删除 Tool 后的缓存命中情况5.1 环境准备建议使用 Python 3.10 和 openai 官方 SDK。版本以实际安装为准本文重点演示通用思路。pip install openai然后设置环境变量export OPENAI_API_KEY你的Key export OPENAI_BASE_URL你的BaseURL如果你用中转或代理服务把OPENAI_BASE_URL换成对应地址。注意这里不涉及任何网络工具只是常规 API 配置。5.2 构造一个带 Tools 的请求函数import os import json from openai import OpenAI client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL, https://api.openai.com/v1), ) def build_messages(): return [ { role: system, content: 你是一个智能客服助手。请根据用户的问题调用合适的工具来查询信息。 }, { role: user, content: 查询订单 20240001 的物流状态并检查该订单是否享受了折扣。 } ] def build_tools(include_discount_toolTrue): tools [ { type: function, function: { name: query_order_status, description: 根据订单号查询物流状态, parameters: { type: object, properties: { order_id: { type: string, description: 订单号 } }, required: [order_id] } } } ] if include_discount_tool: tools.append( { type: function, function: { name: query_order_discount, description: 查询订单是否享受折扣, parameters: { type: object, properties: { order_id: { type: string, description: 订单号 } }, required: [order_id] } } } ) return tools def send_request(tools, modelgpt-5.5): response client.chat.completions.create( modelmodel, messagesbuild_messages(), toolstools, temperature0.7 ) return response这段代码里build_tools通过include_discount_tool控制是否保留第二个工具正好用来模拟“删除一个 tool”的场景。5.3 对比测试两次请求必须完全一致才能判断命中很多人在这一步会犯一个错误第一次请求和第二次请求的消息内容不同结果发现缓存没命中就以为“缓存失效了”。实际上请求结构不同缓存本来就不可能命中。正确的实验顺序是请求 A完整两个工具。请求 B和 A 完全一致再发一次。对比 A 和 B 的cached_tokens。请求 C只保留一个工具其他内容不变。对比 C 的cached_tokens。def print_usage(response, label): usage response.usage cached 0 if usage and hasattr(usage, prompt_tokens_details): cached usage.prompt_tokens_details.cached_tokens print(f[{label}] prompt_tokens{usage.prompt_tokens}, cached_tokens{cached}) print(f[{label}] total_tokens{usage.total_tokens}) return cached print( 测试 1完整 Tools第一次请求 ) r1 send_request(build_tools(include_discount_toolTrue)) print_usage(r1, A-第一次) print( 测试 2相同请求再发一次 ) r2 send_request(build_tools(include_discount_toolTrue)) print_usage(r2, B-完全相同) print( 测试 3删除一个 Tool 后请求 ) r3 send_request(build_tools(include_discount_toolFalse)) print_usage(r3, C-删除Tool)运行后你会看到类似这样的输出[测试 1] prompt_tokens1260, cached_tokens0 [测试 2] prompt_tokens1260, cached_tokens1180 [测试 3] prompt_tokens1100, cached_tokens0测试 1 的cached_tokens0是正常的因为这是第一次请求系统里没有可复用的缓存。 测试 2 的cached_tokens1180说明前缀命中了只有后半段是新增计算。 测试 3 的cached_tokens0说明删除一个 Tool 后缓存完全失效即使删掉的是末尾的工具。如果你换到 5.2 上跑同一个脚本测试 3 的结果可能不一样有可能cached_tokens仍然有值说明 5.2 对 Tool 变更更宽容。6. 运行结果分析与判断标准实验跑完后判断标准其实很简单如果相同请求第二次的cached_tokens明显高于第一次说明缓存机制正常工作。如果删除一个 Tool 后cached_tokens归零说明该模型的缓存前缀把 Tools 列表纳入了精确匹配范围。如果删除 Tool 后仍有较高的cached_tokens说明该模型对 Tools 列表做了独立缓存或规范化处理。这里要特别提醒一点cached_tokens不一定会等于prompt_tokens。因为系统提示、工具定义、消息内容可能被拆成多个段落只有最长公共前缀会被复用。所以看到cached_tokens小于prompt_tokens是正常的关键看它是否从非零变成零。另外不要只测一次。服务端缓存有一定的时效性和淘汰策略两次请求之间如果间隔过久缓存可能已经过期。建议在几秒内连续请求并在同一会话或同一 API Key 下测试。如果发现结果和标题描述不一致也不要惊讶。模型版本、服务端配置、区域部署情况都可能导致行为差异。重要的是掌握判断方法而不是迷信某一个版本的结论。7. 为什么会出现“删一个 Tool整个缓存失效”的情况从工程实现的角度看有三种常见设计会导致这个问题。7.1 整体拼接式前缀匹配这是最直接的原因。服务端把所有请求内容拼成一个长字符串包括 system prompt、tools、历史消息。Tools 列表的变更会让字符串长度或内容发生变化从变化点开始后面的所有 token 都无法与历史缓存匹配。这种设计简单直接但代价就是工具列表对缓存极其敏感。新增、删除、修改任何一个工具都会导致后续所有内容重新计算。7.2 工具名或参数描述参与缓存 Key有些服务会把“工具列表的结构化表示”作为缓存 Key 的一部分。这样即使消息部分完全一样只要工具列表变了缓存 Key 就变了。在这种设计下删除一个工具相当于换了一个缓存 Key旧缓存自然用不上。7.3 请求批处理中的重排序有些系统会在服务端对工具定义做重排序比如按名称排序、按使用频率排序。如果你在请求里自定义了顺序服务端可能在内部重新排列。这个重排过程如果依赖哈希或随机因子就可能导致看似同样的请求实际产生不同的缓存 Key。对开发者来说这些底层细节往往不可控。我们能做的是在请求构造层面尽量减少变化。8. 工具设计层面的缓存友好实践既然我们改变不了服务端实现那就从自身请求构造上想办法。这里给出几条经过验证的思路。8.1 工具定义尽量稳定不频繁变更工具列表不是不能改而是要控制修改频率。尤其是生产环境里工具定义最好走“版本发布”流程不要在日常调试中频繁增删。如果确实要改可以把工具变更集中在一个版本里发布避免多次小改动导致缓存反复失效。8.2 把易变部分放到工具之外有些信息虽然不是工具但和工具关联紧密比如工具的使用说明、示例、注意事项。这些内容如果放在 system prompt 里改起来会影响缓存前缀。更合理的做法是把真正会变的业务规则、动态信息放到 messages 里把稳定的工具定义放在 tools 里。这样即使业务规则每天变工具定义不变缓存仍然可以覆盖前一段。8.3 保持固定的工具顺序如果你的业务对工具顺序没有要求建议始终按固定顺序排列工具比如按名称拼音排序或按功能模块分组。这样即使某个工具暂时不用也不要直接从列表里删除可以把它的description改为“已停用”或把parameters设置为空对象保持列表结构不变。当然description改了也会导致缓存失效。最稳妥的做法是完全不修改工具定义只是在函数调用逻辑里拒绝执行。8.4 适当拆分多个 Tools 列表如果你的业务有多种场景每种场景需要不同工具不要把所有工具塞进一个列表里。可以考虑拆成多个请求路径每个路径使用固定的工具集合。这样做的好处是修改场景 A 的工具时只要不影响场景 B 的固定前缀场景 B 的缓存仍然能命中。8.5 用“工具版本号”做发布管理可以给工具集加一个版本号发布新版本时整体替换。这样对比缓存命中情况时可以清楚地知道“工具集版本变化导致缓存失效”是预期行为而不是意外问题。9. 常见问题与排查思路在调试 prompt cache 时经常会遇到一些看似诡异的问题。下面整理一份排查表。问题现象可能原因排查方法解决方案相同请求第二次仍未命中缓存System prompt 中有随机时间戳或 UUID打印完整请求体检查前缀是否一致移除动态内容或推迟到消息部分删除一个工具后缓存全失效工具列表被拼接到公共前缀中对比删除前后的 prompt_tokens 和 cached_tokens保持工具列表结构不变修改工具描述后缓存失效工具描述参与缓存 Key 或 token 序列逐字段修改观察缓存何时失效避免频繁修改 description两个请求看起来相同但 cached_tokens 不同Tokenizer 对某些字符处理不同或有隐藏字符对比请求的 token 级表示统一文本格式避免全角半角混用5.2 与 5.5 行为不一致版本间缓存机制或序列化方式不同用同一脚本分别测试按版本拆分请求策略缓存命中但系统报错提示上下文不一致工具列表变更导致历史消息中的 tool_call_id 失效检查 messages 中 tool_call_id 是否对应已删除工具清理历史 tool 消息或重建会话这里特别提醒一点如果出现an assistant message with tool_calls must be followed by tool messages这类错误通常不是因为缓存而是因为你在 assistant 消息里声明了 tool_calls但后续没有提供对应的 tool 消息。这和缓存是两个独立问题不要混在一起排查。10. 最佳实践与工程建议综合前面的分析我给出几条可以直接落到工程里的建议。10.1 建立缓存命中率监控在生产环境里把每次返回的prompt_tokens_details.cached_tokens记录下来按分钟或小时聚合。缓存命中率低于某个阈值时报警。这样工具列表一旦发生变更你能第一时间看到成本变化。一个简单的指标公式缓存命中率 sum(cached_tokens) / sum(prompt_tokens)建议忽略第一次请求因为第一次请求天然无法命中缓存。可以按会话或 Key 维度统计“非首次请求的缓存命中率”。10.2 为工具变更准备成本评估每次修改工具定义时先估算影响范围。如果工具列表在请求前缀中占比很高一次变更可能带来几千甚至上万 token 的额外计算量。在高峰期发布工具变更意味着这段时间内所有新请求都会经历一次缓存重建。可以考虑在低峰期发布工具变更或者在发布后观察一段时间命中率曲线。10.3 区分“工具变更”与“参数变更”工具的name、description、parameters三个字段对缓存的影响可能不同。name通常影响最大因为它是工具的唯一标识description影响次之parameters里的字段描述也会影响。在实际操作中尽量保持name不变只改description或parameters这样缓存失效的范围可能更小。但这一点取决于服务端实现需要在你的环境中验证。10.4 长文本请求分块或精简工具定义不是越长越好。复杂的 JSON Schema 会占用大量 token不只是成本问题还会让缓存更容易失效。建议在保证功能完整的前提下精简工具描述比如去掉冗余的示例、合并相似的参数。每个工具节省几十到几百 token几十个工具累积起来效果明显。10.5 多版本模型并存时要分别验证从本文的对比可以看出不同模型版本对缓存的处理策略确实可能不同。你在 5.2 上验证通过的优化方案不代表在 5.5 上同样有效。所以升级模型版本时要专门跑一遍“缓存命中对比测试”而不是只看功能是否正常。这应该作为模型升级验收的标准流程之一。11. 小结回到最开始的问题为什么 GPT-5.5 上删一个 tool 会 invalidate prompt cache而 5.2 不会从技术原理上推断最可能的原因是两个版本对 Tools 列表的缓存键生成策略不同。5.2 可能对工具定义做了独立缓存或规范化处理5.5 则把工具列表更直接地绑定到主 prompt 前缀中。这个差异与模型本身的推理能力关系不大更多是服务端缓存实现层面的选择。对实际工程来说这个现象告诉我们几件事工具列表是 Agent 请求里的“高危缓存破坏点”变更前要评估成本。不要只看模型版本号就假设行为一致要用 usage 字段做实际验证。工具定义的稳定性应该像接口契约一样被管理而不是随手改、随手发。如果你正在做 Agent 类应用建议把本文的测试脚本整理成一套自动化用例每次升级模型或修改工具定义时跑一遍。这样你对自己的缓存命中情况会有更确定的掌握而不是等月底账单出来才发现成本异常。后续可以继续深入了解的方向包括不同模型服务商的缓存生效条件、带视觉输入时的缓存行为、多模态请求下的前缀匹配差异以及如何通过代理层统一管理 prompt 和工具的版本。这些内容对做大流量 Agent 服务的团队都很有价值。