当您反复向 Claude 发送相同的内容时,提示缓存是一项强大的优化功能,可以让您的 API 请求既更快又更便宜。让我们来探索如何在应用程序中有效地实现它。
提示缓存的工作原理
当您启用提示缓存时,第一个请求会将内容写入缓存,默认生命周期为 5 分钟,每次使用缓存内容时,该窗口都会免费刷新。如果您需要更长的窗口,可以选择 1 小时的缓存持续时间,但需要支付额外费用。后续请求将从此缓存中读取,而不是再次处理相同的内容。当您发送以下内容时,这一点尤其有价值:
- 大型系统提示(例如 6K 令牌的编码助手提示)
- 复杂的工具架构(例如多个工具的详细定义)
- 重复的消息内容
关键的洞察在于:只有当您反复发送相同的内容时,缓存才会有所帮助——但在许多应用程序中,这种情况发生得非常频繁。
设置工具架构缓存
要缓存您的工具架构,您需要在工具列表的最后一个工具中添加一个缓存控制字段。以下是在不修改原始工具定义的情况下正确实现的方法:
if tools:
tools_clone = tools.copy()
last_tool = tools_clone[-1].copy()
last_tool["cache_control"] = {"type": "ephemeral"}
tools_clone[-1] = last_tool
params["tools"] = tools_clone这种方法在添加缓存控制字段之前,会先创建工具列表和最后一个工具架构的副本。虽然您可以直接修改 tools[-1]["cache_control"],但使用复制方法可以避免您以后重新排序工具时出现问题。
系统提示缓存
对于系统提示,您需要将其构建为带有缓存控制的文本块:
if system:
params["system"] = [
{
"type": "text",
"text": system,
"cache_control": {"type": "ephemeral"}
}
]这会将您的系统提示从简单的字符串转换为支持缓存的结构化格式。
理解缓存行为
当您运行启用了缓存的请求时,您会在响应中看到不同的使用模式:
- 第一个请求:
cache_creation_input_tokens显示写入了多少令牌——Claude 正在写入缓存 - 后续请求:
cache_read_input_tokens显示读回的令牌数量相同——Claude 正在从缓存中读取 - 更改的内容: 会出现新的缓存创建令牌
缓存极其敏感——即使在您的工具或系统提示中更改单个字符,也会使该组件的整个缓存失效。
缓存顺序和断点
您可以在单个请求中设置多个缓存断点。顺序很重要:
- 工具(如果提供)
- 系统提示(如果提供)
- 消息
如果您更改了系统提示但保留了相同的工具,您将看到部分缓存读取(针对工具)和缓存写入(针对新的系统提示)。只有当工具本身达到最小长度时,您才会获得该部分读取,因为如果断点之前的内容未达到最小长度,缓存断点就不会写入任何内容。这种细粒度的缓存意味着您只需为实际发生变化的部分付费。
实际考虑因素
在以下情况下,提示缓存最为有效:
- 跨请求的工具架构保持一致
- 系统提示保持稳定
- 应用程序以相似的上下文发出多个请求
请记住,默认缓存持续 5 分钟(每次使用时刷新),另有 1 小时选项可供选择,但需额外付费,因此它专为具有相对频繁 API 使用的应用程序设计,而非用于长期存储。