OpenAI 提示词缓存

为什么需要提示词缓存

提示词缓存复用多个请求中相同前缀的计算：避免重复计算已处理前缀；复用词元采用更低的缓存输入单价，折扣最高95%；减少响应开始前处理输入的时间。

支持的模型默认启用缓存。缓存用量面板用于监控读取命中率，缓存诊断用于调查未命中并改善复用。

Agents API模型调用采用与Responses相同的缓存行为。会话内复用上下文可以保留共享前缀，但维持会话不保证命中；会话用量与子智能体计费见可观测性和用量。价格因模型而异，见API定价。缓存写入不是额外叠加费：每个输入词元按普通输入、缓存读取或缓存写入三者之一计费。

什么是提示词缓存

模型处理输入词元时，会计算称为键值（KV）状态的中间状态，使后续输入和输出可以参照此前词元。缓存保存可复用前缀的状态，也就是提示词开头未变的部分。后续请求匹配到缓存条目时，复用状态，无需重算这些词元；新输入仍须处理，响应仍重新生成。

缓存存的是KV张量，不是词元本身。完整渲染上下文包括OpenAI提供的指令、developer消息、工具定义及历史对话，其中可含文本、图像、文档和支持的音频。复用要求整个渲染前缀匹配，断点前内容或相关设置改变后，该变化之后的前缀就不能匹配原条目。

哪些设置影响缓存前缀

请求改变不一定删除原缓存，关键是后续请求是否保留相同前缀，并能找到符合条件的匹配断点。

设置	影响
`model`	模型权重及缓存行为可能不同
`tools`	名称、说明、Schema、顺序或工具特定指令改变
`parallel_tool_calls`	可能改变一轮调用多个工具的指令
`text.format`	添加输出格式及Schema指令，见结构化输出
`reasoning.effort`	可能改变模型侧推理指令；支持的模型可用配置更新保留前缀
`text.verbosity`	可能改变回答详细度指令
`context_management`	压缩替换此前上下文，从首个变化词元起可能无法复用

缓存怎样工作

缓存断点标记可保存并在未来复用的前缀终点。首次请求写入符合条件的前缀，后续请求从最长前缀开始，沿合格断点向前查找匹配。

前缀须达到模型的最小可缓存长度；OpenAI提供的隐藏系统内容不计入该最低长度。GPT-5.6及以后为1,024个词元，较早模型随请求设置变化，见模型差异。超过最低长度后，可显式指定断点，也可由OpenAI隐式选择，支持方式依模型而定。

GPT-5.6及以后

默认30分钟有效期的写入费为普通输入的1.25倍。Responses可选12小时最短有效期，写入费2.5倍。读取通常为普通输入的0.1倍，GPT-6.1 Sol为0.05倍，不因所选有效期而改变。

以0.1倍读取、30分钟写入为例：写一次完整读一次合计普通输入成本的1.35倍，不缓存处理两次为2倍；十次请求一写九读为2.15倍，不缓存为10倍。

支持显式与隐式缓存，显式方式让开发者控制写入哪些上下文。

显式模式：设置prompt_cache_options.mode: "explicit"，只使用开发者断点；在消息支持的内容块上加入prompt_cache_breakpoint: { "mode": "explicit" }。

未放显式断点时，不使用缓存，也不产生缓存写入。
最后断点之后的内容按普通输入收费，不收写入费，可避免缓存不会复用的动态内容。
多断点保留变化频率不同的前缀，每请求最多产生四次写入。
additional_tools输入项目前不接受prompt_cache_breakpoint。
顶层instructions不能放显式断点；要标记可复用开发者指令，放在developer消息中的input_text块上。

隐式模式：prompt_cache_options.mode: "implicit"时，在最新合格消息末尾放断点。合格消息包括user消息、连续工具响应组中的最后一条，以及开头连续developer消息组中的最后一条。可额外放显式断点，隐式断点占四个写入名额之一，因此还可用三个显式写入名额。

较早模型

只支持隐式缓存，从隐藏OpenAI系统消息开头起按模型特定间隔放断点。只有从隐藏上下文末尾计数后达到最小长度的断点才合格。cached_tokens为最后匹配断点减去隐藏系统词元，再向下取整到128的倍数。

前缀匹配方式

OpenAI只检查当前请求中合格的缓存查找边界，从长到短寻找机器上已有的匹配前缀。GPT-5.6及以后：

