此功能符合零数据保留(ZDR)的条件,但存在有限的技术性保留。有关保留内容及原因的详细信息,请参阅数据保留部分。
提示缓存可显著降低延迟和成本,但前提是您的提示开头部分与最近的某个请求逐字节完全相同。工具顺序的调整、插入到系统提示中的时间戳,或对早期消息的编辑,都可能在不知不觉中使缓存失效。如果没有缓存诊断,唯一的信号就是 usage.cache_read_input_tokens 降为零,而无法得知具体是什么发生了变化。
缓存诊断弥补了这一缺口。传入您上一个响应的 id,API 会比较这两个请求,并告诉您它们在何处出现分歧(模型、系统提示、工具或消息历史记录),这样您就可以修复根本原因,而不是靠猜测。
缓存诊断目前处于测试阶段。请在您的 API 请求中包含 beta header(测试版标头)cache-diagnosis-2026-04-07 以使用此功能。
缓存诊断目前仅在 Claude API 上可用,不支持 Amazon Bedrock 或 Vertex AI。
当存在该测试版标头时,API 会为每个请求存储一个轻量级的指纹(fingerprint),并以响应 id 作为键。在您的下一个请求中,将该 id 作为 diagnostics.previous_message_id 传入。API 会为新请求重建指纹,将其与已存储的指纹进行比较,并在响应中附加一个 diagnostics 对象,描述第一个分歧点。
该比较针对的是请求结构,与缓存是否实际命中无关。请参阅结合 usage 解读诊断结果,了解如何将 diagnostics 结果与 usage.cache_read_input_tokens 结合使用。
指纹仅包含哈希值和令牌数量估算值(绝不包含原始提示内容),保留时间有限,作用域限定在您的组织和工作区内,且不会用于任何其他目的。
在每一轮对话中都发送该测试版标头。在第一轮中,传入 "previous_message_id": null 以选择启用该功能(此时没有可供比较的先前消息)。在后续轮次中,传入上一个响应的 id。
在流式传输响应中,diagnostics 出现在 message_start 事件中。
message_start 事件携带完整的 diagnostics 字段;有关可能的取值,请参阅响应格式。
在多轮对话中,将最新的响应 id 作为 previous_message_id 传递到每一轮。第一次迭代传入 null 以选择启用;后续每次迭代传入上一个响应的 id。
响应 Message 上的 diagnostics 字段有四种可能的状态:
| 值 | 含义 |
|---|---|
| 字段不存在 | 请求未包含 diagnostics,或缺少测试版标头。 |
null | previous_message_id 为 null(第一轮,无可比较对象),或者比较已运行且未发现分歧。 |
{"cache_miss_reason": null} | 响应序列化时比较仍在运行中。当响应启动非常快时可能会发生这种情况。请将其视为不确定结果,并在下一轮检查。 |
{"cache_miss_reason": {...}} | 附带了 cache_miss_reason。对于 *_changed 类型,它标识了第一个分歧点;previous_message_not_found 和 unavailable 则表示未生成比较结果的情况。 |
当 cache_miss_reason 非 null 时,其形式如下:
{
"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)。响应仅报告最早的分歧点,因此请先修复它;后续的分歧可能被它所掩盖。
| 类型 | 含义 | 应如何修改 |
|---|---|---|
model_changed | model 与上一个请求不同(例如,路由器、A/B 测试或回退机制选择了不同的模型)。缓存是按模型划分的。 | 在缓存的对话中保持模型不变。 |
system_changed | system 参数不同。通常是时间戳、请求 ID 或其他每次请求都会变化的值被插入到了系统提示中。 | 将系统提示设为字节稳定的常量,并将动态数据移至缓存断点之后的第一条 user 消息中。 |
tools_changed | tools 数组不同:在轮次之间添加、删除或重新排序了工具,或者工具的 input_schema JSON 序列化方式不确定。 | 在每一轮中以固定顺序发送相同的工具列表,并使用确定性方式序列化 schema(例如对键进行排序)。 |
messages_changed | 模型、系统提示和工具均匹配,但 messages 中较早的某个条目被更改、重新排序或删除,而不是被追加。通常是对话历史记录被截断或编辑,或者助手轮次和 块在重新发送时被以不同方式重新序列化。 |
四种 *_changed 类型还携带一个 cache_missed_input_tokens 整数:这是对分歧点之后的输入令牌数量的估算,让您了解损失了多少可缓存的前缀。它是在分词之前根据字节长度推算的,因此请将其视为量级指标,而非计费数字。它可能与 usage.input_tokens 不同(偶尔会超过后者)。
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(未生成比较结果)时,此矩阵同样不适用。
| 诊断结果 | 缓存读取令牌数 | 解读 |
|---|---|---|
null | 高 | 工作正常。您的前缀稳定且缓存命中。 |
null | 低或零 | 您的请求匹配,但缓存条目已不可用。考虑缩短轮次之间的间隔,或使用 1 小时缓存 TTL。 |
cache_miss_reason 为 *_changed 类型 | 低或零 | 您的问题。请求发生了变化;请根据 type 指示的原因进行修复。 |
cache_miss_reason 为 *_changed 类型 | 高 | 罕见。变化发生在提示的靠后位置,但较早的 cache_control 断点仍然命中。值得修复,但影响较小。 |
previous_message_id 查找的指纹会在短时间后过期。请在时间间隔较短的请求之间运行诊断比较。unavailable 而非精确位置。unavailable;如果比较仍在运行中,则返回 cache_miss_reason: null。缓存诊断符合 ZDR(零数据保留)资格(有条件)。Anthropic 不会为此功能存储您的提示或 Claude 输出的原始文本。
为每个请求存储的指纹仅包含加密哈希值和令牌数量估算值,以响应 id 为键,作用域限定在您的组织和工作区内。指纹会在短时间后过期,且不会用于任何其他目的。
有关所有功能的 ZDR 资格,请参阅 API 与数据保留。
Was this page helpful?
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-4-8",
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-4-8",
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}")# 第 2 轮:流式传输,引用上一个响应的 id
with client.beta.messages.stream(
model="claude-opus-4-8",
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}")tool_result将历史记录视为仅追加;逐字回传助手的 content 和工具结果。 |
previous_message_not_found | 提供的 previous_message_id 没有对应的已存储指纹。这并不能证明您的请求发生了变化。通常是上一个请求未携带测试版标头、来自不同的工作区,或者距离发送已过去太长时间。 | 在每一轮都发送测试版标头,并使连续轮次在时间上保持紧凑。 |
unavailable | 此请求的诊断信息不可用。这包括以下情况:model、system 和 tools 均匹配,但其他影响提示的请求参数(tool_choice、thinking、context_management、output_config、output_format 或生效的 anthropic-beta 标头集合)不同;以及对话非常长、分歧点超出比较范围的情况。您的请求已正常处理。 | 在缓存对话的整个生命周期内保持影响提示的请求参数不变。如果问题持续存在,请应用提示缓存页面中常见问题排查下的手动检查方法。 |