Claude 中的提示缓存通过存储对您消息所做的计算工作来实现,以便在后续请求中重复使用。这使得后续请求的执行既更快又更便宜,但仅在您反复发送相同内容时才有效。
这个过程很简单:您的初始请求会将处理工作写入缓存,后续请求则可以从该缓存中读取,而无需重新处理相同的内容。默认情况下,缓存的存活时间为 5 分钟,因此只有在该时间范围内反复发送相同内容时,此功能才有用。许多应用程序都是这样做的。如果您需要更长的时间,也可以使用 1 小时的缓存持续时间,但缓存写入价格会更高。
缓存断点
缓存不会自动启用——您需要手动在消息中的特定块上添加缓存断点。其工作原理如下:
- 对消息所做的工作不会自动缓存
- 您必须手动在某个块上添加一个"缓存断点"
- 断点之前的所有工作都会被缓存
- 只有当断点及其之前的内容完全相同时,缓存才会在后续请求中被使用

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

简写形式没有提供添加缓存控制字段的位置,因此您必须使用扩展格式,并将 cache_control 字段设置为 {"type": "ephemeral"}。
缓存断点的工作原理
当您在消息中放置一个缓存断点时,Claude 会缓存截至该断点(包含该断点)的所有处理工作。断点之后的内容会照常处理,不会被缓存。

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

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

这对于您希望缓存截至某一点的整个上下文的对话场景特别有用。
系统提示和工具
您不仅限于文本块——缓存断点还可以添加到以下位置:
- 系统提示
- 工具定义
- 图像块
- 工具使用和工具结果块

系统提示和工具定义是缓存的绝佳候选对象,因为它们在不同请求之间很少发生变化。这通常是您从提示缓存中获益最多的地方。
缓存排序
在后台,Claude 会按特定顺序处理您请求中的各个组成部分:先是工具,然后是系统提示,最后是消息。理解这一顺序有助于您更有效地放置断点。

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

最小内容长度
缓存存在一个最小长度限制,具体取决于模型。对于本课程使用的 Claude Haiku 4.5 模型,内容必须至少达到 4,096 个令牌才能被缓存。这是您尝试缓存的所有消息和块的总和,而不是单个块的长度。
像"Hi there!"这样的消息太短,无法被缓存,但一段真正较长的提示则能达到最低要求。低于最低要求的内容只是会被照常处理而不缓存,并且不会返回任何错误。要判断这一点,可以查看响应中的用量信息:cache_creation_input_tokens 和 cache_read_input_tokens 都将为 0。
有效使用提示缓存的关键在于,识别出您的请求中在多次调用之间保持一致的部分,并有策略地放置断点,从而在最大化重复利用的同时最小化缓存失效。