最近在调试 GPT 模型接口时遇到一个比较有意思的现象同样的对话上下文只是删掉了 tools 里的一个函数定义在某个模型版本上 prompt cache 全量失效请求延迟直接拉高换到另一个版本缓存命中却基本不受影响。这个差异非常影响线上接口的响应速度和成本尤其是在高频调用场景下。本文基于这一现象展开完整梳理 prompt cache 的命中机制、工具定义变化对缓存的影响以及如何在不同模型版本上做优化。适合的人群正在接入 GPT 对话接口、使用 function calling 做 Agent 应用的开发者或者对 prompt 成本优化、接口性能调优感兴趣的同学。阅读完本文你会理解 prompt cache 的判定逻辑学会排查缓存失效问题并掌握一套稳定命中缓存的工具编排方法。1. 什么是 Prompt Cache先把基础概念理清1.1 Prompt Cache 解决的是什么问题大模型接口的每次请求都需要把完整的输入上下文系统提示词、历史消息、工具定义等发送给模型。请求越复杂输入 token 越多计算量和费用也就越高。但在很多业务场景中上下文的大部分内容是重复的系统提示词可能每周才改一次历史会话在连续多轮请求里不断拼接tools 定义往往整套系统里固定不变。Prompt cache提示缓存的思路很简单对重复出现的共同前缀直接缓存计算结果下次请求如果前缀完全一致就不需要重新计算前面对应层的 KVKey-Value状态从而降低首 token 延迟TTFTTime to First Token和费用。从用户视角看这个机制是透明的你不需要额外传什么参数。只要你的输入满足缓存条件API 后台就会自动命中缓存并在响应中返回缓存命中状态。1.2 为什么 Prompt Cache 对 Agent 应用特别重要在 Agent 应用中请求往往有很长的系统提示词和大量工具定义。比如一个客服机器人系统提示词可能包含业务规则、话术风格、敏感词处理策略等整体 2000 tokentools 定义可能有十几个函数包括查订单、查物流、处理退款等整体可能达到 3000~5000 token再加上每轮对话都要携带的历史消息单次请求轻易达到 8000~15000 token。在这样的场景下如果缓存能够稳定命中重复输入的 3000~5000 token 不再重复计费首 token 延迟也会明显下降。反之如果缓存经常失效每次都要全量重新计算成本和延迟都会明显上升。理解缓存命中规则本质上就是在理解“如何花更少的钱获得更快的响应”。1.3 容易混淆的概念Prompt Cache 与上下文缓存不同平台对缓存的称呼不太一样。OpenAI 的官方文档中这个能力早期叫 prompt caching后来统一叫 Automatic Prompt Caching自动提示缓存强调“自动”二字开发者不需要额外配置系统自动判断。Google Gemini 和 Anthropic Claude 也都有类似机制Anthropic 称为 prompt caching但它的实现方式更偏向“显式缓存”需要指定缓存控制点。这些机制本质上都是复用输入前缀的中间计算结果但细节差异很大。本文重点讨论 OpenAI 系列模型的自动提示缓存行为。2. 环境准备与版本说明2.1 模型版本差异为什么本文会对比 5.5 与 5.2你看到的模型版本号最好是基于你实际项目使用的版本来验证。本文之所以会讨论 GPT-5.5 和 GPT-5.2 两个版本的行为差异是因为不同版本的缓存实现策略并不完全相同理解这些差异有助于你在升级模型时合理评估性能与成本变化。需要说明的是模型版本迭代非常快不同厂商、不同版本的缓存规则可能会有调整。本文描述的机制与排查思路具有通用性但具体响应字段和缓存长度要求请以你使用的 API 文档和实际测试为准。2.2 准备环境与测试工具本文示例使用 Python 和 OpenAI 官方 SDK需要准备以下环境Python 3.9 以上版本。安装 openai 库pip install openai。一个可访问 API 的密钥并设置环境变量OPENAI_API_KEY。建议在测试环境中使用较小的上下文方便观察缓存命中与否的差异。以下是一个最小化的测试代码骨架先把客户端准备好# 文件路径test_prompt_cache.py import os import time from openai import OpenAI client OpenAI( api_keyos.environ.get(OPENAI_API_KEY), ) def chat_with_tools(model: str, messages: list, tools: list): start time.time() response client.chat.completions.create( modelmodel, messagesmessages, toolstools, tool_choiceauto, ) cost_time time.time() - start return response, cost_time后面我们会用这个骨架来对比“相同消息但不同工具列表”时的缓存命中情况。3. Prompt Cache 的命中机制拆解3.1 前缀精确匹配原则自动提示缓存并不是对整段上下文做模糊匹配而是采用前缀匹配prefix matching。也就是说请求的输入 token 序列必须在某个起始位置与之前请求的 token 序列完全一致。举个例子第一次请求的 token 序列为[系统提示词, 工具定义A, 工具定义B, 历史消息1, 用户问题1]第二次请求的 token 序列为[系统提示词, 工具定义A, 工具定义B, 历史消息1, 历史消息2, 用户问题2]第二次请求的前缀包含了第一次请求的前半部分因此从历史消息1之前的内容是可以命中缓存的。这也是多轮对话能持续命中缓存的原因每次追加新消息前面的消息都保持不变。3.2 Tool 定义在 Prompt 中的位置在 Chat Completions 接口中tools 参数会被序列化后拼接到系统消息之后、用户消息之前。不同模型对 tools 的处理方式有细微差异但整体结构基本一致[系统提示词] [tools 序列化结果] [历史消息] [当前用户消息]因此tools 的任何变化都会导致后续所有 token 序列发生变化。问题是模型会不会把 tools 作为“可跳过重新计算”的部分这就回到了不同版本的实现差异上。3.3 缓存命中的几个必要条件综合多个版本的行为自动提示缓存通常要求满足以下条件输入前缀的 token 序列完全一致。前缀长度超过系统设定的最小值例如早期 OpenAI 要求前缀至少 1024 个 token后来部分版本下调。请求参数中与缓存相关的设置一致例如 model、temperature、top_p 等采样参数一般不影响前缀计算但工具定义顺序变化会影响 token 序列。没有开启影响输入序列的随机化机制。这里最关键的一点是只要 tools 序列化后的 token 发生了变化前缀匹配就会被打破。而“变化”不只是增删函数连函数定义的顺序调整、描述文本改动、参数结构重排都会改变 token 序列。4. 核心问题分析删除一个 Tool 为什么缓存会失效4.1 问题复现从现象到根因回到本文标题的场景在一个请求中传入 tools 列表包含 A、B、C 三个工具下一次请求中只传入 A、B 两个工具。结果是在 GPT-5.5 上第二次请求的缓存完全失效在 GPT-5.2 上缓存仍然命中。要理解这个现象必须区分两个层面如果缓存前缀严格包含 tools 序列化内容那么删掉 C 之后再请求前缀必然不完整缓存应该失效。但某些模型版本可能会对 tools 部分做特殊缓存处理类似“工具注册表”的机制把工具定义内容独立缓存与对话历史分开计算。目前很多人猜测模型版本差异的根源可能在于 tools 被序列化进入请求的方式不同。5.2 版本可能采用了一种“工具定义与对话上下文分离缓存”的策略只要工具定义集合没有变化对话历史部分仍然可以命中而 5.5 版本则把工具定义与对话上下文做了更严格的耦合任何一个工具定义的变化都会导致整个输入前缀重新计算。4.2 复现实验相同消息不同工具列表下面我们用代码来做一次对比。首先定义相同的系统提示词和消息序列然后分别用“完整工具列表”和“删除一个工具后的列表”发起请求。# 文件路径test_prompt_cache.py续 SYSTEM_PROMPT 你是一个智能客服助手请根据用户的提问选择合适的工具回答问题。 TOOLS_FULL [ { type: function, function: { name: query_order, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string, description: 订单编号} }, required: [order_id] } } }, { type: function, function: { name: query_logistics, description: 查询物流信息, parameters: { type: object, properties: { order_id: {type: string, description: 订单编号} }, required: [order_id] } } }, { type: function, function: { name: apply_refund, description: 申请退款, parameters: { type: object, properties: { order_id: {type: string, description: 订单编号} }, required: [order_id] } } } ] TOOLS_WITHOUT_REFUND TOOLS_FULL[:-1] MESSAGES [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: 帮我查一下订单 2024001 的状态} ] # 第一次请求完整工具列表 response1, cost1 chat_with_tools(gpt-5.2, MESSAGES, TOOLS_FULL) print(第一次请求耗时, cost1) print(第一次缓存标记, response1.usage.prompt_tokens_details) # 第二次请求删除一个工具 response2, cost2 chat_with_tools(gpt-5.2, MESSAGES, TOOLS_WITHOUT_REFUND) print(第二次请求耗时, cost2) print(第二次缓存标记, response2.usage.prompt_tokens_details)在上面的示例中我们通过response.usage.prompt_tokens_details来查看缓存命中数据。如果返回的cached_tokens字段比较大说明缓存命中成功如果为 0则说明缓存未命中。4.3 为什么 5.5 上全量失效在 5.5 版本上缓存失效的本质是输入 token 序列变化。系统提示词之后紧跟的就是 tools 序列化内容一旦apply_refund被删除tools 序列化后的 token 序列就少了一块后面所有内容都需要重新对齐因此整段缓存都失效。这就像一个文本文件的中间被删掉一段后面所有字符的字节位置都变了即使内容一模一样也无法直接复用之前的索引。类似的判断也适用于其他场景比如工具定义里只是多了一个空格、调整了参数的顺序、修改了 description 中的某个字都会导致整体 token 序列变化。4.4 为什么 5.2 上仍然命中5.2 之所以表现不同很可能是因为该版本对 tools 部分的处理方式不同。一种常见实现是请求在系统内部被拆成两段——工具段和对话段二者使用不同的缓存策略。工具段按“工具集合名称/版本”进行匹配对话段按纯文本前缀进行匹配。这样一来工具列表从 3 个变成 2 个时对话段完全不变因此对话段的缓存仍然可以命中工具段可能单独失效但因为它只是输入中的一小部分整体缓存失效的影响被大幅减少。另一种可能是5.2 对工具定义做了哈希摘要请求输入前缀中实际参与匹配的是哈希值而不是工具定义的完整文本。工具定义不变化时哈希值一致缓存命中。但极端情况下如果两个工具定义内容不同但哈希冲突理论上可能造成错误缓存所以这种实现需要谨慎设计。4.5 不要急着下结论验证方式很重要上面的解释更多是基于现象做推断。工程调试时不要只看“延迟变高”就认为是缓存失效建议通过响应中的usage字段确认缓存状态。不同版本字段可能不同常见的是{ prompt_tokens: 3000, prompt_tokens_details: { cached_tokens: 2400 } }cached_tokens表示命中缓存的 token 数量。如果这个值接近prompt_tokens说明大部分输入都命中了缓存如果为 0说明缓存完全没有命中。5. 实战如何稳定观测缓存命中状态5.1 封装一个缓存观测函数为了更好对比不同版本、不同工具列表下的缓存表现可以封装一个通用的观测函数把请求的耗时、缓存命中 token、总输入 token 都打印出来。# 文件路径cache_observer.py from openai import OpenAI client OpenAI() def call_with_cache_info(model: str, messages: list, tools: list None, label: str ): kwargs { model: model, messages: messages, tools: tools, tool_choice: auto if tools else None, } response client.chat.completions.create(**kwargs) usage response.usage details getattr(usage, prompt_tokens_details, None) cached details.cached_tokens if details else 0 total usage.prompt_tokens print(f[{label}] model{model}) print(f prompt_tokens{total}) print(f cached_tokens{cached}) print(f 缓存命中率{cached / total * 100:.1f}% if total else 无输入) return response使用这个函数可以快速对比相同消息、相同工具列表连续请求两次观察第二次是否命中。相同消息、删除工具后再请求观察缓存命中率变化。修改工具描述后再请求观察缓存命中率变化。5.2 一次完整的对比实验假设我们要做三组测试实验一相同请求连续发两次验证正常缓存。实验二删除一个工具定义观察缓存变化。实验三只修改工具描述再次观察缓存变化。# 文件路径run_experiment.py from cache_observer import call_with_cache_info SYSTEM_PROMPT 你是一个智能客服助手。 TOOLS [ { type: function, function: { name: query_order, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } }, { type: function, function: { name: query_logistics, description: 查询物流信息, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } } ] MESSAGES [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: 帮我查一下订单 2024001 的状态} ] # 实验一相同请求连发两次 call_with_cache_info(gpt-5.2, MESSAGES, TOOLS, label实验一-第一次) call_with_cache_info(gpt-5.2, MESSAGES, TOOLS, label实验一-第二次) # 实验二删除最后一个工具 call_with_cache_info(gpt-5.2, MESSAGES, TOOLS[:-1], label实验二-删除工具) # 实验三新增一个新工具 TOOLS_EXTRA TOOLS [ { type: function, function: { name: apply_refund, description: 申请退款, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } } ] call_with_cache_info(gpt-5.2, MESSAGES, TOOLS_EXTRA, label实验三-新增工具)根据输出结果可以做趋势分析。如果实验一中第二次请求cached_tokens明显大于 0但实验二、实验三都为 0说明工具定义变化确实会影响缓存。5.3 时间间隔对缓存的影响还有一个容易被忽略的因素缓存是有时间窗口的。多数实现中缓存内容会在一定时间后过期比如 5 分钟、1 小时或更长。如果两次请求间隔太久即使前缀完全一致也可能因为缓存过期而失效。因此做实验时建议连续请求间隔控制在 1 到 2 秒内。线上做性能对比时也要固定时间窗口避免把缓存过期误判为工具变化导致失效。6. 缓存失效后的优化策略6.1 方案一固定工具定义顺序tokens 的前缀匹配对顺序非常敏感。同一组工具如果每次请求顺序都不同缓存命中率会大幅下降。推荐做法是在代码中维护一个全局工具注册表按固定顺序输出。# 文件路径tool_registry.py TOOL_REGISTRY { query_order: { type: function, function: { name: query_order, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string, description: 订单编号} }, required: [order_id] } } }, query_logistics: { type: function, function: { name: query_logistics, description: 查询物流信息, parameters: { type: object, properties: { order_id: {type: string, description: 订单编号} }, required: [order_id] } } } } def get_tools(tool_names: list) - list: 按照注册表顺序返回工具列表而不是按照调用方传入顺序 return [TOOL_REGISTRY[name] for name in tool_names if name in TOOL_REGISTRY]这样做可以避免列表顺序抖动。同时不要每次请求动态生成工具定义尽量使用静态配置或序列化后的固定字符串。6.2 方案二按会话批量分组少改工具如果业务场景中不同用户需要的工具集合不同建议按照“会话维度”把用户分组每组使用固定的工具集合。比如客服会话使用包含query_order、query_logistics、apply_refund的工具集合。数据报表会话使用包含query_report、send_email的工具集合。工具集合一旦确定在整个会话生命周期内保持不变。即使某个用户在整个会话中没有调用过某个工具也不要在后续请求中删除它除非你确认可以接受缓存失效。6.3 方案三把工具描述做纯文本前置或后置有些团队会尝试把工具定义从系统提示词中拆出。比如在系统提示词里写“以下是可用工具”然后把 JSON 形式的工具描述放到用户消息开头。这种方式的作用是让工具描述更可控但缓存机制通常仍然按 token 前缀匹配所以并不能完全避免工具变化带来的失效。更稳妥的做法是接受“工具变化会导致缓存失效”然后把工具变化频率降到最低。比如工具描述、参数的变动统一走配置中心灰度发布避免高频变动。6.4 方案四使用更长的系统提示词垫底这是一个工程技巧但不适用于所有场景。假设系统提示词非常短只有几百 token即使缓存命中节省的成本也有限。某些实现会设置缓存生效的最小前缀长度比如 1024 token 或 2048 token小于这个长度不启用缓存。这种情况下可以为系统提示词增加一些固定内容比如“系统版本说明”“业务术语表”把系统提示词凑到超过最小值。注意这只是为了利用缓存机制不是推荐大家堆无用字符。如果能同时提升指令稳定性可以考虑否则不要为了缓存而缓存。6.5 方案五多版本验证与灰度在模型版本升级时建议对你的请求模板做一次缓存命中率回归。具体做法是记录旧版本的缓存命中率。用同样的消息和工具列表请求新版本。对比cached_tokens和首 token 延迟。如果命中率明显下降评估成本增加是否在可接受范围内。这套流程可以做成一个离线脚本每次升级模型前跑一遍避免上线后才发现成本异常。7. 常见问题与排查思路问题现象常见原因解决思路连续相同请求第二次cached_tokens仍为 0上下文长度不足未达到缓存最小 token 要求或两次请求间隔超过缓存过期时间检查上下文长度缩短请求间隔查看官方文档的缓存长度要求删除一个工具后缓存全量失效工具序列化内容属于输入前缀删除后前缀变化固定工具集合避免会话中途删除工具修改工具描述后缓存命中率下降描述文本属于 token 序列内容变化即失效工具描述使用稳定的静态文本不要拼接动态字段tools 顺序每次请求都不同列表顺序影响输入序列使用工具注册表按固定顺序输出同一个字符串不同客户端请求缓存命中率不同客户端自动给消息追加了额外字段或序列化顺序不同对比两个客户端最终发送的请求体统一序列化规则响应中看不到prompt_tokens_details版本不支持该字段或 SDK 版本过低升级 SDK查阅当前版本的 usage 字段结构缓存命中但首 token 延迟仍然很高命中的只是部分前缀用户消息跨度较大拆分多段请求或尽量保证更长前缀不变补充一个排查缓存问题的通用 checklist确认请求模型版本。确认输入前缀是否完全一致。确认工具列表是否发生变化包括增删、顺序、字段顺序。确认系统提示词是否变化。确认请求间隔是否超过缓存过期时间。确认usage.prompt_tokens_details.cached_tokens的实际数值。使用同一个客户端、同一套 SDK 做 A/B 对比。8. 最佳实践与工程建议8.1 工具定义纳入版本管理工具定义建议像代码一样纳入版本管理。每次修改工具定义时走代码评审流程。避免在 console 里直接手改线上配置因为工具定义的变化会影响缓存、token 消耗甚至可能引发模型对输入理解的偏差。在实现上可以把工具定义单独放在 JSON 文件中类似{ tools_version: v3, tools: [ { type: function, function: { name: query_order, description: 查询订单状态, parameters: { type: object, properties: { order_id: {type: string} }, required: [order_id] } } } ] }加载时读取该文件保证同一版本内工具定义完全一致。8.2 针对不同会话做工具集合隔离线上 Agent 如果给所有用户都返回全量工具可能会导致输入 token 虚高也会增加缓存失效概率。建议按业务域拆分工具集合。例如订单域query_order、cancel_order、apply_refund。物流域query_logistics、modify_address。售后域create_complaint、query_after_sale。每个会话只挂载当前业务域的工具。这样既能减少无效工具对模型判断的干扰也能让同一业务域内的请求拥有更稳定的工具前缀。8.3 日志中记录缓存命中率在线上环境建议把prompt_tokens_details.cached_tokens写入结构化日志并计算缓存命中率指标。一旦发现某个模型版本的命中率异常下降可以快速报警。示例日志结构{ model: gpt-5.2, session_id: abc123, prompt_tokens: 3200, cached_tokens: 2800, hit_ratio: 0.875, latency_ms: 510 }通过这个指标可以评估工具变更对成本的影响也方便做版本升级前后的对比。8.4 为工具变化设计“预热”请求如果你知道某个工具集合即将被大量使用比如下一个小时要批量处理一万个请求而这些请求都会带上新增的工具定义那么可以先发一次“预热”请求让后台完成缓存构建。这样后续大量请求更容易命中缓存。预热请求只需要保证输入前缀与正式请求一致即可。比如def warm_up(model: str, messages: list, tools: list): 预热请求触发服务端建立缓存 client.chat.completions.create( modelmodel, messagesmessages, toolstools, tool_choiceauto, max_tokens1, # 减少输出 token降低预热成本 )注意预热请求不一定适用于所有场景且预热本身也消耗 token。如果单次请求量不大可能不需要预热。8.5 安全与权限边界在涉及工具调用的系统中工具定义中可能包含敏感的业务字段。比如query_user_info的参数里可能包含手机号、身份证号等。把这类信息放入 tools 定义会影响缓存失效范围。建议敏感字段不要写入工具描述把字段名尽量模糊化。权限校验放在服务端而不是依赖模型不调用某个工具。删除工具定义时要同步清理客户端缓存和日志中的敏感信息。8.6 成本与性能权衡工具定义越多输入 token 越多即使缓存命中首次请求的成本也会更高。工具定义越少模型可选择的范围越小可能影响任务完成率。这个需要根据业务做权衡。如果发现工具列表已经超过 50 个可能需要考虑对工具做分层高频工具直接暴露给模型低频工具通过检索方式按需注入。9. 总结从缓存失效现象到系统化优化回到最开始的场景在 GPT-5.5 上删除一个工具导致缓存全量失效在 GPT-5.2 上却不受影响。这个现象的核心其实在于不同模型对 tools 的序列化与缓存策略存在差异。作为开发者不建议把“某个版本缓存命中率高”视为永久特性而应该把缓存命中率当成一个可观测、可优化的工程指标。本文主要分享了以下几点prompt cache 是自动前缀缓存工具定义是输入前缀的一部分。工具增删、顺序调整、描述改动都可能影响缓存命中。推荐用工具注册表固定工具顺序按业务域隔离工具集合。通过prompt_tokens_details.cached_tokens字段观测缓存命中率。模型升级时务必做缓存命中率回归测试。如果你正在用 function calling 搭 Agent建议下一步动手做三件事第一记录当前线上请求的缓存命中率第二整理一套固定顺序的工具注册表第三在测试环境中对比不同模型版本的工具变更表现。这样可以减少很多线上成本问题。