缓存诊断

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

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

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

缓存诊断的工作原理

对于每个包含 diagnostics 对象的请求,API 会存储一个以响应 id 为键的轻量级 “fingerprint”(指纹)。对于省略该对象的请求,API 不会存储任何内容。在下一个请求中,将上一个响应的 id 作为 diagnostics.previous_message_id 传入。API 会为新请求重新构建指纹,将其与已存储的指纹进行比较,并在响应中附加一个 diagnostics 对象,描述第一个分歧点。

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

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

基本用法

在每一轮中都包含 diagnostics 对象。该对象即表示选择启用:API 仅为包含该对象的请求存储指纹。在第一轮中,传入 "previous_message_id": null,以便在没有可供比较的先前消息的情况下选择启用。在后续轮次中,传入上一个响应中的 id。

示例代码
# 第 1 轮:建立缓存并启用诊断
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are an AI assistant analyzing a large document. <document>...</document>",
    "messages": [{"role": "user", "content": "Summarize section 1."}],
    "diagnostics": {"previous_message_id": null}
  }'

# 第 2 轮:将第 1 轮响应中的 id 作为 previous_message_id 传入,以便 API 比较前缀。
# 在响应中,diagnostics: null 表示未发现分歧。
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are an AI assistant analyzing a large document. <document>...</document>",
    "messages": [
      {"role": "user", "content": "Summarize section 1."},
      {"role": "assistant", "content": "Section 1 covers..."},
      {"role": "user", "content": "Now summarize section 2."}
    ],
    "diagnostics": {"previous_message_id": "'"$message_id"'"}
  }'
示例代码
# 第 1 轮:建立缓存并启用诊断
ant beta:messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
  type: ephemeral
system: "You are an AI assistant analyzing a large document. <document>...</document>"
messages:
  - role: user
    content: Summarize section 1.
diagnostics:
  previous_message_id: null
YAML

# 第 2 轮:将第 1 轮响应中的 id 作为 previous_message_id 传入
ant beta:messages create <<YAML
model: claude-opus-5-5
max_tokens: 1024
cache_control:
  type: ephemeral
system: "You are an AI assistant analyzing a large document. <document>...</document>"
messages:
  - role: user
    content: Summarize section 1.
  - role: assistant
    content: Section 1 covers...
  - role: user
    content: Now summarize section 2.
diagnostics:
  previous_message_id: $message_id
YAML
示例代码
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-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=SYSTEM,
    messages=[{"role": "user", "content": "Summarize section 1."}],
    diagnostics={"previous_message_id": None},
)

# 第 2 轮:引用上一个响应的 id
r2 = client.beta.messages.create(
    model="claude-opus-5-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},
)

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}")
示例代码
const client = new Anthropic();

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

// 第 1 轮:通过 previous_message_id: null 选择启用
const r1 = await client.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  cache_control: { type: "ephemeral" },
  system: SYSTEM,
  messages: [{ role: "user", content: "Summarize section 1." }],
  diagnostics: { previous_message_id: null }
});

// 第 2 轮:引用上一个响应的 id
const r2 = await client.beta.messages.create({
  model: "claude-opus-5-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 }
});

if (r2.diagnostics === null) {
  console.log("No divergence detected.");
} else if (r2.diagnostics.cache_miss_reason === null) {
  console.log("Comparison still pending.");
} else {
  console.log(`cache_miss_reason: ${r2.diagnostics.cache_miss_reason.type}`);
}
示例代码
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;

AnthropicClient client = new();

var system = "You are an AI assistant analyzing a large document. <document>...</document>";

var r1 = await client.Beta.Messages.Create(
    new()
    {
        Model = Messages::Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        CacheControl = new(),
        System = system,
        Messages = [new BetaUserMessageParam { Content = "Summarize section 1." }],
        Diagnostics = new() { PreviousMessageID = null },
    }
);

