提示缓存 | OpenAI API

为什么提示缓存很重要

当请求具有相同的提示前缀时，提示缓存可以复用已有的计算结果。这主要带来三项好处：

节省计算资源： 避免重新计算模型已处理过的提示前缀。
输入 Token 费用更低： 复用的 Token 按模型较低的缓存输入费率计费，费用最高可降低 90%。
速度更快： 缩短开始响应前处理输入所需的时间。

支持提示缓存的 OpenAI 模型默认启用此功能。使用提示缓存仪表板监控缓存读取命中率，并使用提示缓存诊断工具诊断缓存未命中的原因，提高缓存复用率。

Agents API 模型调用的提示缓存行为与 Responses API 相同。在会话中复用上下文可以保留共享的提示前缀，但维持会话并不保证缓存命中。有关会话用量字段和子智能体用量核算的信息，请参阅可观测性和用量。

提示缓存的定价因模型而异。有关当前的缓存输入和缓存写入费率，请参阅API 定价。缓存写入费用并非额外收取：输入 Token 按未缓存输入、缓存输入或缓存写入费率中的一种计费。

什么是提示缓存？

模型处理输入 Token 时，必须计算称为键值（KV）状态的中间状态。这些状态让模型能够在处理新输入和生成输出 Token 时参考之前的 Token。

提示缓存会为可复用的前缀保存这些状态。前缀是提示开头保持不变的 Token。当后续请求具有相同前缀，并找到匹配的缓存条目时，模型就可以复用已保存的状态，无须再次处理这些 Token。模型仍需处理所有新输入，才能生成新的响应。

提示缓存存储的是键值（KV）张量，而非 Token 本身。

请 ChatGPT 进一步解释

OpenAI 会缓存模型渲染后的完整上下文，包括 OpenAI 提供的指令、开发者消息、工具定义，以及包含文本、图像、文档和受支持的音频的对话历史。

复用缓存要求渲染后的整个前缀完全匹配。如果断点之前的内容或相关设置发生变化，包含该变更及其后续内容的前缀就无法匹配现有缓存条目。

更改请求不一定会丢弃现有缓存条目。关键在于后续请求是否具有相同前缀，以及能否找到符合条件的匹配断点。需要检查的主要设置如下：

设置	影响
`model`	不同模型可能使用不同的权重，并具有不同的缓存行为。
`tools`	更改工具名称、描述、模式、顺序或工具专用指令。
`parallel_tool_calls`	可能更改有关在同一轮中调用多个工具的指令。
`text.format`（结构化输出）	添加输出格式指令和请求中指定的模式。
`reasoning.effort`	可能更改模型侧的推理指令。对于支持此功能的模型，请使用配置更新来调整推理强度，同时保留之前的前缀。
`text.verbosity`	可能更改有关响应详细程度的指令。
`context_management`（压缩）	将较早的对话内容替换为压缩后的上下文，可能导致从第一个发生变化的 Token 起无法复用缓存。

缓存的工作原理

缓存断点 标记提示前缀的结束位置，OpenAI 可以将此前缀保存到缓存中，供后续请求复用。首个请求将符合条件的前缀写入缓存，后续请求则从后向前检查符合条件的断点，直到找到匹配项，从而找到当前可用的最长匹配缓存前缀。

提示前缀必须达到模型的 最小可缓存 Token 长度 才能缓存。OpenAI 提供的隐藏系统内容中的 Token 不计入此最低要求。GPT-5.6 及后续模型的最小可缓存提示长度为 1,024 个 Token，早期模型则因请求设置而异。详情请参阅模型对比。

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

对于 GPT-5.6 及后续模型，缓存写入按标准未缓存输入 Token 费率的 1.25 倍计费。当您确定某个前缀会被复用时，支付这笔费用是值得的，因为后续读取的费率仅为标准费率的 0.1 倍。将前缀写入一次并完整复用一次，费用为其普通输入费用的 1.35 倍，而不使用缓存处理两次的费用为 2 倍。每增加一次缓存读取，节省的费用就会更多：在十次请求中，一次写入加九次完整读取的费用为普通输入费用的 2.15 倍，而不使用缓存则为 10 倍。

