显式缓存标记是什么
Anthropic 侧需要在内容块上显式打缓存标记：给长文档、工具定义或系统说明加上缓存控制字段，服务端才会把这些内容存下来，后续请求命中时按折扣价读取。写入缓存时按上浮价计费，读取时按折扣价，因此适合「同一份大内容被反复提问」的场景。标记位置决定命中范围：断点之前的内容才会被缓存。
基本信息
| 标记方式 | 在需要缓存的内容块上加缓存控制字段 |
|---|---|
| 有效期 | 默认较短（约数分钟量级），可选更长档位，以官方文档为准 |
| 计费 | 写入按基础价上浮，读取按折扣价 |
| 断点上限 | 单次请求的缓存断点数量有上限（以官方文档为准） |
| 命中条件 | 断点之前的内容完全一致才能命中 |
| 适用范围 | 长文档问答、工具定义固定、系统说明较长的场景 |
标记怎么放
| 位置 | 效果 | 说明 |
|---|---|---|
| 系统说明末尾 | 缓存整段说明 | 规则固定时有收益 |
| 长文档块之后 | 缓存整份文档 | 同一文档反复提问最划算 |
| 工具定义之后 | 缓存工具清单 | 多轮调用场景中收益稳定 |
| 放在易变内容之后 | 几乎不命中 | 断点前后内容都一致才算命中 |
| 标记过短的块 | 收益为负 | 写入上浮价都赚不回来 |
典型使用场景
- 长文档反复提问：一份手册配多个问题依次提问
- 多轮对话：系统规则与背景资料在多轮之间保持不变
- 工具型应用：工具定义较长且每轮都要传给模型
- 批量抽取：同一套指令与示例应用于大量文本
- 客服知识问答：同一份产品资料服务大量用户
缓存标记的写法
缓存标记的写法
{
"model": "claude-sonnet",
"system": [
{ "type": "text", "text": "……超长制度文档……",
"cache_control": { "type": "ephemeral" } }
],
"messages": [ { "role": "user", "content": "差旅报销上限是多少？" } ]
}
// 断点打在最长且最稳定的内容块之后
// 每轮都会变化的内容不要放进已标记缓存的前缀里效果评估要点
| 要点 | 做法 | 原因 |
|---|---|---|
| 命中率观察 | 读响应里的缓存读写与命中用量字段 | 确认缓存是否真的生效 |
| 成本核算 | 把写入上浮与读取折扣一起算 | 写入频繁时未必划算 |
| 内容稳定性 | 评估前缀在多轮之间是否真的不变 | 前缀一变整段缓存失效 |
| 请求间隔 | 按业务实际节奏评估 | 间隔过长会错过有效期 |
| 回退方案 | 命中差时先去掉标记对比效果 | 确认是缓存问题还是别的原因 |
同一次请求里命中的要求很严格：断点之前的内容必须完全一致，插入一个变化字段就会让整段缓存失效。
对很短的文本加缓存标记可能不划算：写入时的上浮费用超过后续读取节省的部分，标记前先估算调用频次。