var r2 = await client.Beta.Messages.Create(
    new()
    {
        Model = Messages::Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        CacheControl = new(),
        System = system,
        Messages =
        [
            new BetaUserMessageParam { Content = "Summarize section 1." },
            new BetaAssistantMessageParam
            {
                Content = r1.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),
            },
            new BetaUserMessageParam { Content = "Now summarize section 2." },
        ],
        Diagnostics = new() { PreviousMessageID = r1.ID },
    }
);

Console.WriteLine(r2.Diagnostics switch
{
    null => "No divergence detected.",
    { CacheMissReason: null } => "Comparison still pending.",
    { CacheMissReason.Type: var type } => $"cache_miss_reason: {type.Raw()}",
});
示例代码
client := anthropic.NewClient()
ctx := context.Background()

system := []anthropic.BetaTextBlockParam{
	{Text: "You are an AI assistant analyzing a large document. <document>...</document>"},
}

r1, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
	Model:        anthropic.ModelClaudeOpus5_5,
	MaxTokens:    1024,
	CacheControl: anthropic.BetaCacheControlEphemeralParam{},
	System:       system,
	Messages: []anthropic.BetaMessageParam{
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize section 1.")),
	},
	Diagnostics: anthropic.BetaDiagnosticsParam{
		PreviousMessageID: param.Null[string](),
	},
})
if err != nil {
	panic(err)
}

r2, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
	Model:        anthropic.ModelClaudeOpus5_5,
	MaxTokens:    1024,
	CacheControl: anthropic.BetaCacheControlEphemeralParam{},
	System:       system,
	Messages: []anthropic.BetaMessageParam{
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize section 1.")),
		r1.ToParam(),
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now summarize section 2.")),
	},
	Diagnostics: anthropic.BetaDiagnosticsParam{
		PreviousMessageID: anthropic.String(r1.ID),
	},
})
if err != nil {
	panic(err)
}

switch {
case !r2.JSON.Diagnostics.Valid():
	fmt.Println("No divergence detected.")
case !r2.Diagnostics.JSON.CacheMissReason.Valid():
	fmt.Println("Comparison still pending.")
default:
	fmt.Printf("cache_miss_reason: %s\n", r2.Diagnostics.CacheMissReason.Type)
}
示例代码
import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
import com.anthropic.models.beta.messages.BetaDiagnosticsParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

void main() {
    var client = AnthropicOkHttpClient.fromEnv();

    var system = "You are an AI assistant analyzing a large document. <document>...</document>";

    var r1 = client.beta().messages().create(
        MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_5_5)
            .maxTokens(1024)
            .cacheControl(BetaCacheControlEphemeral.builder().build())
            .system(system)
            .addUserMessage("Summarize section 1.")
            // 首轮传入 null 即可启用,无需可供比较的先前消息。
            .diagnostics(BetaDiagnosticsParam.builder().previousMessageId((String) null).build())
            .build()
    );

    var r2 = client.beta().messages().create(
        MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_5_5)
            .maxTokens(1024)
            .cacheControl(BetaCacheControlEphemeral.builder().build())
            .system(system)
            .addUserMessage("Summarize section 1.")
            .addMessage(r1)
            .addUserMessage("Now summarize section 2.")
            .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())
            .build()
    );

    if (r2.diagnostics().isEmpty()) {
        IO.println("No divergence detected.");
    } else if (r2.diagnostics().get().cacheMissReason().isEmpty()) {
        IO.println("Comparison still pending.");
    } else {
        var reason = r2.diagnostics().get().cacheMissReason().get();
        IO.println("cache_miss_reason: " + reason.type().asString());
    }
}
示例代码
use Anthropic\Beta\Messages\BetaCacheControlEphemeral;
use Anthropic\Beta\Messages\BetaDiagnosticsParam;
use Anthropic\Messages\Model;

$client = new Client();

$system = 'You are an AI assistant analyzing a large document. <document>...</document>';