隐式缓存和显式缓存均受支持，其中显式缓存让您能够更精确地控制将哪些上下文写入缓存。

显式模式： 您根据自己的上下文管理方式选择缓存断点的位置。

将 prompt_cache_options.mode 设为 explicit，即可仅使用开发者选定的断点；在输入消息中受支持的内容块上添加 prompt_cache_breakpoint: { "mode": "explicit" }，即可标记所需的各个断点。
如果未设置显式断点，请求就不会使用提示缓存，也不会执行缓存写入。
仅显式模式让您能够选择缓存写入的结束位置。最后一个选定断点之后的内容按未缓存输入 Token 费率处理，不收取缓存写入费用，因此您可以避免将会变化且不太可能复用的内容写入缓存。
多个显式断点可以保留变化频率不同的前缀。每个请求最多可以执行四次缓存写入。
additional_tools 输入项目前不接受 prompt_cache_breakpoint。

顶层 instructions 不能包含显式断点。要标记可复用的开发者指令，请将其放在开发者消息中的 input_text 块内。

隐式模式： OpenAI 会自动选择适合大多数使用场景的断点位置，无须额外设置。

当 prompt_cache_options.mode 为 implicit 时，OpenAI 会在最近一条符合条件的消息末尾设置断点。符合条件的消息包括：
- 用户消息
- 一组连续工具响应中的最后一条工具响应
- 开头一组连续开发者消息中的最后一条开发者消息。
您可以在保留隐式断点的同时添加显式断点；隐式断点会占用四个缓存写入名额中的一个，剩余三个名额可用于显式缓存写入。

前缀匹配的工作原理

OpenAI 仅遍历传入请求中的 缓存查找边界 （下文详述），按前缀从长到短的顺序，查找当前机器上已缓存且可用的匹配前缀。

对于 GPT-5.6 及后续模型，传入请求中的缓存查找边界包括：

仅显式模式： 最前面的 2 个和最近的 50 个显式断点。
隐式模式： 最前面的 2 个和最近的 50 个显式断点、隐式断点、此前最多 20 条符合条件的消息的末尾，以及开头连续的一组开发者消息的末尾。因此，隐式模式可以复用截至较早消息末尾的前缀，即使那里没有显式断点。

模型代际

缓存模式

隐式

显式

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

隐藏的系统内容工具开发者上下文历史记录后续消息缓存输入未缓存的输入

最小可缓存长度（因模型而异）

请求 1

12,000 个输入 Token

3,000 个 Token（示意）

请求 2

15,000 个输入 Token

3,000 个 Token（示意）

2.5k

7.5k

10k

12.5k

15k

17.5k

20k

输入 Token（包括用于示意的隐藏 Token）

15,000

最后一个匹配的断点

−

3,000

隐藏的 Token

12,000

报告的缓存 Token 数

请求 1 · Responses API 请求

import OpenAI from "openai";

const client = new OpenAI();
const response = await client.responses.create({
  "model": "gpt-5.6",
  "reasoning": {
    "effort": "medium",
    "context": "all_turns"
  },
  "text": { "verbosity": "medium" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "8,000 tokens"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "2,000 tokens"
        }
      ]
    }
  ],
  "tools": [
    "Tool definitions, 2,000 tokens"
  ],
  "prompt_cache_key": "shared-workflow-v1",
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "30m"
  }
});

请求 2 · Responses API 请求

import OpenAI from "openai";

const client = new OpenAI();
const response = await client.responses.create({
  "model": "gpt-5.6",
  "reasoning": {
    "effort": "medium",
    "context": "all_turns"
  },
  "text": { "verbosity": "medium" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "8,000 tokens"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "2,000 tokens"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "3,000 tokens"
        }
      ]
    }
  ],
  "tools": [
    "Tool definitions, 2,000 tokens"
  ],
  "prompt_cache_key": "shared-workflow-v1",
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "30m"
  }
});

请求 1 · 响应用量

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 12000
    }
  }
}

请求 2 · 响应用量

{
  "usage": {
    "input_tokens": 15000,
    "input_tokens_details": {
      "cached_tokens": 12000,
      "cache_write_tokens": 3000
    }
  }
}

