提示缓存

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

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

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

​

提示缓存的工作原理

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

1. 系统检查是否已经从最近的查询中缓存了提示前缀（直到指定的缓存断点）。
2. 如果找到，它会使用缓存版本，减少处理时间和成本。
3. 否则，它会处理完整提示，并在响应开始时缓存前缀。

这对以下情况特别有用：

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

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

​

定价

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

注意：

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

​

如何实现提示缓存

​

支持的模型

提示缓存目前支持：

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

​

构建您的提示

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

缓存前缀按以下顺序创建：tools、system，然后是 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 和图像使用在调用之间保持一致
• 验证您至少缓存了最小数量的令牌
• 虽然系统会尝试在缓存断点之前使用先前缓存的内容，但您可以使用额外的 cache_control 参数来保证对提示的先前部分进行缓存查找，这对于具有很长内容块列表的查询可能很有用

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

​

缓存存储和共享

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

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

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

​

提示缓存示例

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

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

​

常见问题

client.beta.promptCaching.messages.create(...)

client.messages.create(...)