$r1 = $client->beta->messages->create(
    model: Model::CLAUDE_OPUS_5_5,
    maxTokens: 1024,
    cacheControl: new BetaCacheControlEphemeral,
    system: $system,
    messages: [
        ['role' => 'user', 'content' => 'Summarize section 1.'],
    ],
    diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID(null),
);

$r2 = $client->beta->messages->create(
    model: Model::CLAUDE_OPUS_5_5,
    maxTokens: 1024,
    cacheControl: new BetaCacheControlEphemeral,
    system: $system,
    messages: [
        ['role' => 'user', 'content' => 'Summarize section 1.'],
        ['role' => 'assistant', 'content' => $r1->content],
        ['role' => 'user', 'content' => 'Now summarize section 2.'],
    ],
    diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($r1->id),
);

echo match (true) {
    $r2->diagnostics === null => "No divergence detected.\n",
    $r2->diagnostics->cacheMissReason === null => "Comparison still pending.\n",
    default => "cache_miss_reason: {$r2->diagnostics->cacheMissReason->type}\n",
};
示例代码
client = Anthropic::Client.new

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

r1 = client.beta.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  max_tokens: 1024,
  cache_control: {type: "ephemeral"},
  system_: SYSTEM,
  messages: [
    {role: "user", content: "Summarize section 1."}
  ],
  diagnostics: {previous_message_id: nil}
)

r2 = client.beta.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_5_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}
)

case r2.diagnostics
in nil
  puts "No divergence detected."
in {cache_miss_reason: nil}
  puts "Comparison still pending."
in {cache_miss_reason: {type:}}
  puts "cache_miss_reason: #{type}"
end

流式传输

在流式传输(streaming)响应中,diagnostics 出现在 message_start 事件上。

示例代码
# 第 2 轮:以流式传输返回响应。diagnostics 随 message_start 事件到达;
# 值为 null 表示未发现差异。
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "stream": true,
    "cache_control": {"type": "ephemeral"},
    "system": "You are an AI assistant analyzing a large document. <document>...</document>",
    "messages": [
      {"role": "user", "content": "Summarize section 1."},
      {"role": "assistant", "content": "Section 1 covers..."},
      {"role": "user", "content": "Now summarize section 2."}
    ],
    "diagnostics": {"previous_message_id": "'"$message_id"'"}
  }'
示例代码
# 第 2 轮:流式传输。使用 --stream 时,CLI 会将每个 SSE 事件输出为一个 JSON 对象。
# diagnostics 随 message_start 事件一同到达。
ant beta:messages create --stream <<YAML
model: claude-opus-5-5
max_tokens: 1024
cache_control:
  type: ephemeral
system: "You are an AI assistant analyzing a large document. <document>...</document>"
messages:
  - role: user
    content: Summarize section 1.
  - role: assistant
    content: Section 1 covers...
  - role: user
    content: Now summarize section 2.
diagnostics:
  previous_message_id: $message_id
YAML
示例代码
# 第 2 轮:流式传输,并引用上一个响应的 id
with client.beta.messages.stream(
    model="claude-opus-5-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},
) 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}")
示例代码
const stream = client.beta.messages.stream({
  model: "claude-opus-5-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 }
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}
process.stdout.write("\n");

// diagnostics 在 message_start 中到达,并一直传递到最终消息
const r2 = await stream.finalMessage();

if (r2.diagnostics === null) {
  console.log("No divergence detected.");
} else if (r2.diagnostics.cache_miss_reason === null) {
  console.log("Comparison still pending.");
} else {
  console.log(`cache_miss_reason: ${r2.diagnostics.cache_miss_reason.type}`);
}
示例代码
// 第 2 轮:流式传输,并引用上一个响应的 id
BetaDiagnostics? diagnostics = null;

var stream = client.Beta.Messages.CreateStreaming(
    new()
    {
        Model = Messages::Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        CacheControl = new(),
        System = system,
        Messages =
        [
            new BetaUserMessageParam { Content = "Summarize section 1." },
            new BetaAssistantMessageParam
            {
                Content = r1.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),
            },
            new BetaUserMessageParam { Content = "Now summarize section 2." },
        ],
        Diagnostics = new() { PreviousMessageID = r1.ID },
    }
);