缓存有效期

缓存条目不会永久保存。只有在条目仍然可用时，后续请求才能复用缓存的前缀；复用前缀会刷新其有效期，且不会再次产生缓存写入费用。有效期和保留设置因模型而异。

缓存位置

缓存状态存储在各台机器上，每分钟超过 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 的倍数
缓存读取费用	未缓存输入 Token 费率的 0.1 倍	缓存输入费率因模型而异	缓存输入费率因模型而异
缓存写入费用	未缓存输入 Token 费率的 1.25 倍	无额外缓存写入费用	无额外缓存写入费用
缓存有效期控制	`prompt_cache_options.ttl`	`prompt_cache_retention`	`prompt_cache_retention`
支持的保留设置值	`"30m"`	仅支持 `"24h"`	`"in_memory"` 或 `"24h"`^*
缓存有效期	最近一次写入或复用后至少保留 30 分钟	通常约 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 支持延长保留。

对于 GPT-5.6 之前的模型，最短可缓存输入长度随请求设置而变化，包括工具、图像、输出模式、推理强度和详细程度。

请 ChatGPT 帮我确定请求的最短可缓存输入长度

如何优化提示缓存

重点是保留对话历史记录、保持工具定义稳定，以及选择缓存位置。在 GPT-5.6 及后续模型上，请使用 prompt_cache_options.mode 和 prompt_cache_breakpoint 控制缓存断点。如果您的应用需要为不同客户分别核算缓存用量，也可以使用可选的 prompt_cache_key。对于 GPT-5.6 之前的模型，请使用稳定的 prompt_cache_key，为共享可复用前缀的请求优化缓存路由。

请 ChatGPT 帮我优化提示缓存

在多轮对话应用中，复用不断增长的对话历史，比仅缓存初始指令能节省更多输入 Token。保留之前的消息和工具结果，让后续轮次能够复用完整的共享前缀。

保持前缀稳定。 将稳定的开发者指令和共享参考资料放在最前面。如果开发者指令或共享资料包含时间戳、用户专属内容或其他动态内容，请将这些内容放在末尾而非开头，或移到后续的对话消息中。
保留对话历史。 追加新消息，不要重写之前的对话轮次。生成摘要、压缩或截断上下文可能会改变前缀，使缓存无法继续复用。
在不重写前缀的情况下更改推理力度。 在 GPT-6 Astra 上，追加一个 configuration_update 输入项，即可在两次响应之间更改推理力度，同时保持请求级别的 reasoning.effort 不变。这样可以保留原始前缀以供缓存复用。有关示例和兼容性限制，请参阅在对话中途更改推理。

将变化的内容放在断点之后

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "model": "gpt-5.6",
  "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 及更新模型上，追加一个 configuration_update 输入项，即可在对话期间更改推理力度，同时保留之前缓存的前缀。请保持顶层 reasoning.effort 的原始值不变，因为更改该设置可能会重写隐藏系统指令中的内容。

最新的配置更新决定后续响应的推理力度。例如，将此项追加到现有的 input 数组，即可让后续请求使用 high 推理力度：

要追加到 input 数组的项