仅显式模式：检查最前2个和最近50个显式断点。
隐式模式：除上述显式断点，还检查隐式断点、最多20个较早合格消息末尾，以及开头连续developer消息组的终点。因此无需在每处加显式断点，也能复用较早消息末尾的前缀。

缓存有效期

缓存不会永久保存。最短有效期、保留设置及读取后的行为取决于模型。

GPT-5.6及以后

Responses通过prompt_cache_options.ttl选择：

值	最短有效期	写入单价	适用
`"30m"`（默认）	30分钟	普通输入1.25倍	频繁复用的会话与智能体步骤
`"12h"`	12小时	普通输入2.5倍	间隔较长仍复用的稳定指令或资料

这是完整写入单价，不是普通输入之上的附加费。两种有效期的读取单价相同。实际保留可能长于最短有效期；"12h"不设删除期限，也不改变最大数据保留政策。

请求级ttl用于隐式断点及未单独设ttl的显式断点；prompt_cache_breakpoint.ttl可覆盖单个显式断点。两处都省略则默认"30m"，不支持的值返回400 invalid_request_error，不改变旧模型的prompt_cache_retention。

在同一请求混用有效期：全天复用资料放在开头，断点设"12h"；频繁改变的会话上下文设"30m"。下面请求默认30分钟，共享前缀覆盖为12小时，仅显式模式将当前问题留在最后断点之外，避免写入费。

下列英文占位文字依次译为：“全天重复使用的共享指令与参考资料……”“未来几分钟复用的会话上下文……”“当前问题，不需要写入缓存……”。这些省略号是内容占位，须换成实际足够长的前缀。

GPT-5.6及以后（来源示例1，json）

{
  "model": "gpt-6.1-sol",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Shared instructions and reference material reused throughout the day...",
          "prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Session context reused over the next few minutes...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "The current question, which does not need a cache write..."
        }
      ]
    }
  ]
}

以实际内容替换占位文字，各缓存前缀仍须达到最短长度。

写入重叠和有效期变化：断点涵盖之前整个前缀。同请求内，每个词元只按覆盖它的所选写入中最长有效期计费一次；后面的12小时写入也让该前缀内较早断点获得12小时覆盖。以下假定已有前缀能匹配新请求的合格查找边界。

请求前缓存	所选断点	计费读取	30分钟写入	12小时写入
无	2,000词元处`12h`，5,000处`30m`	0	3,000	2,000
无	2,000词元处`30m`，5,000处`12h`	0	0	5,000
前2,000词元有有效30分钟覆盖	5,000处`12h`	0	0	5,000
前2,000词元有有效12小时覆盖	5,000处`30m`	2,000	3,000	0

30分钟升级为12小时，相关词元重新收12小时写入费，不抵扣先前写入费；已有有效12小时覆盖的部分仍算读取。30分钟读取将覆盖刷新到读取后至少30分钟；若读取有效12小时条目，保留原到期时间和本次读取后30分钟中的较晚者，不重新启动12小时时钟，也不再次收写入费。最短有效期约束缓存读取价格资格，不保证每次实际复用KV张量或降低延迟。

较早模型

使用prompt_cache_retention，支持值依模型而定：in_memory通常在闲置5—10分钟后失活，最长一小时；24h通常保留约30分钟，最长24小时。

缓存可能将加密KV张量作为应用状态存到GPU本地存储。对同时支持两值的模型，未启用零数据保留（ZDR）的组织默认24h，启用ZDR的默认in_memory。选择前确认模型与组织支持的保留政策。

缓存位置

缓存位于单台机器。流量超过每分钟15次可能触发溢出路由，只有请求到达持有未过期匹配条目的机器才能复用。不跨组织共享，也不跨区域处理边界复用。

OpenAI自动路由。同组织、同处理区域、同模型内，路由取决于机器负载与容量、隐藏内容后初始词元的哈希（包含工具定义，哈希长度依模型），以及传入的prompt_cache_key。键分离请求组的复用，并帮助旧模型优化路由。

提示词缓存键

GPT-5.6之前，共享前缀的请求使用稳定prompt_cache_key，帮助路由到同一缓存。繁忙组每个键下所有前缀合计目标约15次/分钟；更高流量通过稳定、确定性映射分到多键，相关请求仍保持同键。键影响路由，不固定机器，也不保证命中。

GPT-5.6及以后自动处理路由，无需用键优化缓存；可为客户或用户分开核算。分键便于解释各客户用量与账单，也有助于防止跨用户探测：提交候选提示并观察命中，以猜测之前缓存过的内容。

