如何验证 Claude Prompt Caching 是否真正命中
Claude API 请求可能反复携带相同的系统提示词、工具定义和长文档，但“添加了缓存字段”不能证明服务端创建或读取了缓存。前缀中的时间戳、字段顺序或个性化内容发生变化，也可能让后续请求无法复用。本文只解决缓存验收问题：构造稳定前缀，连续发送仅用户问题不同的请求，比较 usage 中的缓存创建与读取字段，再主动修改前缀做对照。最终结果是一份能区分创建、命中和失效的测试记录。
重复输入通常来自：
固定系统提示词。
固定工具定义。
固定产品手册。
同一段长对话历史。
Prompt Caching 面向可复用的请求前缀。具体支持模型、缓存方式、有效期、最低长度和价格都可能变化，测试前必须核对 Claude Prompt Caching 官方文档。
“加一个 cache_control”不等于已经命中。
如果前缀经常变化、请求频率低或网关没有正确转发，缓存可能一直在写，从来没有命中。
1. Prompt Caching 缓存的是什么
它缓存的是提示词前缀，不是最终答案。
适合缓存：
固定系统提示词。
固定 few-shot 示例。
工具定义。
长文档和知识库材料。
多轮对话中不变的历史前缀。
不适合缓存：
每次都完全不同的短请求。
低频、一天只调用一次的上下文。
持续插入时间戳或随机 ID 的前缀。
包含每次变化字段的大段 system 内容。
关键不是“内容很长”。
而是：
内容很长，并且会在缓存有效期内重复出现。
2. 为什么明明配置了却没有命中
缓存按前缀匹配。
前面的内容发生变化，后面的缓存就可能失效。
常见破坏命中的内容：
每次把当前时间写进 system 开头。
动态调整工具顺序。
随机生成请求 ID 并放进缓存前缀。
文档空格或格式每次重新序列化。
把用户个性化字段放在固定知识库之前。
不同服务生成的 JSON 字段顺序不一致。
推荐顺序：
稳定且较长的内容放前面。
经常变化的内容放后面。
例如：
工具定义
↓
系统提示词
↓
固定知识库文档
↓
会话历史
↓
当前用户问题
具体的缓存顺序和可缓存块类型以官方文档为准。
3. 怎么看是否命中
不要通过“感觉响应变快了”判断。
查看响应 usage 中与缓存相关的字段，例如：
cache_creation_input_tokens
cache_read_input_tokens
input_tokens
output_tokens
将第一次请求的缓存创建字段和后续请求的缓存读取字段分别保存，不要只保留总 token。
验收步骤：
1. 固定同一模型、system、工具和文档。
2. 发送第一个问题，记录 usage。
3. 在当前文档规定的有效期内只修改最后的用户问题。
4. 再发送一次，记录 usage。
5. 检查 `cache_read_input_tokens` 是否出现有效读数。
6. 修改缓存前缀，确认命中下降，用作对照。
4. 多租户怎么防止串用
Prompt Caching 不等于应用层数据隔离。
企业系统仍然要确保：
租户 A 的文档不会出现在租户 B 的请求前缀。
缓存构造函数包含正确的租户边界。
日志不记录完整敏感提示词。
文档更新后生成新版本标识。
权限撤销后旧工作流停止复用相关上下文。
推荐把缓存前缀构造逻辑集中管理：
tenant_id
knowledge_version
prompt_version
tool_version
model_id
这些字段用于你自己的日志和缓存版本判断，不要随意插入会导致前缀每次变化的位置。
5. 通过兼容接口接入前要验收什么
兼容接口要真正支持 Prompt Caching，不能只做到普通文本请求兼容。
至少验证：
1. 是否支持 Anthropic 原生 Messages 格式，或明确支持缓存字段。
2. cache_control 是否被原样转发。
3. 目标模型是否支持当前缓存方式。
4. usage 是否返回缓存创建与读取 token。
但 Prompt Caching 属于供应商特定能力，不能假设 /v1/chat/completions 会自动理解 Anthropic 的 cache_control。
以接口服务当前技术文档为准。先用测试凭据发送对照请求并检查 usage，再决定是否采用。
6. 保存可复核的测试记录
只记录输入输出 token 不足以复核缓存测试。保留：
prompt_version。
knowledge_version。
cache_creation_input_tokens。
cache_read_input_tokens。
model_id。
测试时间。
完整请求结构或受控哈希。
请求经过兼容层时，还要记录上游模型和原始 usage，避免接口转换后的汇总字段掩盖创建与读取差异。
7. 常见错误
错误一：每次都把时间戳放在 system 开头
前缀持续变化，缓存无法复用。
错误二：只保留总 token
总数无法区分普通输入、缓存创建和缓存读取。
错误三：没有检查 usage
配置字段存在不代表上游实际创建了缓存。
错误四：有效期与调用间隔不匹配
下一次请求到来前缓存可能已经过期。
错误五：把缓存当知识库
Prompt Caching 只优化重复处理，不负责检索、权限和文档更新。
错误六：中转接口能聊天，就认为能缓存
供应商特定字段需要单独验证。
8. 验收检查清单
[ ] 已确认目标模型支持 Prompt Caching
[ ] 固定前缀达到当前模型最低缓存长度
[ ] 稳定内容在前，动态内容在后
[ ] 已根据当前文档和请求间隔选择有效期
[ ] 已用连续两次请求验证 cache_read_input_tokens
[ ] 文档与提示词有版本号
[ ] 多租户数据构造遵循权限边界
[ ] 网关正确转发 cache_control
[ ] 兼容接口能返回缓存读写 usage
[ ] 测试记录包含当前模型、请求结构和原始 usage
9. 结论与限制
Prompt Caching 最适合这类 API 工作流：
前缀长。
前缀稳定。
短时间内重复调用。
工具和文档会被多次复用。
是否有收益取决于当前定价、首次写入、读取次数、有效期和前缀稳定性，必须使用同期价格与实测 usage 单独计算。本文只给出命中验收顺序：
选一个高重复任务。
固定 system、工具和文档顺序。
按当前文档启用缓存。
连续发送对照请求。
检查 usage。
记录创建、读取与普通输入字段。
再决定是否扩大使用范围。
结论只适用于被测模型、请求结构和接口链路。模型支持、字段、有效期、最低长度与价格均可能变化；上线前应重新查阅官方文档并保留原始请求、响应 usage 和测试时间，不能把一次命中泛化为长期成本结论。