1
2
3
4{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

如果许多请求复用相同的开发者指令和工具定义，但共享前缀未达到模型的最小可缓存长度，请考虑缩短前缀，或添加有用且稳定的指令、示例或参考资料来扩充它。请衡量缓存复用所节省的费用能否抵消额外输入 Token 和缓存写入产生的费用，并确保评估结果和行为保持稳定。

该图展示了最小可缓存长度带来的成本陷阱：较短的前缀无法缓存，其成本可能高于将前缀扩充至最小可缓存 Token 长度后的成本。

提示长度与输入成本

最小可缓存 Token 数每次写入后的完整缓存读取次数缓存读取费率倍数缓存写入费率倍数

500

1,000

1,500

2,000

可复用前缀长度（Token 数）

仅比较成本时，设 $M$ 为最短可缓存长度， $L < M$ 为原始前缀长度， $r$ 为缓存读取费率倍数， $w$ 为缓存写入费率倍数， $N$ 为请求总数。假设扩展后的前缀恰好包含 $M$ 个 Token，仅写入一次，且在此后的每次请求中都被完整复用。以未缓存输入 Token 的等效数量计，保留原始前缀的成本为 $N \times L$ ，而扩展前缀的成本为 $M \left[w + (N - 1)r\right]$ 。两种方案成本相等时的原始长度为：

L_{\mathrm{break\text{-}even}} = M\left(r + \frac{w-r}{N}\right)

扩展前缀的条件是 $L > L_{\mathrm{break\text{-}even}}$ ；保留较短前缀成本更低的条件是 $L < L_{\mathrm{break\text{-}even}}$ 。等号成立时，两种方案的成本相同。扩展后成本更低所需的最小整数 Token 长度为 $\left\lfloor L_{\mathrm{break\text{-}even}} \right\rfloor + 1$ 。反过来，如果将可缓存前缀缩短至低于 $M$ ，就无法使用缓存：在相同假设下，较短的未缓存前缀必须短于 $L_{\mathrm{break\text{-}even}}$ ，成本才会低于缓存 $M$ 个 Token 的成本。不存在一个普遍适用、成本最高的提示长度；成本交叉点取决于复用情况和定价。

例如，当 $M = 1{,}024$ 、 $r = 0.1$ 且 $w = 1.25$ 时，成本交叉点为 $102.4 + \frac{1{,}177.6}{N}$ 个 Token。在总共 10 次请求中，将长度至少为 221 个 Token 的原始前缀扩展到 1,024 个 Token，成本会更低。随着复用次数增加，成本交叉点趋近于 102.4 个 Token。长度为 103 个 Token 的前缀需要总共至少 1,963 次请求才能受益；在这些假设下，长度不超过 102 个 Token 的前缀始终无法受益。此比较不考虑性能、输出 Token 和保持不变的请求成本。额外的缓存未命中、写入或不同的模型费率都会改变结果。

衡量实际缓存性能。 跟踪 usage.input_tokens_details.cached_tokens、usage.input_tokens_details.cache_write_tokens、输入 Token 数、延迟和实际成本。按用户、工作空间、日期或其他有用的维度分别汇总缓存 Token 数和输入 Token 数，再将缓存 Token 总数除以输入 Token 总数，以跟踪 Token 缓存命中率。
计算输入成本。 使用 response.usage 中的 Token 数和模型的每百万 Token 价格进行计算。
使用提示缓存仪表板。 在提示缓存仪表板中监控缓存命中率。

计算输入成本

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18function 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;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def 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 及后续模型。

以单轮 LLM 评判器为例，它会判断一段已完成的用户与聊天机器人交互是否表明用户对这次交互感到满意。每个请求都使用相同的评分标准和带标签的少样本示例来评估不同的交互。

保留前缀： 将固定的评分标准和示例放在最前面。通过选用有助于校准评判器的材料，有意将两者的总长度保持在略高于模型最短可缓存长度的位置。待评估的交互放在最后。
缓存模式和断点： 启用仅显式缓存模式，并在固定的评分标准和示例之后设置断点。待评估的用户与聊天机器人的对话放在该断点之后，不写入缓存，从而避免为不太可能复用的内容支付缓存写入费用。

一个采用这些原则的部署示例报告了 约 70% 的 Token 缓存命中率。这个数字展示了一种可能的结果。实际缓存命中率的上限取决于您的上下文和应用使用情况。

单轮评判器的 Responses API 请求

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-5.6-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..."
    }
  ]
}

以使用较长的共享开发者指令并频繁调用工具的多轮智能体为例。在典型使用场景中，用户会同时与该智能体开展多个会话，并经常从对话中派生新对话。

保留前缀：每轮都追加新的消息、工具调用及结果，不改写之前的上下文，因此可复用前缀会随时间增长。
可选的提示缓存键： 此示例使用 agent_123_v1:user_456 为用户 456 单独核算缓存用量，让其缓存 Token 用量和计费更容易解释。这也有助于防止跨用户的缓存命中探测。在该用户与智能体的各个会话及派生对话中，此键保持不变。如果您的应用不需要这种隔离，可以省略此键。
隐式缓存模式： 启用隐式缓存，使最新的符合条件的用户消息或工具消息提供一个断点。
显式断点： 在每个工具结果之后添加断点，以保留之前的可复用前缀，提高派生对话时的缓存效率。