模型差异一览

行为	GPT-5.6及以后	GPT-5.5与GPT-5.5 Pro	其他较早模型
隐式断点	最新合格消息末尾	每2,048词元	模型特定的固定间隔
显式断点	支持	不支持	不支持
`prompt_cache_key`	可选，分开核算	稳定键优化路由	稳定键优化路由
最小前缀	1,024个可见输入词元	随请求设置	随请求设置
缓存词元报告	精确合格边界，排除隐藏词元	排除隐藏词元，向下取整为128倍数	同左
读取	普通输入0.1倍，Sol为0.05倍	模型对应缓存输入价	模型对应缓存输入价
写入	`30m`为1.25倍，Responses的`12h`为2.5倍	不另收写入费	不另收写入费
有效期控制	`prompt_cache_options.ttl`	`prompt_cache_retention`	`prompt_cache_retention`
保留值	默认`30m`，Responses可用`12h`	仅`24h`	`in_memory`或`24h`，依模型
有效期	最短30分钟或12小时，按读取规则刷新	通常30分钟，最长24小时	in_memory闲置5—10分钟，24h最长24小时

延长保留支持：gpt-5.5、gpt-5.5-pro、gpt-5.4、gpt-5.2、gpt-5.1-codex-max、gpt-5.1、gpt-5.1-codex、gpt-5.1-codex-mini、gpt-5.1-chat-latest、gpt-5、gpt-5-codex、gpt-4.1。旧模型最短输入长度还受工具、图像、输出Schema、推理力度和详细度影响。

怎样优化提示词缓存

重点保留对话历史、保持工具定义稳定，并选择缓存位置。GPT-5.6及以后用模式与显式断点控制位置，按需用键分开客户核算；旧模型用稳定键优化共享前缀的路由。

保留对话历史

多轮应用复用不断增长的历史，可能比只缓存初始指令节省更多输入。保留此前消息和工具结果，使后续轮次复用完整共享前缀。

稳定developer指令和共享资料放前面；时间戳、用户特定值等动态内容放末尾或较晚消息。
追加新消息，避免重写旧轮次。摘要、压缩、截断可能改变前缀、重置复用。
GPT-6可追加configuration_update改变后续推理力度，同时保持请求级reasoning.effort不变，保留原前缀；兼容限制见对话内改变推理力度。

输入占位依次译为：“稳定指令与共享参考资料……”“动态开发者指令，例如用户特定内容和时间戳……”“用户当前的问题……”。

保留对话历史（来源示例2，json）

{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "low", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Stable instructions and shared reference material...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "developer",
      "content": "Dynamic developer instructions, such as user-specific content and timestamps..."
    },
    {
      "role": "user",
      "content": "The user's current question..."
    }
  ]
}

不改写前缀地改变推理力度

支持的GPT-6及以后模型可追加配置更新。顶层力度维持原值，修改顶层设置可能重写隐藏系统指令。最新更新控制后续响应；例如向已有input数组追加以下条目，改为high：

不改写前缀地改变推理力度（来源示例3，json）

{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

用只追加方式管理工具

工具需求变化时，只改变哪些工具可调用，保持定义稳定：保留定义、顺序和Schema；禁用时用tool_choice: "none"而不删除定义；只启用部分时用allowed_tools而不改工具列表；多轮初期可用工具搜索的defer_loading: true减少工具定义输入，发现的工具追加到末尾；用developer角色的additional_tools输入项按应用逻辑加载，并保留加载历史。

选择缓存模式

GPT-5.6及以后由prompt_cache_options.mode选择隐式或仅显式，prompt_cache_breakpoint标记自选边界。隐式适合持续追加上下文的多轮对话；显式放在稳定内容末尾，仅显式模式避免写入动态后缀。

示意含义：工具和Schema在稳定developer前缀及断点1之前；一条分支追加动态developer后缀和会话后到断点2，再分为不同用户输入；另一分支有未选择的动态后缀。各分支最后所选断点后的内容只按普通输入价收费，不收写入费。

预热缓存

GPT-5.6及以后可提前准备已知上下文，降低后续首词元时间。例如交互应用启动时预热共享指令、工具定义或参考资料。

Responses设置prompt_cache_options.prewarm: true，只准备缓存不生成输出。完成后以相同前缀发送实际请求，省略prewarm或设为false。

示例中Your app's shared instructions and reference material...译为“应用的共享指令与参考资料……”，后续The user's question...译为“用户的问题……”。

预热缓存（来源示例4，json）

{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

后续请求：

预热缓存（来源示例5，json）

{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    },
    {
      "role": "user",
      "content": "The user's question..."
    }
  ]
}

