如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

提示词缓存

使用提示词缓存降低延迟和成本。

为什么要使用提示词缓存

当多个请求具有相同的提示词前缀时,提示词缓存可以复用已有的计算结果。这主要有三个好处。

  • 节省算力。 无需重新计算模型已经处理过的提示词前缀。
  • 降低输入 Token 费用。 复用的 Token 按模型较低的缓存输入费率计费,最高可节省 95%。
  • 加快响应。 缩短模型开始响应前处理输入的时间。

支持提示词缓存的 OpenAI 模型默认启用此功能。您可以在提示词缓存仪表板中监控缓存读取命中率,也可以使用提示词缓存诊断工具排查缓存未命中的原因,提高缓存复用率。

通过 Agents API 调用模型时,提示词缓存的工作方式与 Responses API 相同。在会话中复用上下文有助于保留共享的提示词前缀,但维持同一会话并不能保证缓存命中。有关会话用量字段和子智能体用量统计,请参阅可观测性与用量。

提示词缓存的价格因模型而异。有关当前的缓存输入费率和缓存写入费率,请参阅 API 定价。每个输入 Token 只按未缓存输入、缓存输入或缓存写入三种费率之一计费。

什么是提示词缓存?

模型处理输入 Token 时,必须计算称为键值(KV)状态的中间状态。有了这些状态,模型在处理新输入和生成输出 Token 时就能参考之前的 Token。

提示词缓存会为可复用的前缀保存这些状态。前缀是指提示词开头保持不变的一段 Token。如果后续请求具有相同的前缀,并且找到了匹配的缓存条目,模型就能复用已保存的状态,省去重复处理这些 Token 的步骤。模型仍需处理新输入才能生成新的响应。

提示词缓存存储键值(KV)张量,不存储 Token 本身。

让 ChatGPT 进一步解释

在模型渲染后的上下文中,符合缓存条件的前缀可以包含 OpenAI 提供的指令、开发者消息、工具定义和对话历史记录。对话历史记录可以包含文本、图像、文档和受支持的音频。

要复用缓存,渲染后的整个前缀都必须匹配。如果断点之前的内容或相关设置发生变化,包含该变化的前缀就无法与现有缓存条目匹配。

缓存的工作原理

缓存断点标记提示词前缀的结束位置。OpenAI 可以将截至该位置的前缀保存到缓存中,供后续请求复用。第一个请求将符合条件的前缀写入缓存。后续请求会从后往前逐个检查符合条件的断点,直到找到可用的最长匹配缓存前缀。

提示词前缀的 Token 数必须达到模型的最小可缓存长度,才能写入缓存。OpenAI 提供的隐藏系统内容中的 Token 不计入这一门槛。对于 GPT-5.6 及后续模型,提示词的最小可缓存长度为 1,024 个 Token。对于更早的模型,该长度因请求设置而异。详情请参阅模型对比。

达到最小可缓存 Token 数后,您可以显式指定缓存断点的位置,也可以让 OpenAI 隐式选择。可用选项取决于模型。

前缀如何匹配

OpenAI 只检查传入请求中的缓存查找边界(见下文),按前缀从长到短的顺序,查找当前机器上已缓存且可用的匹配前缀。

对于 GPT-5.6 及后续模型,传入请求中的缓存查找边界取决于缓存模式。

  • 仅显式模式。 最前面的 2 个显式断点和最后面的 50 个显式断点。
  • 隐式模式。 最前面的 2 个显式断点、最后面的 50 个显式断点、隐式断点、之前最多 20 条符合条件的消息的末尾,以及开头一组连续开发者消息的末尾。因此,即使较早消息的末尾没有显式断点,隐式模式也可以复用截至该位置的前缀。

仅适用于当前请求的开发者指令应放在顶层 instructions 中。例如,您可以在工作流的最后一轮要求模型汇总结果。从 GPT-6.2 开始,模型(包括 Astra 和 Sol)会将这些指令追加到 input 之后,位于所有符合条件的缓存断点之后。因此,您可以在不同轮次之间更改这些指令,之前的前缀仍符合缓存复用条件。使用 previous_response_id 时,这些顶层指令不会自动沿用到下一次请求。

即使每次提交的指令完全相同,OpenAI 也会在每次请求中按未缓存输入 Token 费率对这些指令的 Token 计费。要让可复用的指令符合缓存条件,请将其放在一条 developer 消息中,并将该消息置于 input 开头。使用 previous_response_id 时,这条消息会保留在对话历史记录中。在隐式模式下,可以复用截至开头一组开发者消息末尾的前缀。要显式指定边界,请在开发者消息的 input_text 块上添加 prompt_cache_breakpoint: { "mode": "explicit" }。

模型代际
缓存模式

隐式断点设在最近一条符合条件的用户消息处。

隐藏的系统内容工具开发者历史上下文后续消息已缓存的输入未缓存的输入
可缓存的最小长度(因模型而异)

