提示词缓存

模型提示词通常包含重复内容，例如系统提示词和常用指令。OpenAI 会将 API 请求路由到最近处理过相同提示词的服务器，使其比从零开始处理提示词更便宜、更快速。提示词缓存可将延迟降低高达 80%，并将输入 Token 成本降低高达 90%。提示词缓存会在您的所有 API 请求中自动生效（无需更改代码），且无需额外费用。提示词缓存已为所有近期的 模型（gpt-4o 及更新版本）启用。

本指南详细介绍了提示词缓存的工作原理，以便您可以优化提示词以实现更低的延迟和成本。

构建提示词

只有提示词的精确前缀匹配时才能触发缓存命中。为了实现缓存收益，请将指令和示例等静态内容放在提示词的开头，将用户特定信息等可变内容放在结尾。这也适用于图片和工具，它们在不同请求之间必须保持一致。

它是如何工作的

对于长度为 1024 个 Token 或更长的提示词，系统会自动启用缓存。当您发出 API 请求时，会发生以下步骤：

1. 缓存路由:

• 请求会根据提示词初始前缀的哈希值路由到特定机器。哈希通常使用前 256 个 Token，具体长度取决于模型。
• 如果您提供 prompt_cache_key 参数，它将与前缀哈希相结合，从而允许您影响路由并提高缓存命中率。当许多请求共享较长的公共前缀时，此功能特别有用。
• 如果针对相同前缀和 prompt_cache_key 组合的请求超过了一定速率（每分钟约 15 次请求），则部分请求可能会溢出并路由到其他机器，从而降低缓存效率。

2. 缓存查找：系统会检查您的提示词初始部分（前缀）是否存在于所选机器的缓存中。
3. 缓存命中：如果找到匹配的前缀，系统将使用缓存的结果。这会显著降低延迟并节省成本。
4. 缓存未命中：如果未找到匹配的前缀，系统将处理您的完整提示词，并在稍后将该前缀缓存在该机器上，以供将来请求使用。

提示词缓存保留机制

提示词缓存可以使用内存内保留策略或扩展保留策略。在可用时，扩展提示词缓存旨在更长时间地保留缓存，以便后续请求更有可能匹配到缓存。

两种保留策略的提示词缓存定价相同。

要配置提示词缓存保留策略，请在您的 Responses.create 请求（如果使用 Chat Completions，则为 chat.completions.create）中设置 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 本地存储中，从而显著增加可用于缓存的存储容量。

键/值张量是模型预填充 (prefill) 阶段生成的注意力层的中间表示。只有键/值张量可以持久存储在本地存储中；原始用户内容（如提示词文本）仅保留在内存中。

按请求配置

如果您未指定保留策略，大多数模型的默认值为 in_memory。对于 gpt-5.5、gpt-5.5-pro 及所有未来模型，默认值为 24h，且不支持 in_memory。允许的值为 in_memory 和 24h。

1
2
3
4
5
{
  "model": "gpt-5.5",
  "input": "Your prompt goes here...",
  "prompt_cache_retention": "24h"
}

要求

缓存适用于包含 1024 个 Token 或更多的提示词。

所有请求（包括少于 1024 个 Token 的请求）都会在 Response 对象 或 Chat 对象 的 usage.prompt_tokens_details 字段中显示 cached_tokens，指示提示词中有多少 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
  }
}

可缓存的内容

• 消息： 完整的消息数组，包含系统、用户和助手的交互内容。
• 图片： 用户消息中包含的图片（可以是链接或 Base64 编码数据），也可以发送多张图片。请确保 detail 参数设置一致，因为它会影响图片的分词方式。
• 工具使用： 消息数组和可用的 tools 列表均可缓存，有助于达到 1024 个 Token 的最低要求。
• 结构化输出： 结构化输出模式可作为系统消息的前缀并进行缓存。

最佳实践

• 构建提示词时，将静态或重复的内容放在开头，将动态的用户特定内容放在结尾。
• 在共享公共前缀的请求中始终使用 prompt_cache_key 参数。选择合适的粒度，确保每个唯一的前缀-prompt_cache_key 组合每分钟请求数低于 15 次，以避免缓存溢出。
• 监控您的缓存性能指标，包括缓存命中率、延迟和缓存 Token 的比例，以优化您的策略。您可以通过记录上述 usage 字段结果，或在 OpenAI 使用情况仪表板中监控缓存的 Token 数量。
• 保持请求流稳定，使用相同的提示词前缀，以最大程度减少缓存逐出并最大化缓存收益。

常见问题解答

1. 如何确保缓存的数据隐私？

   提示词缓存不会在不同组织之间共享。只有同一组织的成员才能访问相同提示词的缓存。使用扩展提示词缓存时，键/值张量的最长保留期限为 24 小时。

2. 提示词缓存会影响 API 的输出 Token 生成或最终响应吗？

   提示词缓存不会影响 API 生成的输出 Token 或最终响应。无论是否使用缓存，生成的输出都将是相同的。这是因为缓存的仅是提示词本身，而实际的响应每次都是基于缓存的提示词重新计算的。

3. 是否有办法手动清除缓存？

   目前不支持手动清除缓存。最近未被访问的提示词会自动从缓存中清除。典型的缓存逐出发生在 5-10 分钟不活动之后，尽管在非高峰时段有时最长可达一小时。

4. 使用提示词缓存写入数据需要额外付费吗？

   不需要。缓存是自动完成的，无需执行显式操作，也不需要为使用缓存功能支付额外费用。

5. 缓存的提示词会影响 TPM（每分钟 Token 数）速率限制吗？

   是的，缓存不会影响速率限制。

6. 提示词缓存适用于“零数据保留”(Zero Data Retention) 请求吗？

   内存内缓存保留不会将任何数据保存到磁盘。扩展提示词缓存可能会将键/值张量存储在 GPU 本地存储中，键/值张量派生自客户内容。此数据不会在缓存过期后保留——键/值张量会保留 1-2 小时（大多数情况下），最长不超过 24 小时。如果为您的项目启用了“零数据保留”，扩展提示词缓存请求不会被阻止。其他“零数据保留”政策仍然适用，例如将客户内容排除在滥用日志之外，并防止使用 store=True。有关“零数据保留”的更多背景信息，请参阅 您的数据 指南。

7. 提示词缓存适用于数据驻留 (Data Residency) 吗？

   内存内提示词缓存不存储数据，因此不影响数据驻留。

   扩展缓存会将数据临时存储在 GPU 机器上，仅在使用区域推理 (Regional Inference) 时才会将数据保留在区域内。