预热写入按所选有效期的写入单价收费。

用键分开缓存核算

GPT-5.6及以后，prompt_cache_key可分开客户、用户或工作区的缓存账目，并非缓存优化所必需。为需要分开核算的组设不同键，如support:customer_123、support:customer_456，即便前缀相同也分开；组内相关请求复用稳定键，仅在会话本身需要独立核算时才按会话分键；跨请求一致应用客户键，也有助于防止跨客户命中探测。

旧模型中键对命中优化重要，共享前缀使用稳定键，繁忙组按前述规则分流。

配置保留时间

支持新选项的Responses模型，频繁复用用30m，长间隔稳定前缀可考虑12h。比较较高12小时写入价与30分钟过期后重写成本；通过断点覆盖，让共享资料比会话内容保留更久。旧模型在模型及数据政策允许时优先考虑prompt_cache_retention: "24h"。

避免最短可缓存长度的成本陷阱

大量请求共享的指令和工具前缀低于最低长度时，可考虑缩短它，或用有价值且稳定的指令、示例、资料扩充。测量复用是否抵消新增输入及写入成本，并确认评测、行为不退化。来源图表展示短前缀不缓存的成本可能高于扩充到最短长度，使用新模型的30分钟写入价。

数学细节

仅比较成本：设最低长度为M，原长度L<M，读取倍数r，写入倍数w，请求总数N。假设扩充后恰为M，只写一次，此后每次完整复用。以普通输入词元成本计，原方案为N×L，扩充为M[w+(N−1)r]。盈亏平衡为：

L_break-even = M[r + (w−r)/N]。

L高于该值时扩充更便宜，低于它时保持短前缀更便宜，相等则成本相同。开始更便宜的最小整数长度为floor(L_break-even)+1。反过来，将可缓存前缀缩至M以下会失去缓存；同样假设下，必须低于该平衡值才比缓存M个词元便宜。不存在通用“最贵提示词长度”，交点取决于复用和价格。

例：M=1,024、r=0.1、w=1.25，交点为102.4 + 1,177.6/N。十次请求时，原前缀至少221个词元，扩到1,024更便宜；复用增加时，交点趋近102.4。103词元前缀至少要1,963次总请求才获益；102或更少在此假设下永远不获益。不计性能、输出词元和未改变的请求成本；额外未命中、写入或不同模型费率都会改变结果。

监控缓存表现

跟踪usage.input_tokens_details.cached_tokens、cache_write_tokens、分有效期写入量、输入量、延迟及实际成本。词元命中率为总缓存词元除以总输入词元，可按用户、工作区、日期等汇总。用response.usage及模型每百万词元价格计算输入成本，并在控制台监控。

新选项的input_tokens_details.cache_write_tokens_details包含ttl_30m_tokens和ttl_12h_tokens，二者不重叠，相加等于cache_write_tokens，即便一项为零也返回。cached_tokens只计读取，不含按写入收费的词元，包括30分钟升级12小时的写入。

监控缓存表现（来源示例6，json）

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

本例普通输入为12000−4000−7000=1000。普通输入乘输入价、读取乘缓存价、30分钟写入乘1.25倍输入价、12小时写入乘2.5倍，合计后按每百万单位除以1,000,000。不要再重复加入总写入量。

若输入价$1/百万、缓存输入价$0.10/百万，本例输入成本为(1000+4000×0.1+3000×1.25+4000×2.5)/1000000=$0.01515，实际应采用对应模型的费率。

下面辅助函数对所有写入使用单一倍数：全为30分钟时用1.25，全为12小时时用2.5；混合请求应按上述组件分别算。

监控缓存表现（来源示例7，javascript）

// [中文] 先用总输入减去缓存读取量和缓存写入量，得到普通输入词元，避免重复计费。
// [中文] 分别按普通、读取、写入倍率加权，再乘每百万词元单价并除以1,000,000；倍率由调用方按实际模型传入。
function calculateInputCost(
  usage,
  inputPricePerMillion,
  cacheInputMultiplier = 0.1,
  cacheWriteMultiplier = 1.25
) {
  const inputTokens = usage.input_tokens;
  const cachedTokens = usage.input_tokens_details.cached_tokens;
  const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
  const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;

  const weightedInputTokens =
    ordinaryInputTokens +
    cachedTokens * cacheInputMultiplier +
    cacheWriteTokens * cacheWriteMultiplier;
  const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
  return inputCost;
}