一个采用这些原则的部署示例报告了 Token 缓存命中率 >90%。这个数字展示了一种可能的结果。实际缓存命中率的上限取决于您的上下文和应用使用情况。

多轮智能体的 Responses API 请求

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
  "model": "gpt-5.6-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...?" }
  ]
}

常见陷阱

由于隐式缓存行为发生了变化，这种情况在从早期模型迁移到 GPT-5.6 或更高版本时尤为常见。如果多个请求共享较长的前缀，但后缀不同，仅通过隐式缓存将第一个完整请求写入缓存，并不能让其中较短的共享前缀得到复用。

假设每个请求都包含一条静态开发者消息，后接一条动态用户消息。该请求写入缓存的内容会一直涵盖到动态内容的末尾。如果下一个请求更改了动态内容，就无法匹配缓存中较长的前缀，而静态内容之后又没有单独的断点。

未在静态内容之后设置断点

1
2
3
4
5
6
7
8
9
10{
  "model": "gpt-5.6-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..." }
  ]
}

要解决此问题，请在两个请求的静态内容之后都设置一个显式断点。第一个请求将可复用的前缀写入缓存；即使动态内容发生变化，下一个请求也能复用该前缀。此示例使用仅显式模式，避免将动态内容写入缓存。

在静态内容之后设置断点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "model": "gpt-5.6-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 使用隐式模式，将截至某条用户消息末尾的前缀写入缓存，随后请求 2 保留该前缀，但切换为 prompt_cache_options.mode: "explicit"。如前缀匹配的工作原理所述，请求 2 仅检查自身输入中的显式断点，因此不会复用请求 1 隐式保存的前缀，除非请求 2 中的某个显式断点与请求 1 的缓存结束位置匹配。

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message] ▼

- Request 2: explicit-only mode. Does not hit cache.
  [Developer message][User message][Follow-up] ▼

要复用请求 1 隐式缓存的前缀，请在请求 2 中匹配的内容块边界处设置显式断点，或保持隐式模式启用，让之前符合条件的消息末尾仍然作为候选查找位置。

即使两个请求都使用隐式模式，仅保持开头的 Token 相同也不一定足够。假设请求 1 以一条包含 Content A 的用户消息结束，随后请求 2 将同一条消息扩展为 Content A + Content B。此时，Content A 之后的原结束位置位于消息内部，而不再是消息末尾。如前缀匹配的工作原理所述，如果该边界处没有显式断点，请求 2 就不会复用保存在该位置的前缀。

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message: Content A] ▼

- Request 2: implicit mode. Cannot reuse the prefix through Content A.
  [Developer message][User message: Content A + Content B] ▼

如果对话结构允许，请保留原消息并追加一条新消息。否则，请将可复用文本保留在单独的内容块中，并在两个请求中都于该内容块之后设置显式断点。

建议

开始使用

核心概念

SDK 与 CLI

资源

旧版 API

选择模型

文本与代码

提示词

推理

图像与视频

实时交互与音频

专用模型

智能体 API

智能体 SDK

ChatKit

搜索与检索

连接工具与数据

构建工具工作流

计算机与代码

媒体

GPT-Live

Realtime API

构建语音应用

连接

音频处理

上线

性能与质量

成本与吞吐量

安全与治理

基础设施与访问

运营

核心概念

Plan

Build

Test and publish

Conversion specs

指南

资源

开始使用

指南

File Upload

API

Measurement

Advertiser API

API 参考

开始使用

基础

探索

可用平台

发布

工作流

能力

参考资料

自定义

配置文件

智能体配置

扩展 ChatGPT 和 Codex 的功能

Linux

Windows

开发工作流

扩展并实现自动化

环境

使用 Codex 构建

第三方集成

参考资料

权限

Codex Security

网络安全

入门

ChatGPT Work

身份与身份验证

工作空间访问权限、策略和模型

插件和连接器控制

使用情况、治理与合规

部署和模型提供商

社区

博客

社区

博客