prompt-caching

概述

Prompt Caching 是一个用于 Claude API 的提示缓存（prompt caching）技能。根据资料描述，其核心目的是利用 Anthropic 的提示缓存机制，在提示内容被重复使用的场景中大幅降低请求延迟与调用成本，资料给出的量级为延迟最高减少 85%、成本最高降低 90%。

适用场景

资料列出了该技能的典型使用场景：

带有大型静态文档的 RAG 系统
包含长指令的多轮对话
带大型代码库上下文的代码分析
共享前缀的批处理
文档分析与摘要

核心概念

缓存控制放置

在请求中通过 cache_control 字段标记需要缓存的内容，示例写法为 "cache_control": {"type": "ephemeral"}。资料给出的一段 Python 示例中，该字段被放在 system 的参数块内，配合 model、max_tokens 与 messages 一起使用。

缓存层级

资料说明缓存断点按以下顺序检查：

Tools —— 工具定义最先被缓存
System —— 系统提示其次被缓存
Messages —— 对话历史最后被缓存

TTL 选项

资料提供了 TTL 与成本的对照表：

TTL	写入成本	读取成本	使用场景
5 分钟（默认）	基础价 1.25 倍	基础价 0.1 倍	交互式会话
1 小时	基础价 2.0 倍	基础价 0.1 倍	批处理、稳定文档

缓存要求

最小令牌数： 1024–4096（随模型不同而变化）
最大断点数： 每个请求 4 个
支持的模型： 资料称支持所有当前模型（列举为 Fable 5、Opus 4.8、Sonnet 5、Haiku 4.5）

实现模式

模式一：单断点（推荐）

适合文档分析、带静态上下文的问答。做法是将断点放在静态内容的结尾处，即将 cache_control 放在 system 中最后一个内容块上。

模式二：多轮对话

将 cache_control 放在对话消息中，使缓存随对话增长。资料示例中，该字段被放在最新一条 user 消息上，用于缓存整个对话。

模式三：带多断点的 RAG

在 system 中设置多个内容块并各自标记断点：第一块放工具定义与指令，作为断点 1；第二块放检索到的文档，作为断点 2。

模式四：1 小时 TTL 的批处理

先用一次请求预热缓存（system 中带 cache_control 且 ttl 设为 "1h"），随后遍历批处理条目逐条请求，这些请求都会命中缓存。资料给出的示例中，预热请求与批处理请求的 system 内容保持一致。

性能监控

资料建议通过响应中的 usage 字段观察缓存效果：

cache_creation_input_tokens —— 新写入缓存的数量
cache_read_input_tokens —— 命中缓存的数量
input_tokens —— 断点之后未被缓存的数量

并给出缓存命中率的计算方式：cache_read / (cache_read + cache_write + uncached) * 100。

成本计算

资料提供一个示例函数 calculate_cost，以 base_input_rate 为基础费率，写入成本按基础价 1.25 倍、读取成本按基础价 0.1 倍、未缓存部分按基础价分别计算后求和。资料同时提示该费率为示例，需核对当前定价。

缓存失效

资料列出会令缓存失效的变更类型：

变更	影响
工具定义	整个缓存失效
系统提示	系统与消息部分失效
断点之前的任意内容	该断点及其之后失效

最佳实践

资料给出的建议包括：

应当做的：

将断点放在静态内容的末尾
在多次请求间保持工具与指令稳定
批处理使用 1 小时 TTL
监控 cache_read_input_tokens 以确认节省效果

不应做的：

将断点放在动态内容中间
频繁修改工具定义
期待低于 1024 令牌时缓存生效
忽略 20 个块的回溯限制

与扩展思考的集成

资料给出缓存与扩展思考同时使用的示例：在请求中设置 thinking 为 {"type": "adaptive"}，并在 system 中带上 cache_control。

限制与说明

资料未提供该技能的安装命令、收费方式、价格以及独立的平台限制说明；其中的费率数值仅作为计算示例，模型名称与支持范围也需以官方最新信息为准。

技能介绍

概述