缓存诊断

提示缓存（prompt caching）可以显著降低延迟和成本，但前提是您的提示开头与最近的某个请求逐字节完全相同。工具顺序的调整、插入到系统提示中的时间戳，或对较早消息的编辑，都可能悄无声息地使缓存失效。如果没有缓存诊断，唯一的信号就是 usage.cache_read_input_tokens 降为零，而没有任何关于发生了什么变化的提示。

缓存诊断（cache diagnostics）填补了这一空白。传入您上一个响应的 id，API 会比较这两个请求并告诉您它们在哪里发生了分歧（模型、系统提示、工具或消息历史），这样您就可以修复根本原因，而不是靠猜测。

缓存诊断的工作原理

当存在 beta 请求头时，API 会为每个请求存储一个轻量级的"fingerprint"（指纹），以响应 id 作为键。在您的下一个请求中，将该 id 作为 diagnostics.previous_message_id 传入。API 会为新请求重建指纹，将其与已存储的指纹进行比较，并在响应中附加一个 diagnostics 对象，描述第一个分歧点。

该比较针对的是请求结构，与缓存是否实际命中无关。有关如何将 diagnostics 结果与 usage.cache_read_input_tokens 结合使用，请参阅结合 usage 解读诊断结果。

指纹仅包含哈希值和令牌数量估计值（绝不包含原始提示内容），保留时间有限，作用域限定在您的组织和工作区内，并且不会用于任何其他目的。

基本用法

在每一轮都发送 beta 请求头。在第一轮，传入 "previous_message_id": null 以选择启用该功能，此时没有可供比较的先前消息。在后续轮次中，传入上一个响应的 id。

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

# 第 1 轮：通过 previous_message_id=None 选择启用
r1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[{"role": "user", "content": "Summarize section 1."}],
    diagnostics={"previous_message_id": None},
    betas=["cache-diagnosis-2026-04-07"],
)

# 第 2 轮：引用上一个响应的 id
r2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
)

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

流式传输

在流式传输（streaming）响应中，diagnostics 出现在 message_start 事件上。

# 第 2 轮：流式传输，引用上一个响应的 id
with client.beta.messages.stream(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[
        {"role": "user", "content": "Summarize section 1."},
        {"role": "assistant", "content": r1.content},
        {"role": "user", "content": "Now summarize section 2."},
    ],
    diagnostics={"previous_message_id": r1.id},
    betas=["cache-diagnosis-2026-04-07"],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()
    r2 = stream.get_final_message()

diagnostics = r2.diagnostics
if diagnostics is None:
    print("No divergence detected.")
elif diagnostics.cache_miss_reason is None:
    print("Comparison still pending.")
else:
    print(f"cache_miss_reason: {diagnostics.cache_miss_reason.type}")

message_start 事件携带完整的 diagnostics 字段；有关可能的取值，请参阅响应格式。

在对话循环中传递诊断信息

在多轮对话中，每一轮都将最新的响应 id 作为 previous_message_id 向前传递。第一次迭代传入 null 以选择启用；之后的每次迭代传入上一个响应的 id。

client = anthropic.Anthropic()

SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"

messages = []
prev_id = None

for i, user_message in enumerate(
    ["Summarize section 1.", "Now section 2.", "Now section 3."]
):
    messages.append({"role": "user", "content": user_message})

    r = client.beta.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system=SYSTEM,
        messages=messages,
        diagnostics={"previous_message_id": prev_id},
        betas=["cache-diagnosis-2026-04-07"],
    )

    if r.diagnostics is not None and r.diagnostics.cache_miss_reason is not None:
        print(f"Turn {i + 1} cache_miss_reason: {r.diagnostics.cache_miss_reason.type}")

    messages.append({"role": "assistant", "content": r.content})
    prev_id = r.id

响应格式

响应 Message 上的 diagnostics 字段有四种可能的状态：

当 cache_miss_reason 非空时，它看起来像这样：

{
  "id": "msg_01Xyz...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 41850,
    "output_tokens": 210
  },
  "diagnostics": {
    "cache_miss_reason": {
      "type": "system_changed",
      "cache_missed_input_tokens": 41850
    }
  }
}

缓存未命中原因类型

cache_miss_reason 是一个基于 type 的可辨识联合类型（discriminated union）。响应仅报告最早的分歧，因此请先修复它；后面的分歧可能被它掩盖。

结合 usage 解读诊断结果

diagnostics 回答的是"我的请求变了吗？"，而 usage.cache_read_input_tokens 回答的是"缓存命中了吗？"。将两者结合起来可以告诉您应该从哪里着手排查。

此矩阵适用于您传入了真实 previous_message_id 的轮次。在第一轮（previous_message_id: null），diagnostics 始终为 null，且 cache_read_input_tokens 通常为零，因为此时缓存正在被写入而非读取；无需排查。当 cache_miss_reason 为 null（比较仍在进行中；请检查下一轮）或其 type 为 previous_message_not_found 或 unavailable（未产生比较结果）时，此矩阵也不适用。

限制

• Beta： 在此功能处于 beta 阶段期间，字段名称和语义可能会发生变化。
• 仅限 Claude API： 在 Amazon Bedrock 或 Google Cloud 上不可用。
• 有限的保留期： 用于 previous_message_id 查找的指纹会在短时间后过期。请在时间间隔较近的请求之间运行诊断比较。
• 同一工作区： 上一个请求必须在同一组织和工作区中运行。要进行检查，请比较两个响应上的 anthropic-workspace-id 响应头。
• 比较范围： 对于唯一变化位于消息列表深处的超长对话，响应可能是 unavailable 而非精确位置。
• 尽力而为： 诊断绝不会阻塞您的请求或使其失败。如果诊断信息不可用，响应会返回 unavailable；如果比较仍在运行，则返回 cache_miss_reason: null。

数据保留

缓存诊断符合 ZDR 资格（有条件）。Anthropic 不会为此功能存储您的提示或 Claude 输出的原始文本。

为每个请求存储的指纹仅由加密哈希值和令牌数量估计值组成，以响应 id 作为键，作用域限定在您的组织和工作区内。指纹会在短时间后过期，并且不会用于任何其他目的。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

另请参阅

• 提示缓存
• 令牌计数
• Beta 请求头

Compatibility