提示缓存

模型提示通常包含重复内容，例如系统提示和通用说明。OpenAI 将 API 请求路由到最近处理相同提示的服务器，这比从头开始处理提示更便宜、更快捷。这可以将长提示的延迟降低多达 80%，成本降低 50%。Prompt Caching 会自动处理您的所有 API 请求（无需更改代码），并且不会产生与之相关的额外费用。

为以下模型启用了提示缓存：

本指南详细介绍了 Prompt Caching 的工作原理，以便您可以优化 Prompt，以降低延迟和成本。

缓存命中仅适用于提示中的精确前缀匹配。要实现缓存优势，请将静态内容（如说明和示例）放在提示的开头，并将变量内容（如用户特定信息）放在末尾。这也适用于图像和工具，它们在请求之间必须相同。

将自动为具有 1024 个令牌或更长的提示启用缓存。当您发出 API 请求时，将执行以下步骤：

1. Cache Lookup：系统检查提示的初始部分（前缀）是否存储在缓存中。
2. 缓存命中：如果找到匹配的前缀，系统将使用缓存的结果。这显著降低了延迟并降低了成本。
3. 缓存未命中：如果未找到匹配的前缀，系统将处理您的完整提示。处理后，将缓存提示的前缀以供将来请求使用。

缓存的前缀通常会在 5 到 10 分钟的非活动状态内保持活动状态。但是，在非高峰时段，缓存可能会持续长达一小时。

缓存可用于包含 1024 个或更多令牌的提示，缓存命中以 128 个令牌为增量发生。因此，请求中缓存的令牌数量将始终按以下顺序排列：1024、1152、1280、1408 等，具体取决于提示的长度。

所有请求（包括令牌数少于 1024 个的请求）都将显示聊天完成对象的一个字段，指示缓存命中了多少个提示令牌。对于低于 1024 个令牌的请求，将为零。cached_tokensusage.prompt_tokens_detailscached_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 参数设置相同，因为它会影响图像分词化。
• 工具使用：messages 数组和 available 列表都可以缓存，从而有助于满足最低 1024 个令牌要求。tools
• 结构化输出：结构化输出架构用作系统消息的前缀，可以缓存。

• 结构提示，开头为静态或重复内容，结尾为动态内容。
• 监控缓存命中率、延迟和缓存的令牌百分比等指标，以优化您的提示和缓存策略。
• 要增加缓存命中率，请使用更长的提示并在非高峰时段发出 API 请求，因为高峰时段缓存驱逐会更频繁。
• 最近未使用的提示将自动从缓存中删除。为了最大限度地减少驱逐，请保持具有相同提示前缀的一致请求流。

1. 如何维护缓存的数据隐私？

   提示缓存不会在组织之间共享。只有同一组织的成员才能访问相同提示的缓存。

2. 提示缓存是否会影响输出令牌生成或 API 的最终响应？

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

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

   手动缓存清除当前不可用。最近未遇到的提示将自动从缓存中清除。典型的缓存驱逐发生在 5-10 分钟处于非活动状态后，但在非高峰时段，有时最多持续 1 小时。

4. 我是否需要为写入 Prompt Caching 支付额外费用？

   不。缓存会自动进行，无需显式操作或支付额外费用即可使用缓存功能。

5. 缓存的提示是否会影响 TPM 速率限制？

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

6. Scale Tier 和 Batch API 是否提供提示缓存的折扣？

   提示缓存的折扣在 Batch API 上不可用，但在 Scale Tier 上可用。使用 Scale Tier，溢出到共享 API 的任何令牌也将符合缓存条件。

7. 提示缓存是否适用于零数据保留请求？

   是的，Prompt Caching 符合现有的零数据保留策略。