模型提示词通常包含重复性内容，例如系统提示词和通用指令。OpenAI 会将 API 请求路由到最近处理过相同提示词的服务器，这使其比从头开始处理提示词更便宜、更快速。Prompt 缓存最高可降低 80% 的延迟和 90% 的输入 Token 成本。Prompt 缓存会在您的所有 API 请求中自动生效（无需更改代码），并且不会产生任何额外费用。Prompt 缓存已对所有最新的 视觉, gpt-4o 及更新模型。
本指南详细介绍了 Prompt 缓存的工作原理，以便您优化提示词，从而降低延迟和成本。
构建提示词
缓存命中仅对提示词中完全一致的前缀匹配生效。为了获得缓存带来的益处，请将指令和示例等静态内容放置在提示词的开头，并将用户特定信息等可变内容放置在末尾。这也适用于图像和工具，它们在不同请求之间必须保持完全一致。
工作原理
对于长度达到或超过 1024 个 Token 的提示词，缓存会自动启用。当您发起 API 请求时，会发生以下步骤：
- 缓存路由:
- 请求会根据提示词初始前缀的哈希值被路由到相应的机器。该哈希值通常使用前 256 个 Token，尽管具体长度会因模型而异。
- 如果您提供了
prompt_cache_key参数，它将与前缀哈希值结合使用，从而允许您影响路由并提高缓存命中率。当许多请求共享较长的公共前缀时，这会特别有用。 - 如果针对相同前缀和
prompt_cache_key组合的请求超过一定速率（大约每分钟 15 个请求），部分请求可能会溢出并被路由到其他机器，从而降低缓存效果。
- 缓存查找: 系统会检查所选机器的缓存中是否存在提示词的初始部分（前缀）。
- 缓存命中: 如果找到匹配的前缀，系统将使用缓存结果。这能显著降低延迟并减少成本。
- 缓存未命中: 如果未找到匹配的前缀，系统将处理完整提示词，并在该机器上缓存其前缀以备未来请求使用。
提示缓存保留
提示缓存可以使用内存或扩展保留策略。如果可用，扩展提示缓存旨在将缓存保留更长时间，以便后续请求更有可能命中缓存。
两种保留策略的提示缓存定价相同。
要配置提示缓存保留策略，请在您的 prompt_cache_retention 请求上设置 Responses.create 参数（如果使用 Chat Completions，则设置 chat.completions.create （如果使用 Chat Completions）。
In-memory prompt cache retention
内存提示缓存保留适用于所有支持提示缓存的模型，除了 gpt-5.5, gpt-5.5-pro, 以及所有未来的模型。
使用内存策略时，缓存前缀在非活动状态下通常保持活跃 5 到 10 分钟，最长可达一小时。内存缓存前缀仅保存在易失性 GPU 内存中。
扩展提示缓存保留
以下模型支持扩展提示缓存保留：
- 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
扩展提示缓存保留可以将缓存前缀保持活跃更长时间，最长可达 24 小时。扩展提示缓存的工作原理是在内存已满时将 key/value 张量卸载到 GPU 本地存储，从而显著增加可用于缓存的存储容量。
key/value 张量是模型在预填充阶段由注意力层生成的中间表示。只有 key/value 张量可以持久保存在本地存储中；原始客户内容（例如提示文本）仅保留在内存中。
按请求配置
如果您未指定保留策略，大多数模型的默认值为 in_memory。对于 gpt-5.5, gpt-5.5-pro, 以及所有未来的模型，默认值为 24h and in_memory 不支持。允许的取值为 in_memory and 24h.
1
2
3
4
5
{
"model": "gpt-5.5",
"input": "Your prompt goes here...",
"prompt_cache_retention": "24h"
}要求
提示包含 1024 个或更多 token 时即可使用缓存。
所有请求（包括少于 1024 个 token 的请求）都将显示一个 cached_tokens 字段，位于 usage.prompt_tokens_details Response 对象 or Chat 对象 用于指示提示中有多少个 token 是缓存命中。对于少于 1024 个 token 的请求， cached_tokens 将为零。
1
2
3
4
5
6
7
8
9
10
11
12
13
"usage": {
"prompt_tokens": 2006,
"completion_tokens": 300,
"total_tokens": 2306,
"prompt_tokens_details": {
"cached_tokens": 1920
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
}哪些内容可以被缓存
- Messages: 完整的 messages 数组，包含系统、用户和助手交互。
- Images: 用户消息中包含的图像（无论是作为链接还是 base64 编码的数据），可以发送多张图像。请确保 detail 参数的设置保持一致，因为它会影响图像的 token 化。
- 工具使用： messages 数组和可用的列表均可
tools被缓存，并计入最低 1024 个 token 的要求。 - 结构化输出： 结构化输出架构用作系统消息的前缀，可以被缓存。
最佳实践
- 构建提示时，请在开头放置 静态或重复的内容 并在末尾放置动态的、特定于用户的内容。
- 使用
prompt_cache_key参数 在共享相同前缀的请求中保持一致。选择合适的粒度，使每个独特的前缀-prompt_cache_key组合每分钟的请求数保持在 15 次以下，以避免缓存溢出。 - 监控您的缓存性能指标, 包括缓存命中率、延迟和已缓存的 token 比例，以优化你的策略。你可以通过如上所示记录 usage 字段的结果，或者在 OpenAI Usage 仪表板中监控你的缓存 token 数量。
- 保持稳定的请求流 使用相同的提示前缀，以最大程度减少缓存逐出并最大化缓存收益。
常见问题
-
缓存如何维护数据隐私？
提示缓存在组织之间不共享。只有同一组织的成员才能访问相同提示的缓存。使用扩展提示缓存时，键/值张量的最长保留期限为 24 小时。
-
提示缓存会影响输出 token 的生成或 API 的最终响应吗？
提示缓存不会影响输出 token 的生成或 API 提供的最终响应。无论是否使用缓存，生成的输出都将完全相同。这是因为只有提示本身被缓存，而实际的响应每次都会基于缓存的提示重新计算。
-
有手动清除缓存的方法吗？
目前不支持手动清除缓存。近期未遇到的提示词会自动从缓存中清除。通常在非活动 5 到 10 分钟后会发生缓存清理，但在非高峰时段，最长可能会保留最多一小时。
-
写入 Prompt Caching 需要额外付费吗？
不需要。缓存会自动进行，无需执行任何明确操作，使用该缓存功能也不会产生额外费用。
-
缓存的提示词会占用 TPM 速率限制吗？
是的，因为缓存不影响速率限制。
-
Prompt Caching 适用于零数据保留请求吗？
内存中的缓存保留不会将任何数据保存到磁盘。扩展的提示词缓存可能会将键/值张量存储在 GPU 本地存储中，而这些键值张量派生自客户内容。这些数据在缓存过期后不会被保留——键值张量会保留 1 到 2 小时（适用于大多数使用场景），最长保留 24 小时。如果您的项目启用了零数据保留，扩展的提示词缓存请求不会被阻止。其他零数据保留政策依然适用，例如将客户内容排除在滥用日志之外，以及阻止使用
store=True。请参阅 您的数据 指南，以获取有关零数据保留的更多背景信息。 -
Prompt Caching 适用于数据驻留吗？
内存中的 Prompt Caching 不存储数据，因此不会影响数据驻留。
扩展缓存会临时将数据存储在 GPU 机器上，并且在使用区域推理时，数据只会保留在该区域内。