await foreach (var streamEvent in stream)
{
    if (streamEvent.TryPickStart(out var start))
    {
        // diagnostics 随 message_start 事件一同到达
        diagnostics = start.Message.Diagnostics;
    }
    else if (streamEvent.TryPickContentBlockDelta(out var delta) && delta.Delta.TryPickText(out var textDelta))
    {
        Console.Write(textDelta.Text);
    }
}
Console.WriteLine();

Console.WriteLine(diagnostics switch
{
    null => "No divergence detected.",
    { CacheMissReason: null } => "Comparison still pending.",
    { CacheMissReason.Type: var type } => $"cache_miss_reason: {type.Raw()}",
});
示例代码
// 第 2 轮:流式传输,并引用上一个响应的 id
stream := client.Beta.Messages.NewStreaming(ctx, anthropic.BetaMessageNewParams{
	Model:        anthropic.ModelClaudeOpus5_5,
	MaxTokens:    1024,
	CacheControl: anthropic.BetaCacheControlEphemeralParam{},
	System:       system,
	Messages: []anthropic.BetaMessageParam{
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize section 1.")),
		r1.ToParam(),
		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now summarize section 2.")),
	},
	Diagnostics: anthropic.BetaDiagnosticsParam{
		PreviousMessageID: anthropic.String(r1.ID),
	},
})
defer stream.Close()

// diagnostics 随 message_start 到达;Accumulate 会将其带入 r2
var r2 anthropic.BetaMessage
for stream.Next() {
	if err := r2.Accumulate(stream.Current()); err != nil {
		panic(err)
	}
}
if err := stream.Err(); err != nil {
	panic(err)
}

switch {
case !r2.JSON.Diagnostics.Valid():
	fmt.Println("No divergence detected.")
case !r2.Diagnostics.JSON.CacheMissReason.Valid():
	fmt.Println("Comparison still pending.")
default:
	fmt.Printf("cache_miss_reason: %s\n", r2.Diagnostics.CacheMissReason.Type)
}
示例代码
// 第 2 轮:流式传输,并引用上一个响应的 id
var params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_5_5)
    .maxTokens(1024)
    .cacheControl(BetaCacheControlEphemeral.builder().build())
    .system(system)
    .addUserMessage("Summarize section 1.")
    .addMessage(r1)
    .addUserMessage("Now summarize section 2.")
    .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())
    .build();

var accumulator = BetaMessageAccumulator.create();
try (var streamResponse = client.beta().messages().createStreaming(params)) {
    streamResponse.stream()
        .peek(accumulator::accumulate)
        .flatMap(event -> event.contentBlockDelta().stream())
        .flatMap(deltaEvent -> deltaEvent.delta().text().stream())
        .forEach(textDelta -> IO.print(textDelta.text()));
    IO.println("");
}

// diagnostics 随 message_start 到达,并会一直传递到累积的消息中
var diagnostics = accumulator.message().diagnostics();
if (diagnostics.isEmpty()) {
    IO.println("No divergence detected.");
} else if (diagnostics.get().cacheMissReason().isEmpty()) {
    IO.println("Comparison still pending.");
} else {
    var reason = diagnostics.get().cacheMissReason().get();
    IO.println("cache_miss_reason: " + reason.type().asString());
}
示例代码
// 第 2 轮:流式传输,并引用上一个响应的 id
$stream = $client->beta->messages->createStream(
    model: Model::CLAUDE_OPUS_5_5,
    maxTokens: 1024,
    cacheControl: new BetaCacheControlEphemeral,
    system: $system,
    messages: [
        ['role' => 'user', 'content' => 'Summarize section 1.'],
        ['role' => 'assistant', 'content' => $r1->content],
        ['role' => 'user', 'content' => 'Now summarize section 2.'],
    ],
    diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($r1->id),
);

