当多个请求具有相同的提示词前缀时,提示词缓存可以复用已有的计算结果。这主要有三个好处。
- 节省算力。 无需重新计算模型已经处理过的提示词前缀。
- 降低输入 Token 费用。 复用的 Token 按模型较低的缓存输入费率计费,最高可节省 95%。
- 加快响应。 缩短模型开始响应前处理输入的时间。
支持提示词缓存的 OpenAI 模型默认启用此功能。您可以在提示词缓存仪表板中监控缓存读取命中率,也可以使用提示词缓存诊断工具排查缓存未命中的原因,提高缓存复用率。
通过 Agents API 调用模型时,提示词缓存的工作方式与 Responses API 相同。在会话中复用上下文有助于保留共享的提示词前缀,但维持同一会话并不能保证缓存命中。有关会话用量字段和子智能体用量统计,请参阅可观测性与用量。
提示词缓存的价格因模型而异。有关当前的缓存输入费率和缓存写入费率,请参阅 API 定价。每个输入 Token 只按未缓存输入、缓存输入或缓存写入三种费率之一计费。
模型处理输入 Token 时,必须计算称为键值(KV)状态的中间状态。有了这些状态,模型在处理新输入和生成输出 Token 时就能参考之前的 Token。
提示词缓存会为可复用的前缀保存这些状态。前缀是指提示词开头保持不变的一段 Token。如果后续请求具有相同的前缀,并且找到了匹配的缓存条目,模型就能复用已保存的状态,省去重复处理这些 Token 的步骤。模型仍需处理新输入才能生成新的响应。
提示词缓存存储键值(KV)张量,不存储 Token 本身。
让 ChatGPT 进一步解释
Step 1
tiny chips
↓
↓
Generates power Step 2
tiny chips power
↓
↓
Generates big Step 3
tiny chips power big
↓
↓
Generates ideas
在模型渲染后的上下文中,符合缓存条件的前缀可以包含 OpenAI 提供的指令、开发者消息、工具定义和对话历史记录。对话历史记录可以包含文本、图像、文档和受支持的音频。
要复用缓存,渲染后的整个前缀都必须匹配。如果断点之前的内容或相关设置发生变化,包含该变化的前缀就无法与现有缓存条目匹配。
上下文历史记录
对话消息、工具调用及其结果、文本和多模态内容
更改请求后,现有缓存条目可能仍然有效。能否复用取决于后续请求是否具有相同的前缀,以及能否找到符合条件的匹配断点。请重点检查以下设置。
缓存断点标记提示词前缀的结束位置。OpenAI 可以将截至该位置的前缀保存到缓存中,供后续请求复用。第一个请求将符合条件的前缀写入缓存。后续请求会从后往前逐个检查符合条件的断点,直到找到可用的最长匹配缓存前缀。
提示词前缀的 Token 数必须达到模型的最小可缓存长度,才能写入缓存。OpenAI 提供的隐藏系统内容中的 Token 不计入这一门槛。对于 GPT-5.6 及后续模型,提示词的最小可缓存长度为 1,024 个 Token。对于更早的模型,该长度因请求设置而异。详情请参阅模型对比。
达到最小可缓存 Token 数后,您可以显式指定缓存断点的位置,也可以让 OpenAI 隐式选择。可用选项取决于模型。
对于 GPT-5.6 及后续模型,在默认的 30 分钟有效期下,缓存写入费率为标准未缓存输入 Token 费率的 1.25 倍。在 Responses API 中,您可以选择最短有效期为 12 小时,写入费率为普通输入费率的 2.5 倍。无论选择哪种有效期,大多数此类模型的后续读取费率均为普通输入费率的 0.1 倍,GPT-6.2 Astra、GPT-6.2 Sol、GPT-6.1 Sol 和 GPT-6.1 Terra 的读取费率则为 0.05 倍。
按 0.1 倍的读取费率和 30 分钟的写入有效期计算,将前缀写入一次并完整复用一次,费用为该前缀普通输入费用的 1.35 倍,不使用缓存处理两次则为 2 倍。按同一费率计算,10 次请求中写入一次、完整读取 9 次的费用为 2.15 倍,不使用缓存则为 10 倍。
这些模型同时支持隐式缓存和显式缓存。使用显式缓存时,您可以更精确地控制哪些上下文会写入缓存。
显式模式。 您可以根据上下文的管理方式选择缓存断点的位置。
- 将
prompt_cache_options.mode 设为 explicit 即可仅使用开发者指定的断点。在输入消息内受支持的内容块上添加 prompt_cache_breakpoint: { "mode": "explicit" },标记每个所需断点。
- 在仅显式模式下,如果没有设置显式断点,请求就不会使用提示词缓存,也不会写入缓存。
- 仅显式模式允许您指定缓存写入的结束位置。最后一个选定断点之后的内容按未缓存输入 Token 费率处理,不收取缓存写入费用。这样可以避免将经常变化且不太可能复用的内容写入缓存。
- 使用多个显式断点可以保留变化频率不同的前缀。每个请求最多可以写入缓存 4 次。
additional_tools 输入项目前不接受 prompt_cache_breakpoint。
顶层 instructions 不能包含显式断点。要标记可复用的开发者指令,请将其放在开发者消息的 input_text 块中。
隐式模式。 OpenAI 会自动选择适合大多数使用场景的断点位置。
- 当
prompt_cache_options.mode 为 implicit 时,OpenAI 会在最近一条符合条件的消息末尾设置断点。以下消息符合条件。
- 用户消息
- 一组连续工具响应中的最后一个工具响应
- 开头一组连续开发者消息中的最后一条开发者消息
- 您可以在保留隐式断点的同时添加显式断点。隐式断点会占用 4 个缓存写入名额中的 1 个,其余 3 个可用于显式写入。
这些模型仅支持隐式缓存。OpenAI 从隐藏的 OpenAI 系统消息开头起,按各模型对应的间隔设置隐式断点。最小可缓存长度从隐藏上下文末尾开始计算,只有达到或超过这一长度的断点才符合条件。
计算返回的 cached_tokens 时,先从截至最后一个匹配断点的 Token 数中减去隐藏系统 Token 数,再向下取整到最接近的 128 的倍数。
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 · 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
39import 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 请求
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
42
43
44
45
46
47
48import 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 · 响应中的用量信息
1
2
3
4
5
6
7
8
9{
"usage": {
"input_tokens": 12000,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 12000
}
}
}
请求 2 · 响应中的用量信息
1
2
3
4
5
6
7
8
9{
"usage": {
"input_tokens": 15000,
"input_tokens_details": {
"cached_tokens": 12000,
"cache_write_tokens": 3000
}
}
}
缓存条目的保留时间有限。缓存的最短有效期、保留设置,以及请求复用前缀时的行为均取决于模型。
在 Responses API 中,通过 prompt_cache_options.ttl 选择缓存的最短有效期。
| 值 |
最短有效期 |
缓存写入费率 |
适用场景 |
"30m"(默认) |
30 分钟 |
未缓存输入 Token 费率的 1.25 倍 |
频繁复用上下文的对话和智能体步骤。 |
"12h" |
12 小时 |
未缓存输入 Token 费率的 2.5 倍 |
间隔较长时间仍会复用的固定指令或参考资料。 |
表中列出的是写入的完整费率,已包含输入费用。两种有效期的缓存读取费率相同。OpenAI 保留条目的时间可能超过请求指定的最短有效期。"12h" 不会设定删除期限,也不会更改关于最长数据保留期限的政策。
请求级别的 ttl 适用于隐式断点以及未单独指定 ttl 的显式断点。您可以设置 prompt_cache_breakpoint.ttl,为某个显式断点覆盖请求级别的设置。如果两项设置都省略,则使用默认值 "30m"。使用不支持的值会返回 400 invalid_request_error。这些设置不会改变较早模型的 prompt_cache_retention 参数。
在同一请求中使用不同的有效期
将一天中反复使用的资料放在提示词开头,并将对应断点的有效期设为 "12h"。对于变化更频繁的会话上下文,请使用 "30m"。以下示例将请求的默认有效期设为 30 分钟,并为共享前缀单独设置有效期。此示例使用仅显式模式,并将当前问题放在最后一个断点之后,因此这部分内容不会产生缓存写入费用。
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{
"model": "gpt-6.2-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..."
}
]
}
]
}
请将占位文本替换为您的内容。您要缓存的每个前缀都必须达到模型的最小可缓存长度。
写入范围重叠和有效期变更
一个断点覆盖其之前的整个前缀。在同一请求中,每个 Token 只计费一次,按覆盖该 Token 的选定写入操作中最长的有效期计费。如果靠后的断点按 12 小时有效期写入,那么该前缀中较早的选定断点也会获得 12 小时的缓存覆盖。
以下示例假设已有的缓存前缀与新请求中符合条件的查找边界匹配。
| 请求前的缓存状态 |
选定断点 |
按读取计费的 Token 数 |
按 30 分钟写入计费的 Token 数 |
按 12 小时写入计费的 Token 数 |
| 无缓存前缀 |
"12h" 设在第 2,000 个 Token 处,"30m" 设在第 5,000 个 Token 处 |
0 |
3,000 |
2,000 |
| 无缓存前缀 |
"30m" 设在第 2,000 个 Token 处,"12h" 设在第 5,000 个 Token 处 |
0 |
0 |
5,000 |
| 前 2,000 个 Token 的 30 分钟缓存仍有效 |
"12h" 设在第 5,000 个 Token 处 |
0 |
0 |
5,000 |
| 前 2,000 个 Token 的 12 小时缓存仍有效 |
"30m" 设在第 5,000 个 Token 处 |
2,000 |
3,000 |
0 |
将仍有效的 30 分钟缓存升级为 12 小时缓存时,相关 Token 会按新的 12 小时写入计费,之前的写入费用不能抵扣。已由有效的 12 小时缓存条目覆盖的部分仍按缓存读取计费。
按 30 分钟有效期读取时,缓存有效期会刷新至读取后至少 30 分钟。如果读取的条目仍在 12 小时有效期内,刷新后的到期时间取原到期时间和读取后 30 分钟两者中的较晚者。读取不会重新开始计算 12 小时有效期,也不会再次产生写入费用。
最短有效期决定哪些 Token 可以按缓存读取费率计费,但并不保证每个请求都会复用存储的 KV 张量或获得更低的延迟。
使用 prompt_cache_retention 设置保留时间。支持的值因模型而异。
in_memory:条目在闲置后通常还能使用约 5 到 10 分钟,最长可达 1 小时。
24h:使用延长保留时,条目通常可用约 30 分钟,最长可保留 24 小时。
默认保留设置与零数据保留
提示词缓存可能会将加密的键值张量作为应用状态存储在 GPU 本地存储中。对于同时支持 in_memory 和 24h 的模型,默认值取决于您组织的数据保留政策。
- 如果组织 未启用 零数据保留,默认使用
24h。
- 如果组织 已启用 零数据保留,默认使用
in_memory。
选择参数值前,请确认您的模型和组织可使用哪些保留政策。
缓存状态存储在各台机器上。流量超过每分钟 15 个请求时,部分请求可能被分流到其他机器。只有当请求到达的机器上存在匹配且未过期的缓存条目时,才能复用缓存前缀。因此,将请求路由到合适的机器对于复用缓存很重要。
OpenAI 会自动处理路由。在同一组织和处理区域内,特定模型的请求路由取决于以下因素。
- 机器当前的负载和可用容量。
- OpenAI 提供的隐藏内容之后一段起始 Token 的哈希值。如果有工具定义,也会包含在内。参与哈希计算的 Token 数因模型而异。
- 请求中提供的
prompt_cache_key。它将缓存复用限制在各自的请求组内,在 GPT-5.6 之前的模型上还有助于优化缓存路由。
在 GPT-5.6 之前的模型上,请为具有相同可复用前缀的请求使用稳定的 prompt_cache_key,以便将相关请求路由到同一缓存。对于请求频繁的组,尽量将使用同一个键的所有前缀的总流量控制在每分钟约 15 个请求。流量更高时,请采用稳定、确定的映射规则,将流量分配到多个键。相关请求应使用相同的 prompt_cache_key,以便复用其缓存。键会影响路由,但不会将请求固定到某台机器,也不能保证缓存命中。
在 GPT-5.6 及后续模型上,OpenAI 会自动处理缓存路由,优化缓存无需指定键。您可以使用不同的键,为应用中的各个客户或用户分别统计缓存用量。
使用不同的键,有助于向每位客户或用户解释其缓存 Token 用量和费用。例如,使用不同的键有助于防止用户探测其他用户的缓存命中情况,即通过提交候选提示词并观察缓存是否命中,推断匹配的内容是否曾被缓存。请参阅使用键分别统计缓存用量。
| 行为 |
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 帮我优化提示词缓存
在多轮对话应用中,复用不断增长的对话历史记录,可以比只缓存初始指令节省更多输入 Token。请保留之前的消息和工具结果,以便后续轮次复用完整的共享前缀。
- 保持前缀稳定。 将稳定的开发者指令和共享参考资料放在开头。如果开发者指令或共享资料包含时间戳、用户专属内容或其他动态内容,请将这些内容放在末尾,或移至后续的对话消息中。
- 保留对话历史记录。 追加新消息,避免改写之前的对话。生成摘要、压缩或截断上下文都可能改变前缀,导致缓存复用需要重新开始。
- 调整推理强度,同时保留原有前缀。 在支持此功能的模型上,追加一个
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-6.2-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 及后续模型上,您可以追加一个 configuration_update 输入项,在对话过程中调整推理强度,同时保留之前缓存的前缀。请将顶层 reasoning.effort 保持为原值,因为更改该设置可能会改写隐藏系统指令中的内容。
后续响应的推理强度取决于最近一次对 reasoning.effort 的更新。将以下输入项追加到 input,即可将推理强度切换为 high。
1
2
3
4{
"type": "configuration_update",
"reasoning": { "effort": "high" }
}
在 GPT-5.6 及后续模型上,prompt_cache_options.mode 用于选择隐式缓存或仅显式缓存,prompt_cache_breakpoint 用于标记您指定的边界。两项设置共同决定缓存断点的位置。
- 自动设置断点。 使用隐式缓存即可在最近一条符合条件的消息末尾设置断点。这适用于在现有上下文后追加内容的多轮对话线程。
- 手动选择断点。 在稳定内容的末尾设置显式断点。使用仅显式模式,避免将经常变化的后缀无谓地写入缓存。
Shared cached prefix for breakpoint 2
Hidden system message
Tools
Developer message · stable prefix
Developer message · variable suffix A
User message
Tool call
Tool result
Assistant message
Developer message · variable suffix B
New user input A
New user input B
Breakpoint 1
Breakpoint 2
Shared cached prefix for breakpoint 1
Unreused suffix: no cache-write charge
New user inputs: no cache-write charge
在 GPT-5.6 及后续模型上,提前准备好已知的上下文可以缩短后续请求等待首个 Token 的时间。例如,交互式应用可以在启动时预热共享指令、工具定义或参考资料,此时用户还未提出第一个问题。
在 Responses API 请求中将 prompt_cache_options.prewarm 设为 true,即可在不生成输出的情况下预热提示词缓存。预热完成后,使用相同的提示词前缀发送实际请求,并省略 prewarm 或将其设为 false。
1
2
3
4
5
6
7
8
9
10
11
12{
"model": "gpt-6.2-sol",
"input": [
{
"role": "developer",
"content": "Your app's shared instructions and reference material..."
}
],
"prompt_cache_options": {
"prewarm": true
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13{
"model": "gpt-6.2-sol",
"input": [
{
"role": "developer",
"content": "Your app's shared instructions and reference material..."
},
{
"role": "user",
"content": "The user's question..."
}
]
}
预热请求写入缓存的 Token 按所选有效期的缓存写入费率计费。
在 GPT-5.6 及后续模型上,如果希望为应用中的各个客户、用户或工作空间分别统计缓存用量,请使用 prompt_cache_key。这样更容易解释各组的缓存 Token 用量和费用。此键是可选的,在这些模型上优化缓存无需指定键。
- 选择分别统计缓存用量的方式。 为需要单独统计缓存用量的每个客户或用户分配唯一的键。例如,使用
support:customer_123 和 support:customer_456 可以分别统计两个客户的缓存用量,即使他们的请求包含相同的前缀。
- 在每个组内保持键稳定。 对同一客户的相关请求使用相同的键。只有当会话或线程需要单独统计缓存用量时,才为其生成单独的键。
- 一致地使用键。 在客户的所有请求中使用该客户的键,以便分别统计缓存用量。这也有助于防止客户探测其他客户的缓存命中情况。
在 GPT-5.6 之前的模型上,prompt_cache_key 对优化缓存命中率很重要。请为具有相同可复用前缀的请求使用稳定的键,以便将它们路由到同一缓存。对于请求频繁的组,请遵循将流量分配到更多键的指南。
- 保留现有的稳定前缀。
- 如果使用了
prompt_cache_key,请保留现有值,以便继续为各个客户或用户分别统计缓存用量。
- 将
prompt_cache_retention 替换为 prompt_cache_options.ttl。
- 确认可复用前缀达到模型的最小可缓存长度。
- 如果默认断点覆盖的内容会随请求变化,请在稳定前缀后添加显式断点。
- 如果后续内容不值得写入缓存,请使用
prompt_cache_options.mode: "explicit"。
- 比较迁移前后的
cached_tokens、cache_write_tokens、延迟和总成本。
以下示例适用于 GPT-5.6 及后续模型。
假设您使用 LLM 进行单轮评判,判断一段已结束的对话中是否有迹象表明用户对与聊天机器人的互动感到满意。每个请求使用相同的评分标准和带标签的少样本示例,评估不同的对话。
- 保留前缀。 将固定的评分标准和示例放在开头。选择有助于校准评判结果的材料,使两者的总长度略高于模型的最小可缓存长度。将待评估的对话放在最后。
- 缓存模式和断点。 启用仅显式缓存,并在固定的评分标准和示例之后设置断点。将待评估的用户与聊天机器人的对话放在该断点之后,使其不会写入缓存,从而避免为不太可能复用的内容支付缓存写入费用。
某个采用上述做法的部署报告称,其 Token 缓存命中率约为 70%。这只是可能的结果之一。实际可达到的缓存命中率上限取决于您的上下文和应用使用情况。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
"model": "gpt-6.2-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%。这只是可能的结果之一。实际可达到的缓存命中率上限取决于您的上下文和应用使用情况。
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-6.2-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-6.2-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-6.2-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 只检查其自身输入中的显式断点。因此,只有当请求 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] ▼
如果对话结构允许,请保留原消息并追加一条新消息。否则,请将可复用文本放在单独的内容块中,并在两个请求中都将显式断点设在该块之后。
在隐式模式下,开头一组连续开发者消息之后出现的开发者消息不会自动形成缓存查找边界。请在可复用的开发者消息末尾添加显式断点,并在后续请求中保留该断点,以便 OpenAI 查找匹配的缓存前缀。
在一个模型上符合缓存条件的前缀,在另一个模型上可能太短。请查看模型对比,并使用您实际采用的模型和设置测量可复用前缀的长度。更换模型时,请根据新模型的门槛重新检查。
压缩会用更短的表示形式替换之前的对话上下文。这可能改变前缀,因此即使对话在逻辑上没有变化,压缩后的第一个请求能够复用的已有缓存也可能减少。
请尽可能保持可复用的指令和参考资料稳定,再让后续对话在压缩后的上下文基础上继续。请比较压缩前后的总输入成本。即使缓存命中率下降,减少输入 Token 仍可能节省费用。
不会。提示词缓存不会改变模型生成输出 Token 的方式。模型会使用缓存前缀生成新的响应,因此相同的请求不一定会产生相同的输出。
不可以。目前不支持手动清除缓存。缓存条目会根据模型的缓存有效期和保留设置到期。
会。缓存输入 Token 仍会计入每分钟 Token 数限制。提示词缓存不会改变速率限制的计算方式。
所有提示词缓存功能均兼容零数据保留(ZDR)。
提示词缓存只存储键值(KV)张量,不存储提示词原文。这些张量可能作为加密的应用状态保存在 GPU 本地存储中,最长保留 24 小时。有关各模型的缓存有效期和刷新机制,请参阅缓存有效期。
不同组织之间不共享缓存,缓存也不能跨区域处理边界复用。有关各项 API 功能如何处理数据以及是否符合零数据保留条件的详细信息,请参阅您的数据。