请求 1

12,000 个输入 Token
3,000 个 Token(示意)

请求 2

15,000 个输入 Token
3,000 个 Token(示意)
0
2.5k
5k
7.5k
10k
12.5k
15k
17.5k
20k
输入 Token(含用于示意的隐藏 Token)
15,000
最后一个匹配的断点
−
3,000
隐藏的 Token
=
12,000
响应中报告的缓存 Token 数

缓存有效期

缓存条目的保留时间有限。缓存的最短有效期、保留设置,以及请求复用前缀时的行为均取决于模型。

缓存位置

缓存状态存储在各台机器上。流量超过每分钟 15 个请求时,部分请求可能被分流到其他机器。只有当请求到达的机器上存在匹配且未过期的缓存条目时,才能复用缓存前缀。因此,将请求路由到合适的机器对于复用缓存很重要。

不同组织之间不共享缓存,缓存也不能跨区域处理边界复用。

OpenAI 会自动处理路由。在同一组织和处理区域内,特定模型的请求路由取决于以下因素。

  • 机器当前的负载和可用容量。
  • OpenAI 提供的隐藏内容之后一段起始 Token 的哈希值。如果有工具定义,也会包含在内。参与哈希计算的 Token 数因模型而异。
  • 请求中提供的 prompt_cache_key。它将缓存复用限制在各自的请求组内,在 GPT-5.6 之前的模型上还有助于优化缓存路由。

模型差异概览

行为 GPT-5.6 及后续模型 GPT-5.5 和 GPT-5.5 Pro 其他较早的模型
隐式断点 位于最近一条符合条件的消息末尾。 每隔 2,048 个 Token 设置一个。 按固定间隔设置,间隔因模型而异。
显式断点 支持 不支持 不支持
prompt_cache_key 可选,用于分别统计缓存用量 使用稳定的键优化缓存路由 使用稳定的键优化缓存路由
最小可缓存前缀 1,024 个可见输入 Token 取决于请求设置 取决于请求设置
缓存 Token 数的报告方式 精确计数至符合条件的边界,不含隐藏 Token 排除隐藏 Token,向下取整到 128 的倍数 排除隐藏 Token,向下取整到 128 的倍数
缓存读取费用 未缓存输入费率的 0.1 倍(GPT-6.2 Astra、GPT-6.2 Sol、GPT-6.1 Sol 和 GPT-6.1 Terra 为 0.05 倍) 按模型的缓存输入费率计费 按模型的缓存输入费率计费
缓存写入费用 有效期为 "30m" 时按未缓存输入费率的 1.25 倍计费,Responses API 中有效期为 "12h" 时按 2.5 倍计费 无额外缓存写入费用 无额外缓存写入费用
缓存有效期设置 prompt_cache_options.ttl prompt_cache_retention prompt_cache_retention
支持的保留设置值 "30m"(默认),或 Responses API 中的 "12h" 仅 "24h" "in_memory" 或 "24h"*
缓存有效期 最短为 30 分钟或 12 小时,请参阅刷新机制 通常约 30 分钟,最长 24 小时 通常闲置 5 到 10 分钟后过期(in_memory),或最多保留 24 小时(24h)

在 Responses API 中,从 GPT-6.2 开始,模型会将顶层 instructions 追加到 input 之后。即使请求命中缓存,这些指令的 Token 仍按未缓存输入费率计费。请将可复用的指令放在 input 中的第一条 developer 消息里。

* 支持延长保留的模型包括 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。

对于 GPT-5.6 之前的模型,最小可缓存输入长度取决于请求设置,包括工具、图像、输出模式、推理强度和响应详细程度。

让 ChatGPT 确定我的请求的最小可缓存长度

如何优化提示词缓存

请重点关注保留对话历史记录、保持工具定义稳定,以及选择缓存断点的位置。在 GPT-5.6 及后续模型上,使用 prompt_cache_options.mode 和 prompt_cache_breakpoint 控制缓存断点。如果您的应用需要按客户分别统计缓存用量,还可以使用可选的 prompt_cache_key。在 GPT-5.6 之前的模型上,请为具有相同可复用前缀的请求使用稳定的 prompt_cache_key,以优化缓存路由。

让 ChatGPT 帮我优化提示词缓存

示例

以下示例适用于 GPT-5.6 及后续模型。

常见陷阱

常见问题

数据保留

所有提示词缓存功能均兼容零数据保留(ZDR)。

提示词缓存只存储键值(KV)张量,不存储提示词原文。这些张量可能作为加密的应用状态保存在 GPU 本地存储中,最长保留 24 小时。有关各模型的缓存有效期和刷新机制,请参阅缓存有效期。

不同组织之间不共享缓存,缓存也不能跨区域处理边界复用。有关各项 API 功能如何处理数据以及是否符合零数据保留条件的详细信息,请参阅您的数据。