$diagnostics = null;
foreach ($stream as $event) {
    switch (true) {
        case $event instanceof \Anthropic\Beta\Messages\BetaRawMessageStartEvent:
            // diagnostics 位于 message_start 事件内嵌的 BetaMessage 中
            $diagnostics = $event->message->diagnostics;
            break;
        case $event instanceof \Anthropic\Beta\Messages\BetaRawContentBlockDeltaEvent:
            if ($event->delta instanceof \Anthropic\Beta\Messages\BetaTextDelta) {
                echo $event->delta->text;
            }
            break;
    }
}
echo PHP_EOL;

echo match (true) {
    $diagnostics === null => "No divergence detected.\n",
    $diagnostics->cacheMissReason === null => "Comparison still pending.\n",
    default => "cache_miss_reason: {$diagnostics->cacheMissReason->type}\n",
};
示例代码
# 第 2 轮:流式传输,并引用上一个响应的 id
stream = client.beta.messages.stream(
  model: Anthropic::Model::CLAUDE_OPUS_5_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}
)

stream.each do |event|
  print(event.text) if event.is_a?(Anthropic::Streaming::TextEvent)
end
puts

# diagnostics 随 message_start 到达,并保留在累积的消息上
r2 = stream.accumulated_message

case r2.diagnostics
in nil
  puts "No divergence detected."
in {cache_miss_reason: nil}
  puts "Comparison still pending."
in {cache_miss_reason: {type:}}
  puts "cache_miss_reason: #{type}"
end

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

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

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

此工作流需要的逻辑超出了单个 shell 命令所能承载的范围。请使用 Anthropic SDK 来运行循环。每一轮发送的 HTTP 请求与基本用法中的相同。

此工作流需要的逻辑超出了单个 shell 命令所能承载的范围。请使用 Anthropic SDK 来运行循环。每一轮发送的请求与基本用法中的相同。

示例代码
client = anthropic.Anthropic()

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

messages = []
prev_id = None

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

    response = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system=SYSTEM,
        messages=messages,
        diagnostics={"previous_message_id": prev_id},
    )

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

    messages.append({"role": "assistant", "content": response.content})
    prev_id = response.id
示例代码
import type { BetaMessage, BetaMessageParam } from "@anthropic-ai/sdk/resources/beta";

const client = new Anthropic();

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

const prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];

const messages: BetaMessageParam[] = [];
let prevId: string | null = null;

for (const [turn, prompt] of prompts.entries()) {
  messages.push({ role: "user", content: prompt });

  const response: BetaMessage = await client.beta.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    cache_control: { type: "ephemeral" },
    system: SYSTEM,
    messages,
    diagnostics: { previous_message_id: prevId }
  });

  if (response.diagnostics?.cache_miss_reason) {
    console.log(
      `Turn ${turn + 1} cache_miss_reason: ${response.diagnostics.cache_miss_reason.type}`
    );
  }

  messages.push({ role: "assistant", content: response.content });
  prevId = response.id;
}
示例代码
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;

AnthropicClient client = new();

var system = "You are an AI assistant analyzing a large document. <document>...</document>";

List<BetaMessageParam> messages = [];
string? prevId = null;
string[] prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];

for (int turn = 0; turn < prompts.Length; turn++)
{
    messages.Add(new BetaUserMessageParam { Content = prompts[turn] });

    var response = await client.Beta.Messages.Create(
        new()
        {
            Model = Messages::Model.ClaudeOpus5_5,
            MaxTokens = 1024,
            CacheControl = new(),
            System = system,
            Messages = messages,
            Diagnostics = new() { PreviousMessageID = prevId },
        }
    );

    if (response.Diagnostics?.CacheMissReason is { Type: var type })
    {
        Console.WriteLine($"Turn {turn + 1} cache_miss_reason: {type.Raw()}");
    }

    messages.Add(
        new BetaAssistantMessageParam
        {
            Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),
        }
    );
    prevId = response.ID;
}
示例代码
client := anthropic.NewClient()
ctx := context.Background()

