加载中
加载中

当您反复向 Claude 发送相同的内容时,提示缓存是一项强大的优化功能,可以让您的 API 请求既更快又更便宜。让我们来探索如何在应用程序中有效地实现它。

提示缓存的工作原理

当您启用提示缓存时,第一个请求会将内容写入缓存,默认生命周期为 5 分钟,每次使用缓存内容时,该窗口都会免费刷新。如果您需要更长的窗口,可以选择 1 小时的缓存持续时间,但需要支付额外费用。后续请求将从此缓存中读取,而不是再次处理相同的内容。当您发送以下内容时,这一点尤其有价值:

  • 大型系统提示(例如 6K 令牌的编码助手提示)
  • 复杂的工具架构(例如多个工具的详细定义)
  • 重复的消息内容

关键的洞察在于:只有当您反复发送相同的内容时,缓存才会有所帮助——但在许多应用程序中,这种情况发生得非常频繁。

设置工具架构缓存

要缓存您的工具架构,您需要在工具列表的最后一个工具中添加一个缓存控制字段。以下是在不修改原始工具定义的情况下正确实现的方法:

python
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"],但使用复制方法可以避免您以后重新排序工具时出现问题。

系统提示缓存

对于系统提示,您需要将其构建为带有缓存控制的文本块:

python
if system:
    params["system"] = [
        {
            "type": "text",
            "text": system,
            "cache_control": {"type": "ephemeral"}
        }
    ]

这会将您的系统提示从简单的字符串转换为支持缓存的结构化格式。

理解缓存行为

当您运行启用了缓存的请求时,您会在响应中看到不同的使用模式:

  • 第一个请求: cache_creation_input_tokens 显示写入了多少令牌——Claude 正在写入缓存
  • 后续请求: cache_read_input_tokens 显示读回的令牌数量相同——Claude 正在从缓存中读取
  • 更改的内容: 会出现新的缓存创建令牌

缓存极其敏感——即使在您的工具或系统提示中更改单个字符,也会使该组件的整个缓存失效。

缓存顺序和断点

您可以在单个请求中设置多个缓存断点。顺序很重要:

  1. 工具(如果提供)
  2. 系统提示(如果提供)
  3. 消息

如果您更改了系统提示但保留了相同的工具,您将看到部分缓存读取(针对工具)和缓存写入(针对新的系统提示)。只有当工具本身达到最小长度时,您才会获得该部分读取,因为如果断点之前的内容未达到最小长度,缓存断点就不会写入任何内容。这种细粒度的缓存意味着您只需为实际发生变化的部分付费。

实际考虑因素

在以下情况下,提示缓存最为有效:

  • 跨请求的工具架构保持一致
  • 系统提示保持稳定
  • 应用程序以相似的上下文发出多个请求

请记住,默认缓存持续 5 分钟(每次使用时刷新),另有 1 小时选项可供选择,但需额外付费,因此它专为具有相对频繁 API 使用的应用程序设计,而非用于长期存储。