• 消息
  • 托管智能体
  • 管理
Search...
⌘K
第一步
Claude 简介快速入门
使用 Claude 构建
功能概览使用消息 API停止原因与回退拒绝与回退回退额度
模型能力
扩展思考自适应思考努力程度任务预算(测试版)快速模式(研究预览)结构化输出引用流式传输消息批处理搜索结果流式传输拒绝多语言支持嵌入
工具
概览工具使用的工作原理教程:构建使用工具的智能体定义工具处理工具调用并行工具使用工具运行器(SDK)严格工具使用工具使用与提示缓存服务器工具故障排除网络搜索工具网页获取工具代码执行工具顾问工具记忆工具Bash 工具计算机使用工具文本编辑器工具
工具基础设施
工具参考管理工具上下文工具组合工具搜索编程式工具调用细粒度工具流式传输
上下文管理
上下文窗口压缩上下文编辑提示缓存对话中系统消息构建编排模式缓存诊断(测试版)令牌计数
处理文件
文件 APIPDF 支持图像与视觉
技能
概览快速入门最佳实践企业技能API 中的技能
MCP
远程 MCP 服务器MCP 连接器
云平台上的 Claude
Amazon BedrockAmazon Bedrock(旧版)AWS 上的 Claude PlatformMicrosoft FoundryVertex AI
Log in
缓存诊断(测试版)
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
消息/上下文管理

缓存诊断

通过比较连续的请求并精确识别提示前缀的分歧位置,诊断意外的提示缓存未命中问题。

此功能符合零数据保留(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,或缺少测试版标头。
nullprevious_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_changedmodel 与上一个请求不同(例如,路由器、A/B 测试或回退机制选择了不同的模型)。缓存是按模型划分的。在缓存的对话中保持模型不变。
system_changedsystem 参数不同。通常是时间戳、请求 ID 或其他每次请求都会变化的值被插入到了系统提示中。将系统提示设为字节稳定的常量,并将动态数据移至缓存断点之后的第一条 user 消息中。
tools_changedtools 数组不同:在轮次之间添加、删除或重新排序了工具,或者工具的 input_schema JSON 序列化方式不确定。在每一轮中以固定顺序发送相同的工具列表,并使用确定性方式序列化 schema(例如对键进行排序)。
messages_changed模型、系统提示和工具均匹配,但 messages 中较早的某个条目被更改、重新排序或删除,而不是被追加。通常是对话历史记录被截断或编辑,或者助手轮次和 块在重新发送时被以不同方式重新序列化。

四种 *_changed 类型还携带一个 cache_missed_input_tokens 整数:这是对分歧点之后的输入令牌数量的估算,让您了解损失了多少可缓存的前缀。它是在分词之前根据字节长度推算的,因此请将其视为量级指标,而非计费数字。它可能与 usage.input_tokens 不同(偶尔会超过后者)。

结合 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(未生成比较结果)时,此矩阵同样不适用。

诊断结果缓存读取令牌数解读
null高工作正常。您的前缀稳定且缓存命中。
null低或零您的请求匹配,但缓存条目已不可用。考虑缩短轮次之间的间隔,或使用 1 小时缓存 TTL。
cache_miss_reason 为 *_changed 类型低或零您的问题。请求发生了变化;请根据 type 指示的原因进行修复。
cache_miss_reason 为 *_changed 类型高罕见。变化发生在提示的靠后位置,但较早的 cache_control 断点仍然命中。值得修复,但影响较小。

限制

  • 测试版: 字段名称和语义在正式发布前可能会发生变化。
  • 仅限 Claude API: 在 Amazon Bedrock 或 Vertex AI 上不可用。
  • 有限保留期: 用于 previous_message_id 查找的指纹会在短时间后过期。请在时间间隔较短的请求之间运行诊断比较。
  • 同一工作区: 上一个请求必须使用来自同一组织和工作区的 API 密钥发出。
  • 比较范围: 对于非常长的对话,如果唯一的变化位于消息列表的深处,响应可能返回 unavailable 而非精确位置。
  • 尽力而为: 诊断绝不会阻塞或导致您的请求失败。如果诊断信息不可用,响应将返回 unavailable;如果比较仍在运行中,则返回 cache_miss_reason: null。

数据保留

缓存诊断符合 ZDR(零数据保留)资格(有条件)。Anthropic 不会为此功能存储您的提示或 Claude 输出的原始文本。

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

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

另请参阅

  • 提示缓存
  • 令牌计数
  • 测试版标头

Was this page helpful?

  • 缓存诊断的工作原理
  • 基本用法
  • 流式传输
  • 在对话循环中传递诊断信息
  • 响应格式
  • 缓存未命中原因类型
  • 结合 usage 解读诊断结果
  • 限制
  • 数据保留
  • 另请参阅
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 标头集合)不同;以及对话非常长、分歧点超出比较范围的情况。您的请求已正常处理。在缓存对话的整个生命周期内保持影响提示的请求参数不变。如果问题持续存在,请应用提示缓存页面中常见问题排查下的手动检查方法。