提示缓存是一个强大的功能,它通过允许从提示中的特定前缀恢复来优化您的API使用。这种方法显著减少了重复任务或具有一致元素的提示的处理时间和成本。

以下是使用Messages API实现提示缓存的示例,使用cache_control块:

在这个示例中,《傲慢与偏见》的全部文本使用cache_control参数进行缓存。这使得这个大文本可以在多个API调用中重复使用,而无需每次都重新处理。只更改用户消息就可以让您询问关于这本书的各种问题,同时利用缓存的内容,从而获得更快的响应和提高效率。

提示缓存处于测试版阶段

我们很高兴地宣布提示缓存现已进入公开测试阶段!要访问此功能,您需要在API请求中包含anthropic-beta: prompt-caching-2024-07-31头部。

我们将在接下来的几周内对这个公开测试版进行迭代,因此我们感谢您的反馈。请使用此表单分享您的想法和建议。


提示缓存的工作原理

当您发送启用了提示缓存的请求时:

  1. 系统检查提示前缀是否已从最近的查询中缓存。
  2. 如果找到,它会使用缓存版本,减少处理时间和成本。
  3. 否则,它会处理完整提示并缓存前缀以供将来使用。

这对以下情况特别有用:

  • 包含许多示例的提示
  • 大量的上下文或背景信息
  • 具有一致指令的重复任务
  • 长时间的多轮对话

缓存的生命周期为5分钟,每次使用缓存内容时都会刷新。

提示缓存会缓存完整前缀

提示缓存引用整个提示 - toolssystemmessages(按此顺序)直到并包括用cache_control指定的块。


定价

提示缓存引入了新的定价结构。下表显示了每个支持模型的每个令牌的价格:

模型基础输入令牌缓存写入缓存命中输出令牌
Claude 3.5 Sonnet$3 / MTok$3.75 / MTok$0.30 / MTok$15 / MTok
Claude 3.5 Haiku$1 / MTok$1.25 / MTok$0.10 / MTok$5 / MTok
Claude 3 Haiku$0.25 / MTok$0.30 / MTok$0.03 / MTok$1.25 / MTok
Claude 3 Opus$15 / MTok$18.75 / MTok$1.50 / MTok$75 / MTok

注意:

  • 缓存写入令牌比基础输入令牌贵25%
  • 缓存读取令牌比基础输入令牌便宜90%
  • 常规输入和输出令牌按标准费率定价

如何实现提示缓存

支持的模型

提示缓存目前支持:

  • Claude 3.5 Sonnet
  • Claude 3.5 Haiku
  • Claude 3 Haiku
  • Claude 3 Opus

构建您的提示

将静态内容(工具定义、系统指令、上下文、示例)放在提示的开头。使用cache_control参数标记要缓存的可重用内容的结束位置。

缓存前缀按以下顺序创建:toolssystem,然后是messages

使用cache_control参数,您可以定义最多4个缓存断点,允许您分别缓存不同的可重用部分。

缓存限制

最小可缓存提示长度为:

  • Claude 3.5 Sonnet和Claude 3 Opus为1024个令牌
  • Claude 3.5 Haiku和Claude 3 Haiku为2048个令牌

即使标记了cache_control,较短的提示也无法缓存。任何请求缓存少于此数量的令牌都将在不缓存的情况下处理。要查看提示是否已缓存,请参阅响应使用字段

缓存的生存时间(TTL)为5分钟。目前,“ephemeral”是唯一支持的缓存类型,对应于这个5分钟的生命周期。

可以缓存什么

请求中的每个块都可以用cache_control指定进行缓存。这包括:

  • 工具:tools数组中的工具定义
  • 系统消息:system数组中的内容块
  • 消息:messages.content数组中的内容块,适用于用户和助手轮次
  • 图像:用户轮次中messages.content数组中的内容块
  • 工具使用和工具结果:用户和助手轮次中messages.content数组中的内容块

这些元素中的每一个都可以用cache_control标记,以启用该部分请求的缓存。

跟踪缓存性能

使用这些API响应字段监控缓存性能,这些字段位于响应中的usage内(或如果流式传输则在message_start事件中):

  • cache_creation_input_tokens:创建新条目时写入缓存的令牌数。
  • cache_read_input_tokens:从缓存中检索的此请求的令牌数。
  • input_tokens:未从缓存读取或用于创建缓存的输入令牌数。

有效缓存的最佳实践

要优化提示缓存性能:

  • 缓存稳定的、可重用的内容,如系统指令、背景信息、大型上下文或频繁的工具定义。
  • 将缓存内容放在提示的开头以获得最佳性能。
  • 战略性地使用缓存断点来分隔不同的可缓存前缀部分。
  • 定期分析缓存命中率并根据需要调整策略。

针对不同用例的优化

根据您的场景调整提示缓存策略:

  • 对话代理:减少延长对话的成本和延迟,特别是那些有长指令或上传文档的对话。
  • 编码助手:通过在提示中保持相关部分或代码库的摘要版本来改进自动完成和代码库问答。
  • 大文档处理:在不增加响应延迟的情况下,在提示中包含完整的长篇材料,包括图像。
  • 详细指令集:共享广泛的指令、程序和示例列表,以微调Claude的响应。开发人员通常在提示中包含一两个示例,但使用提示缓存,您可以通过包含20多个多样化的高质量答案示例来获得更好的性能。
  • 代理工具使用:增强涉及多个工具调用和迭代代码更改的场景的性能,其中每个步骤通常需要新的API调用。
  • 与书籍、论文、文档、播客记录和其他长篇内容交谈:通过将整个文档嵌入到提示中,让用户能够提问,从而让任何知识库活起来。

常见问题故障排除

如果遇到意外行为:

  • 确保缓存部分在调用之间完全相同,并在相同位置标记了cache_control
  • 检查调用是否在5分钟的缓存生命周期内进行
  • 验证tool_choice和图像使用在调用之间保持一致
  • 验证您至少缓存了最小数量的令牌

请注意,更改tool_choice或提示中任何位置的图像存在/不存在都将使缓存失效,需要创建新的缓存条目。


缓存存储和共享

  • 组织隔离:缓存在组织之间是隔离的。不同的组织永远不会共享缓存,即使它们使用相同的提示。

  • 精确匹配:缓存命中需要100%相同的提示段,包括标记有缓存控制的块中及之前的所有文本和图像。在缓存读取和创建期间必须用cache_control标记相同的块。

  • 输出令牌生成:提示缓存对输出令牌生成没有影响。您收到的响应将与不使用提示缓存时相同。


提示缓存示例

为了帮助您开始使用提示缓存,我们准备了一个提示缓存指南,其中包含详细的示例和最佳实践。

下面,我们包含了几个展示各种提示缓存模式的代码片段。这些示例演示了如何在不同场景中实现缓存,帮助您理解此功能的实际应用:


常见问题