Claude Cache Diagnostics 教程：定位 Prompt Cache Miss 的真正原因

Prompt caching 可以显著降低 Claude API 的成本和延迟，但前提是 prompt prefix 必须逐字节一致。问题是：一旦 cache miss，以前开发者只能看到 usage.cache_read_input_tokens 掉到 0，却不知道哪里变了。

Cache Diagnostics 就是为了解决这个痛点。

Cache Diagnostics 是什么？#

它是 Anthropic 的 beta 功能，需要 beta header：

anthropic-beta: cache-diagnosis-2026-04-07

使用时，你把上一轮 response 的 id 传给下一轮请求：

{
  "diagnostics": {
    "previous_message_id": "msg_xxx"
  }
}

API 会比较两次请求的 fingerprint，并在响应中返回 diagnostics，告诉你第一个分歧点在哪里。

它能发现哪些问题？#

常见 cache miss 根因包括：

• model 变了
• system prompt 里插入了时间戳
• tools 顺序被重新排列
• tool schema 生成顺序不稳定
• 早期 message 被改写
• 自动拼接上下文时多了空格或换行
• 某些应用中间件修改了请求结构

这些变化都可能让 prompt prefix 失去 byte-for-byte identical，从而无法命中缓存。

基本用法#

第一轮请求先启用 diagnostics：

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are analyzing a large document...",
  "messages": [
    {"role": "user", "content": "Summarize section 1."}
  ],
  "diagnostics": {"previous_message_id": null}
}

第二轮传入上一轮的 response id：

{
  "diagnostics": {
    "previous_message_id": "msg_012345"
  }
}

如果 diagnostics 是 null，表示没有发现 prefix divergence。若有 cache_miss_reason，就可以定位具体分歧。

如何和 usage 一起读？#

Diagnostics 只说明请求结构是否分歧，不完全等于最终是否命中缓存。排查时应同时看：

• usage.cache_read_input_tokens
• usage.cache_creation_input_tokens
• diagnostics.cache_miss_reason

如果 cache read 为 0 且 diagnostics 指向 tools 或 system，说明 prompt 构造确实变了。如果 diagnostics 没有分歧但仍 miss，可能是 cache TTL、模型/平台差异或 cache control 位置问题。

数据保留和安全#

官方说明 fingerprints 只包含 hash 和 token-count estimates，不包含原始 prompt 内容；保留时间有限，并且仅用于组织和 workspace 内部的诊断。

该功能符合 ZDR eligibility，但有有限技术保留，应根据官方数据保留说明确认合规要求。

实战建议#

• 所有长会话 Agent 都应在测试环境开启 diagnostics
• 对 tools 数组做稳定排序
• 不要在 system prompt 里直接拼当前时间
• 对自动生成的 schema 做 deterministic serialization
• cache miss 时先查 diagnostics，而不是盲猜
• 将 previous_message_id 链接到应用 trace，方便回放

来源：Anthropic 官方文档 - Cache diagnostics | 整理：ClaudeEagle