提示缓存的规则

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



该过程遵循两阶段模式：初始请求写入缓存，后续请求可以从缓存中读取。缓存仅存活 5 分钟，因此此功能在您于短时间内反复发送相同内容时最为有用。

缓存点

提示缓存不会自动启用——您需要手动添加缓存点消息部分来控制要缓存的内容。缓存点告诉 Claude 缓存该点之前消息中所有内容所做的工作。



以下是如何向用户消息添加缓存点：

user_message = {
  "role": "user",
  "content": [
    {"text": ""},
    {"cachePoint": {"type": "default"}}
  ]
}

关键规则是：缓存点之前所有内容所做的工作都会被缓存，但缓存点之后的任何内容都不会存储在缓存中。

缓存点的工作原理



当您使用缓存点发出初始请求时，Claude 会处理所有内容，并存储到该缓存点为止所做的工作。在后续请求中，如果缓存点之前的内容完全相同，Claude 会从缓存中读取之前处理过的工作，而不是重新处理它。



只有当缓存点之前的内容完全相同时，才会使用缓存。即使是像在提示开头添加"请"这样的小改动，也会阻止缓存的使用，从而强制 Claude 从头开始处理所有内容。



跨消息缓存

缓存点可以跨越多条消息，甚至包括助手消息。这意味着您可以缓存截至某一点的整个对话历史。



例如，您可能有一段包含用户消息、助手回复和另一条用户消息的对话，并在末尾设置一个缓存点。整个对话线程的所有处理工作都会被缓存，并可以被重复使用。

最小内容长度

内容必须至少为 1024 个令牌长才能被缓存。这是您在缓存点之前尝试缓存的所有消息和部分的总和。



一条简单的"Hi there!"消息无法满足 1024 个令牌的最低要求，因此不会缓存任何内容。但如果您将"Hi there!"重复 500 次，那将超过 1024 个令牌，从而符合缓存条件。

缓存点位置

缓存点不限于用户消息。您可以将它们添加到系统提示和工具定义中，这实际上是最常见的缓存机会。



对于工具定义：

tools = [
  {"toolSpec": add_duration_to_datetime_schema},
  {"toolSpec": get_current_datetime_schema},
  {"cachePoint": {"type": "default"}}
]

对于系统提示：

system = [
  {"text": "You are a senior software..."},
  {"cachePoint": {"type": "default"}}
]

这些是最有价值的缓存机会，因为系统提示和工具列表在请求之间很少发生变化，使它们成为缓存的完美候选对象。