加载中
加载中

Claude 中的提示缓存通过存储对您消息所做的计算工作来实现,以便在后续请求中重复使用。这使得后续请求的执行既更快又更便宜,但仅在您反复发送相同内容时才有效。

这个过程很简单:您的初始请求会将处理工作写入缓存,后续请求则可以从该缓存中读取,而无需重新处理相同的内容。默认情况下,缓存的存活时间为 5 分钟,因此只有在该时间范围内反复发送相同内容时,此功能才有用。许多应用程序都是这样做的。如果您需要更长的时间,也可以使用 1 小时的缓存持续时间,但缓存写入价格会更高。

缓存断点

缓存不会自动启用——您需要手动在消息中的特定块上添加缓存断点。其工作原理如下:

  • 对消息所做的工作不会自动缓存
  • 您必须手动在某个块上添加一个"缓存断点"
  • 断点之前的所有工作都会被缓存
  • 只有当断点及其之前的内容完全相同时,缓存才会在后续请求中被使用

一条用户消息,包含一个较长的提示文本块和一个设置为类型"ephemeral"的 cache_control 字段,即缓存断点。

要添加缓存断点,您需要使用文本块的长格式写法,而不是简写形式:

简写形式的 user_message,内容为"Hi there!",旁边是长格式写法,包含一个文本块以及类型为"ephemeral"的 cache_control。

简写形式没有提供添加缓存控制字段的位置,因此您必须使用扩展格式,并将 cache_control 字段设置为 {"type": "ephemeral"}。

缓存断点的工作原理

当您在消息中放置一个缓存断点时,Claude 会缓存截至该断点(包含该断点)的所有处理工作。断点之后的内容会照常处理,不会被缓存。

处理"Summarize this"块(带断点)的工作会被缓存,而之后的"Focus on"块则不会。

要使缓存在后续请求中发挥作用,断点之前的内容必须完全相同。即使是像添加单词"please"这样的微小改动,也会使缓存失效,并迫使 Claude 重新处理所有内容。

断点位于最后一条用户消息中,因此 Claude 对之前用户和助手消息所做的工作也会被缓存。

跨消息缓存

缓存断点可以跨越多条消息和多种消息类型。如果您在较后的消息中放置断点,之前的所有消息(用户、助手等)都会被包含在缓存内容中。

断点位于最后一条用户消息"Focus the summary on"上,因此 Claude 会读取所有三条消息的缓存工作。

这对于您希望缓存截至某一点的整个上下文的对话场景特别有用。

系统提示和工具

您不仅限于文本块——缓存断点还可以添加到以下位置:

  • 系统提示
  • 工具定义
  • 图像块
  • 工具使用和工具结果块

最后一个工具定义和系统提示块中都设置了类型为"ephemeral"的 cache_control 字段,两者均被缓存。

系统提示和工具定义是缓存的绝佳候选对象,因为它们在不同请求之间很少发生变化。这通常是您从提示缓存中获益最多的地方。

缓存排序

在后台,Claude 会按特定顺序处理您请求中的各个组成部分:先是工具,然后是系统提示,最后是消息。理解这一顺序有助于您更有效地放置断点。

请求 1 中的缓存断点位于 Tool 3,在系统提示和消息之上;请求 2 仅显示从 Tool 1 到 Tool 3。

您最多可以添加四个缓存断点。例如,您可以缓存您的工具,然后在对话历史中途再添加一个断点。这让您在请求的不同部分发生变化时,能够灵活地控制哪些内容会被缓存。

请求 1 中的缓存断点位于 tool 3 和一条助手消息处;请求 2 重复了 tool 1 到 tool 3 以及 tool 3 的断点。

最小内容长度

缓存存在一个最小长度限制,具体取决于模型。对于本课程使用的 Claude Haiku 4.5 模型,内容必须至少达到 4,096 个令牌才能被缓存。这是您尝试缓存的所有消息和块的总和,而不是单个块的长度。

像"Hi there!"这样的消息太短,无法被缓存,但一段真正较长的提示则能达到最低要求。低于最低要求的内容只是会被照常处理而不缓存,并且不会返回任何错误。要判断这一点,可以查看响应中的用量信息:cache_creation_input_tokens 和 cache_read_input_tokens 都将为 0。

有效使用提示缓存的关键在于,识别出您的请求中在多次调用之间保持一致的部分,并有策略地放置断点,从而在最大化重复利用的同时最小化缓存失效。