Claude Prompt Caching 怎么验收：静态前缀、动态尾部与缓存命中率

长文档问答接口明明打开了缓存，账单里的输入 token 却没有下降，延迟也忽高忽低。先别急着换模型，Claude Prompt Caching 的命中对象是“从开头到缓存断点的完整前缀”，只要静态内容前面混入了时间戳或随机请求号，后面的缓存就会一起失效。

缓存到底命中了哪一段前缀

Anthropic 文档把可缓存内容按 tools → system → messages 排列。缓存断点之前的内容会整体参与前缀匹配，后续请求只有前缀一致，才可能复用已有结果。最小可用请求可以这样写：

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "固定的产品知识和回答约束",
  "messages": [{"role": "user", "content": "本轮用户问题"}]
}

自动缓存会把断点向对话末尾推进，适合多轮上下文；如果要固定缓存产品手册或工具定义，则把 cache_control 写到具体内容块上。

静态前缀和动态尾部要拆开

常见错误是把“今天的日期：2026-08-16”拼在 system 最前面。日期一变，整个前缀 hash 就变了。更稳的做法是把动态日期放到最后一个用户块，静态资料的断点保持不动。

TTL 与命中率怎么做一次可复现实验

用同一份长背景连续发送三次请求：第一次观察缓存写入，第二次在几秒内重复观察缓存读取，第三次等过期窗口后再测。默认缓存生命周期为 5 分钟，也可以指定 ttl: 1h；缓存每次被使用会刷新生命周期。

{"cache_control":{"type":"ephemeral","ttl":"1h"}}

记录响应里的 usage，不要只拿客户端耗时做结论：

{
  "input_tokens": 1200,
  "cache_creation_input_tokens": 18000,
  "cache_read_input_tokens": 0
}

第一次通常更像写入；后续命中时 cache_read_input_tokens 应明显增加。若命中突然归零，优先对比断点之前的文本、工具定义、消息顺序和 TTL，而不是立即归因于模型波动。

显式断点的两个坑

一个请求最多只能使用有限的显式断点槽位，重复堆叠断点会得到 400。另一个坑是动态块本身被标成断点：每次内容变化都会产生新前缀，缓存写了很多次，却几乎没有读命中。

• 固定资料放在断点前，动态问题放在断点后。
• 工具、system、messages 的顺序保持稳定。
• 记录 TTL、模型、输入 token 和缓存读写 token。
• 跨环境比较时确认平台和模型一致，避免把配置差异误判成缓存失效。

上线前验收清单

1. 同一静态前缀连续请求能观察到 cache read。
2. 修改静态前缀中的一个字符后，能观察到重新写入。
3. 动态用户问题变化不会破坏静态前缀的命中。
4. 分别验证默认 5 分钟和 1 小时 TTL 的成本与过期行为。
5. 把 usage、请求版本和断点位置写入监控，保留一次冷启动与一次命中样本。

相关问题

Prompt Caching 会缓存整个请求吗？

不会。它缓存的是到断点为止的 prompt 前缀，断点之后的动态内容仍需重新处理。

为什么打开缓存后成本反而变高？

首次写入有单独的 cache write 计费；如果请求很少、前缀经常变化，写入成本可能没有被后续命中摊薄。

自动缓存和显式断点怎么选？

多轮对话优先考虑自动缓存；需要固定手册、工具定义或不同更新频率的资料时，用显式断点更容易控制。

Prompt Caching 的核心验收不是“请求变快了”，而是能解释每次变快或变慢的原因：前缀是否稳定、断点是否合适、TTL 是否覆盖业务间隔，以及 usage 是否真的出现缓存读取。