监控缓存表现（来源示例8，python）

## [中文] 先用总输入减去缓存读取量和缓存写入量，得到普通输入词元，避免重复计费。
## [中文] 分别按普通、读取、写入倍率加权，再乘每百万词元单价并除以1,000,000；倍率由调用方按实际模型传入。
from openai.types.responses import ResponseUsage


def calculate_input_cost(
    usage: ResponseUsage,
    input_price_per_million: float,
    cache_input_multiplier: float = 0.1,
    cache_write_multiplier: float = 1.25,
) -> float:
    input_tokens = usage.input_tokens
    cached_tokens = usage.input_tokens_details.cached_tokens
    cache_write_tokens = usage.input_tokens_details.cache_write_tokens
    ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

    weighted_input_tokens = (
        ordinary_input_tokens
        + cached_tokens * cache_input_multiplier
        + cache_write_tokens * cache_write_multiplier
    )
    input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
    return input_cost

监控缓存表现（来源示例9，go）

// [中文] 先用总输入减去缓存读取量和缓存写入量，得到普通输入词元，避免重复计费。
// [中文] 分别按普通、读取、写入倍率加权，再乘每百万词元单价并除以1,000,000；倍率由调用方按实际模型传入。
func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
    ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
    weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
    return weighted * pricePerMillion / 1_000_000
}

监控缓存表现（来源示例10，java）

// [中文] 先用总输入减去缓存读取量和缓存写入量，得到普通输入词元，避免重复计费。
// [中文] 分别按普通、读取、写入倍率加权，再乘每百万词元单价并除以1,000,000；倍率由调用方按实际模型传入。
import com.openai.models.responses.ResponseUsage;

static double calculateInputCost(
    ResponseUsage usage,
    double pricePerMillion,
    double cacheInputMultiplier,
    double cacheWriteMultiplier) {
  long cached = usage.inputTokensDetails().cachedTokens();
  long written = usage.inputTokensDetails().cacheWriteTokens();
  long ordinary = usage.inputTokens() - cached - written;
  return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
      * pricePerMillion
      / 1_000_000;
}

监控缓存表现（来源示例11，ruby）

## [中文] 先用总输入减去缓存读取量和缓存写入量，得到普通输入词元，避免重复计费。
## [中文] 分别按普通、读取、写入倍率加权，再乘每百万词元单价并除以1,000,000；倍率由调用方按实际模型传入。
def calculate_input_cost(
  usage,
  input_price_per_million,
  cache_input_multiplier = 0.1,
  cache_write_multiplier = 1.25
)
  input_tokens = usage.input_tokens
  details = usage.input_tokens_details
  cached_tokens = details.cached_tokens
  cache_write_tokens = details.cache_write_tokens
  ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

  weighted_input_tokens = ordinary_input_tokens +
                          (cached_tokens * cache_input_multiplier) +
                          (cache_write_tokens * cache_write_multiplier)
  (weighted_input_tokens * input_price_per_million) / 1_000_000
end

从旧模型迁移到GPT-5.6及以后

保持稳定前缀；已有缓存键保留其值以维持独立核算；用prompt_cache_options.ttl替代旧保留字段；确认前缀达到新最低长度；默认断点包含动态内容时，在稳定前缀后加显式断点；后缀不值得写入时采用仅显式模式；对比迁移前后的读取、写入、延迟和总成本。

示例

以下适用于GPT-5.6及以后。

单轮LLM评分器

评分器判断一次已完成的用户与聊天机器人交互是否体现用户满意。每次用相同评分标准和带标签少样本，评估不同交互。

固定标准及示例放前，组合长度刻意略高于最低长度，使用有助校准的材料；待评分交互放最后。启用仅显式缓存，在标准和示例之后放断点，不写入不太可能复用的待评分对话。来源举例部署的词元命中率约70%，只是可能结果，实际取决于上下文及使用方式。

程序内完整评判任务为：“判断已完成的交互是否提供了用户满意的证据。返回true或false。完整评分标准及已标注的少样本示例……”用户部分Completed interaction to evaluate...为“待评估的已完成交互……”。

单轮LLM评分器（来源示例12，json）

{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "user",
      "content": "Completed interaction to evaluate..."
    }
  ]
}

多轮智能体