system := []anthropic.BetaTextBlockParam{
	{Text: "You are an AI assistant analyzing a large document. <document>...</document>"},
}

prompts := []string{"Summarize section 1.", "Now section 2.", "Now section 3."}

var messages []anthropic.BetaMessageParam
prevID := param.Null[string]()

for turn, prompt := range prompts {
	messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)))

	response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
		Model:        anthropic.ModelClaudeOpus5_5,
		MaxTokens:    1024,
		CacheControl: anthropic.BetaCacheControlEphemeralParam{},
		System:       system,
		Messages:     messages,
		Diagnostics: anthropic.BetaDiagnosticsParam{
			PreviousMessageID: prevID,
		},
	})
	if err != nil {
		panic(err)
	}

	if response.JSON.Diagnostics.Valid() && response.Diagnostics.JSON.CacheMissReason.Valid() {
		fmt.Printf("Turn %d cache_miss_reason: %s\n", turn+1, response.Diagnostics.CacheMissReason.Type)
	}

	messages = append(messages, response.ToParam())
	prevID = anthropic.String(response.ID)
}
示例代码
import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
import com.anthropic.models.beta.messages.BetaDiagnosticsParam;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

void main() {
    var client = AnthropicOkHttpClient.fromEnv();

    var system = "You are an AI assistant analyzing a large document. <document>...</document>";
    var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3.");

    var messages = new ArrayList<BetaMessageParam>();
    String prevId = null;

    for (var turn = 0; turn < prompts.size(); turn++) {
        messages.add(BetaMessageParam.ofUser(prompts.get(turn)));

        var response = client.beta().messages().create(
            MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_5_5)
                .maxTokens(1024)
                .cacheControl(BetaCacheControlEphemeral.builder().build())
                .system(system)
                .messages(messages)
                .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())
                .build()
        );

        if (response.diagnostics().isPresent() && response.diagnostics().get().cacheMissReason().isPresent()) {
            var reason = response.diagnostics().get().cacheMissReason().get();
            IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + reason.type().asString());
        }

        messages.add(response.toParam());
        prevId = response.id();
    }
}
示例代码
use Anthropic\Beta\Messages\BetaCacheControlEphemeral;
use Anthropic\Beta\Messages\BetaDiagnosticsParam;
use Anthropic\Messages\Model;

$client = new Client();

$system = 'You are an AI assistant analyzing a large document. <document>...</document>';

$messages = [];
$prevId = null;

foreach (['Summarize section 1.', 'Now section 2.', 'Now section 3.'] as $index => $userMsg) {
    $turn = $index + 1;
    $messages[] = ['role' => 'user', 'content' => $userMsg];

    $response = $client->beta->messages->create(
        model: Model::CLAUDE_OPUS_5_5,
        maxTokens: 1024,
        cacheControl: new BetaCacheControlEphemeral,
        system: $system,
        messages: $messages,
        diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($prevId),
    );

    if ($response->diagnostics?->cacheMissReason !== null) {
        echo "Turn {$turn} cache_miss_reason: {$response->diagnostics->cacheMissReason->type}\n";
    }

    $messages[] = ['role' => 'assistant', 'content' => $response->content];
    $prevId = $response->id;
}
示例代码
client = Anthropic::Client.new

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

messages = []
prev_id = nil

