Skip to main content

快速开始

以下是使用 cache_control 块在 Anthropic 兼容API 中实现 prompt 缓存的快速示例:
JSON
在此示例中,《傲慢与偏见》的完整文本使用 cache_control 参数进行缓存。这使得大文本可以在多次 API 调用中复用而无需每次都重新处理。通过仅更改用户消息,您可以提出关于该书的各种问题,同时利用缓存的内容,从而获得更快的响应并降低成本。

Prompt 缓存的工作原理

当您发送启用了 prompt 缓存的请求时:
  1. 系统检查指定缓存断点 (cache_control) 之前的 prompt 前缀是否已被此前的请求缓存;
  2. 如果找到,它将使用缓存版本,显著减少处理时间和成本;
  3. 如果未找到,它将处理完整的 prompt 并在生成响应时对其进行缓存。
这在以下场景的使用中特别有用:
  • 包含许多示例的 prompt
  • 大量上下文或背景信息
  • 具有一致指令的重复任务
  • 长时间的多轮对话
缓存内容的生命周期为 5 分钟。每次命中缓存内容时,缓存生命周期都会自动刷新,无需额外费用。

支持的模型和定价

Prompt 缓存引入了差异化的定价结构。下表显示了每个支持模型的百万 token 价格:
上表反映了以下 prompt 缓存定价规则:
  • 缓存写入与缓存读取 token 价格以上表为准

如何实现 Prompt 缓存

构建 prompt

将静态可复用的内容(工具定义、系统指令、示例等)放在 prompt 的开头。使用 cache_control 参数标记可缓存内容的结束位置。 缓存前缀按以下顺序创建:toolssystemmessages。此顺序形成一个层次结构,其中每个级别都建立在前一个级别之上。

自动前缀检查

您可以在静态内容的末尾只使用一个缓存断点,系统将自动找到最长的匹配前缀。 三个核心原则:
  1. 缓存内容是累积的:当您使用 cache_control 标记一个块时,缓存内容是从所有先前的块按顺序生成的。这意味着每个缓存都依赖于它之前的所有内容。
  2. 向前顺序检查:系统通过从显式 Cache 断点向前来检查缓存命中,这确保了尽量命中最长的缓存。
  3. 20 块回溯窗口:系统在每个显式 Cache 断点之前最多检查 20 个块。如果检查 20 个块后未找到匹配项,将停止检查并移至上一个显式断点(如果有)。
举例: 如果在第30个块设置了 cache_control, 重复进行请求:
  1. 若无任何块的内容被修改,则系统能命中 1~30 块所有内容的缓存;
  2. 若第 25 个块内容被修改,则系统从第 30 块往前找,直到第 24 块可以匹配缓存,那么 1~24 块内容将会命中缓存;
  3. 若第 5 个块内容被修改,则系统从第 30 块往前找,找到第 11 块仍未匹配缓存,本次缓存失效;

可被缓存的内容

请求中的大多数块都可以使用 cache_control 指定进行缓存,包括:
  • 工具tools 数组中的工具定义
  • 系统消息system 数组中的内容块
  • 文本消息messages.content 数组中的内容块,适用 user 和 assistant 的轮次
  • 工具使用和工具结果messages.content 数组中的内容块中的 tool_use 和 tool_result 类型,适用 user 和 assistant 的轮次
使用 cache_control 标记任何这些元素以启用该部分请求的缓存。

缓存失效

对缓存内容的修改可能会使部分或全部缓存失效。 构建 prompt 中所述,缓存遵循层次结构:toolssystemmessages。每个级别的更改都会使该级别及所有后续级别失效。

缓存性能

使用 usage 对象中的以下 API 响应字段监控缓存性能(或在流式传输)时的 message_start 事件中):
  • cache_creation_input_tokens:创建新缓存条目时写入缓存的 token 数量。
  • cache_read_input_tokens:此请求从缓存中检索的 token 数量。
  • input_tokens:未从缓存读取或用于创建缓存的输入 token 数量(即最后一个缓存断点之后的 token)。
了解 token 构成计算总输入 token:
按位置分解:
  • cache_read_input_tokens:断点之前的 token,已缓存(读取)
  • cache_creation_input_tokens:断点之前的 token,正在缓存(写入)
  • input_tokens:最后一个断点之后的 token(不符合缓存条件)
示例: 一个包含 100,000 个已缓存内容 token(从缓存读取)、0 个正在缓存的新内容 token 和 50 个用户消息 token(缓存断点之后)的请求:
  • cache_read_input_tokens:100,000
  • cache_creation_input_tokens:0
  • input_tokens:50
  • 总输入 token:100,050 个 token
这对于理解成本和速率限制都很重要。有效使用缓存时,input_tokens 通常会比您的总输入小得多。

常见问题

如果您遇到不符合预期的缓存行为:
  • 内容一致性:验证缓存部分在多次调用中是相同的,并且在相同位置使用 cache_control 标记
  • 缓存过期时间:确认调用在缓存生命周期内进行(5 分钟)
  • 块数量的限制:若一次调用有超过 20 个内容块的 prompt,可添加额外的 cache_control 参数以确保所有内容都可以被缓存(系统自动检查每个断点之前的约 20 个块)
  • 未生效的缓存断点:一次调用最多支持 4 个 cache_control 参数,若超过 4 个,只取从后向前最近的 4 个

更多示例

以下代码示例展示了各种 prompt 缓存模式,并演示了如何在不同场景中实现缓存:
此示例演示了缓存工具定义。cache_control 参数放置在最后一个工具(get_time)上,以将所有工具指定为静态前缀的一部分。所有工具定义,包括 get_weatherget_time 之前定义的任何其他工具,都将作为单个前缀缓存。当您有一组一致的工具要在多个请求中复用而无需每次都重新处理时,此方法非常理想。首次请求:
  • input_tokens:用户消息中的 token
  • cache_creation_input_tokens:所有工具定义和系统提示中的 token
  • cache_read_input_tokens:0(首次请求无缓存命中)
缓存生命周期内的后续请求:
  • input_tokens:用户消息中的 token
  • cache_creation_input_tokens:0(无新缓存创建)
  • cache_read_input_tokens:所有缓存工具定义和系统提示中的 token
此示例演示了在多轮对话中的 prompt 缓存。在每一轮中,我们使用 cache_control 标记最终消息的最后一个块,以启用对话的增量缓存。系统会自动查找并使用最长的先前缓存前缀进行后续消息。之前使用 cache_control 标记的块不需要再次标记——如果在 5 分钟内访问,它们仍然会导致缓存命中(和缓存刷新)。请注意,cache_control 也放置在系统消息上。这确保了如果它从缓存中被驱逐(超过 5 分钟未使用后),它将在下一个请求时重新缓存。这种方法非常适合在持续对话中保持上下文,而无需重复处理相同的信息。正确设置后,您应该在每个请求的使用响应中看到以下内容:
  • input_tokens:新用户消息中的 token(通常很少)
  • cache_creation_input_tokens:新助手和用户轮次中的 token
  • cache_read_input_tokens:对话中直到前一轮的 token
这个综合示例演示了如何使用所有 4 个可用的缓存断点来优化 prompt 的不同部分:此模式特别适用于:
  • 具有大型文档上下文的 RAG 应用程序
  • 使用多个工具的 Agent 系统
  • 保持上下文的长时间对话
  • 需要独立优化 prompt 不同部分的应用程序