智能体有较长共享developer指令、频繁工具调用，用户可能同时运行多会话、分叉线程。

每轮追加消息、调用及结果，不改旧上下文；前缀随之增长。可选键agent_123_v1:user_456用于用户456独立核算并防止跨用户命中探测，在同用户会话与分叉中保持不变；无需独立核算则省略。启用隐式缓存，让最新合格user或工具消息提供断点，并在每个工具结果后加显式断点，保留较早前缀、改善分叉效率。来源示例部署命中率超过90%，不是普遍上限保证。

工具与会话占位依次表示：“函数说明”“稳定的开发者指令与参考资料……”“你能做……吗？”“工具结果……”“助手回复……”“你还能做……吗？”。

多轮智能体（来源示例13，json）

{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_key": "agent_123_v1:user_456",
  "prompt_cache_options": { "mode": "implicit" },
  "tools": [
    {
      "type": "function",
      "name": "function_name",
      "description": "Function description",
      "parameters": { "...": "..." }
    }
  ],
  "input": [
    {
      "role": "developer",
      "content": "Stable developer instructions and reference material..."
    },
    { "role": "user", "content": "Can you do...?" },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "function_name",
      "arguments": "..."
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": [
        {
          "type": "input_text",
          "text": "Tool result...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    { "role": "assistant", "content": "Assistant response..." },
    { "role": "user", "content": "Can you also do...?" }
  ]
}

常见陷阱

共享前缀不一定已经缓存

旧模型迁移到新模型时尤其常见：隐式行为改变。静态developer后跟动态user，首次只在完整请求末尾隐式缓存，并不会自动让较短共享前缀可复用。新动态内容不匹配较长旧前缀，静态末尾也没有独立断点。

此处Static content...与Dynamic content...分别译为“静态内容……”与“动态内容……”，下一个显式断点示例沿用“静态内容……”占位。

共享前缀不一定已经缓存（来源示例14，json）

{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "implicit" },
  "input": [
    { "role": "developer", "content": "Static content..." },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

两次请求都在静态内容后加显式断点，首轮写入，后轮即使动态内容变化仍能读取。用仅显式模式可避免写动态部分。

共享前缀不一定已经缓存（来源示例15，json）

{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Static content...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

改成仅显式模式可能错过隐式缓存

请求1隐式缓存到user消息末尾；请求2保留该前缀但改为仅显式，只检查自身显式断点，不会读取此前隐式终点，除非某个显式断点恰好匹配。

改成仅显式模式可能错过隐式缓存（来源示例16，text）

▼ = 断点
- 请求1：隐式模式
  [Developer消息][User消息] ▼
- 请求2：仅显式模式，不命中缓存。
  [Developer消息][User消息][后续内容] ▼

可在请求2相同内容块边界放显式断点，或保持隐式模式，让较早合格消息末尾继续参与查找。

延长一条消息可能妨碍复用

即使两次都用隐式模式，保留初始词元也未必够。请求1的user为Content A，后续将同条消息扩为Content A + Content B，旧终点变成消息内部；未在该处放显式断点就无法复用。

延长一条消息可能妨碍复用（来源示例17，text）

▼ = 断点
- 请求1：隐式模式
  [Developer消息][User消息：Content A] ▼
- 请求2：隐式模式，无法复用到Content A末尾的前缀。
  [Developer消息][User消息：Content A + Content B] ▼

结构允许时，保留原消息并追加新消息；否则将可复用文字分为独立内容块，两次都在其后放显式断点。

并非所有developer消息都是自动查找边界

隐式模式仅开头连续developer组可自动提供边界，后面的developer消息不能。要复用其末尾前缀，应加显式断点，并在后续保留该位置。

最小长度随模型变化

一个模型够长的前缀，在另一个可能不够。按实际模型和设置测量，切换模型后重新检查，不沿用旧阈值。

压缩可能减少复用

压缩用更短表示替换旧上下文，改变前缀，即使逻辑相同，压缩后首请求也可能少读旧缓存。尽量保持可复用指令和资料稳定，后续在压缩上下文上继续增长。比较总输入成本：命中率降低时，输入减少仍可能省钱。

常见问题

缓存会影响输出生成吗

不会改变输出词元生成方式。模型用缓存前缀生成新响应，相同请求不保证相同输出。

可以手动清缓存吗

目前不支持，条目按模型有效期和保留设置过期。

缓存提示词计入速率限制吗

计入。缓存输入词元仍计入每分钟词元限制，缓存不改变速率限制计算方式。