["Summarize section 1.", "Now section 2.", "Now section 3."].each_with_index do |user_msg, turn|
  messages << {role: "user", content: user_msg}

  response = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    system_: SYSTEM,
    messages: messages,
    diagnostics: {previous_message_id: prev_id}
  )

  if (reason = response.diagnostics&.cache_miss_reason)
    puts "Turn #{turn + 1} cache_miss_reason: #{reason.type}"
  end

  messages << {role: "assistant", content: response.content}
  prev_id = response.id
end

响应格式

响应 Message 上的 diagnostics 字段有三种可能的取值:

值含义
null请求未包含 diagnostics 对象,previous_message_id 为 null(第一轮,没有可比较的内容),或者在最后一个断点之前没有发生任何分歧。
{"cache_miss_reason": null}在序列化响应时比较仍在进行中。当响应开始得非常快时可能会出现这种情况。请将其视为无定论,并检查下一轮。
{"cache_miss_reason": {...}}附加了一个 cache_miss_reason。对于 *_changed 类型,它标识第一个分歧点;previous_message_not_found 和 unavailable 则是未产生比较结果的情况。

当 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 的可辨识联合类型。响应仅报告最早的分歧,因此请先修复它;后面的分歧可能被它掩盖了。

类型含义需要更改的内容
model_changedmodel 与上一个请求不同(例如,路由器、A/B 测试或回退机制选择了不同的模型)。缓存是按模型区分的。在一个已缓存的对话中保持模型不变。
system_changedsystem 参数不同。通常是时间戳、请求 ID 或其他每次请求都不同的值被插入到了系统提示中。使系统提示成为字节稳定的常量,并将变化的值放入您即将发送的 user 消息中。
tools_changedtools 数组不同:在轮次之间添加、删除或重新排序了工具,或者工具的 input_schema JSON 被非确定性地序列化。每一轮都以固定顺序发送相同的工具列表,并使用确定性序列化的 schema(例如,对键进行排序)。
messages_changed模型、系统提示和工具全部匹配,但 messages 中较早的条目被修改、重新排序或删除,而不是仅追加。通常是对话历史被截断或编辑,或者助手轮次和 tool_result 块在重新发送时被以不同方式重新序列化。将历史视为仅追加;原样回传助手的 content 和工具结果。
previous_message_not_found对于所提供的 previous_message_id,不存在已存储的指纹。这并不能证明您的请求发生了变化。通常是因为上一个请求未包含 diagnostics 对象、它来自不同的工作区,或者距离其发送已经过去了太长时间。在每一轮中都包含 diagnostics 对象,并使连续轮次在时间上保持接近。
unavailable此请求的诊断信息不可用。这包括以下情况:model、system 和 tools 匹配,但另一个影响提示的请求参数(tool_choice、thinking、context_management、output_config、output_format 或活动的 anthropic-beta 请求头集合)不同;以及分歧超出比较范围的超长对话。您的请求已正常处理。在已缓存对话的整个生命周期内保持影响提示的请求参数不变。如果问题持续存在,请应用提示缓存页面上常见问题排查下的手动检查。

结合 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低或为零您的请求匹配,但没有可供读取的缓存条目:它已过期,或者提示短于最小可缓存长度。
cache_miss_reason 为 *_changed 类型低或为零请求发生了变化;请修复 type 所指示的原因。
cache_miss_reason 为 *_changed 类型高罕见。变化发生在提示的后部,但较早的 cache_control 断点仍然命中。值得修复,但影响较小。

限制

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

数据保留

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

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

另请参阅

可用性

缓存诊断在所有模型上可用。

API 支持

Messages API

  • 可用性:可用
状态云平台
可用Claude API

Managed Agents

  • 可用性:不可用

数据处理

数据处理概览

项目零数据保留HIPAA
状态具备资格(有条件;不包括 涵盖的模型)不具备资格
详细信息您的提示和 Claude 的输出不会被存储。由加密哈希和令牌数估算值组成的指纹会被短暂保留,以便与下一个请求进行比较。 了解更多—

适用的端点:

  • /v1/messages 使用 diagnostics
文档内容持续同步更新