--- title: 快取診斷 url: https://platform.claude.com/docs/zh-TW/build-with-claude/cache-diagnostics description: 透過比較連續的請求並精確找出提示前綴發生分歧的位置，診斷非預期的提示快取未命中。 featureMetadata: status: ga zdr: eligibility: eligible note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). supportedPlatforms: Claude API: ga --- [Prompt caching（提示快取）](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)能大幅降低延遲與成本，但前提是您的提示開頭必須與最近的某個請求逐位元組完全相同。工具順序被重新排列、系統提示中插入了時間戳記，或是對較早訊息的編輯，都可能在無聲無息中使快取失效。若沒有快取診斷，唯一的訊號就是 `usage.cache_read_input_tokens` 降為零，卻沒有任何跡象顯示是什麼發生了變化。 「Cache diagnostics」（快取診斷）填補了這個缺口。傳入您上一個回應的 `id`，API 便會比較這兩個請求，並告訴您它們在何處發生分歧（模型、系統提示、工具或訊息歷史），讓您能修正根本原因，而不是憑空猜測。 ## 快取診斷的運作方式 對於每個包含 `diagnostics` 物件的請求，API 會儲存一個以回應 `id` 為鍵的輕量「fingerprint」（指紋）。對於省略該物件的請求，則不會儲存任何內容。在您的下一個請求中，將上一個回應的 `id` 作為 `diagnostics.previous_message_id` 傳入。API 會為新請求重建指紋，將其與已儲存的指紋進行比較，並在回應中附加一個 `diagnostics` 物件，描述第一個分歧點。 此比較針對的是請求結構，與快取是否實際命中無關。請參閱[搭配 usage 解讀診斷結果](https://platform.claude.com/docs/zh-TW/build-with-claude/cache-diagnostics#reading-diagnostics-alongside-usage)，了解如何將 `diagnostics` 結果與 `usage.cache_read_input_tokens` 結合使用。 指紋僅包含雜湊值與 token 數量估計值（絕不包含原始提示內容），保留時間有限，範圍限定於您的組織與工作區，且不會用於任何其他用途。 ## 基本用法 在每一輪都包含 `diagnostics` 物件。此物件即為選擇加入（opt-in）的方式：API 只會為包含它的請求儲存指紋。在第一輪，傳入 `"previous_message_id": null` 以選擇加入，此時沒有可供比較的先前訊息。在後續各輪，傳入上一個回應的 `id`。`cache-diagnosis-2026-04-07` beta 標頭已不再需要，仍傳送該標頭的請求也會照常運作。 ```bash cURL # 第 1 輪：建立快取並選擇啟用診斷功能 response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -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. ...", "messages": [{"role": "user", "content": "Summarize section 1."}], "diagnostics": {"previous_message_id": null} }') jq '{id, diagnostics}' <<< "$response" message_id=$(jq -r '.id' <<< "$response") # 第 2 輪：參照上一輪，讓 API 能比對前綴 curl -sS --fail-with-body https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -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. ...", "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"'"} }' | jq '{id, diagnostics}' # diagnostics: null means no divergence was found ``` ```bash CLI # 第 1 輪 turn1=$(ant beta:messages create \ --transform '{id,usage,diagnostics}' <<'YAML' model: claude-opus-5-5 max_tokens: 1024 cache_control: type: ephemeral system: "You are an AI assistant analyzing a large document. ..." messages: - role: user content: Summarize section 1. diagnostics: previous_message_id: null YAML ) printf '%s\n' "$turn1" # 第 2 輪：將第 1 輪的 id 作為 previous_message_id 傳入 message_id=$(jq -r '.id' <<<"$turn1") ant beta:messages create \ --transform '{id,usage,diagnostics}' <..." 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 ``` ```python Python client = anthropic.Anthropic() SYSTEM = "You are an AI assistant analyzing a large 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}") ``` ```typescript TypeScript const client = new Anthropic(); const SYSTEM = "You are an AI assistant analyzing a large 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}`); } ``` ```csharp C# AnthropicClient client = new(); var system = "You are an AI assistant analyzing a large document. ..."; var r1 = await client.Beta.Messages.Create( new() { Model = Messages::Model.ClaudeOpus5_5, MaxTokens = 1024, CacheControl = new(), System = system, Messages = [ new() { Role = Role.User, 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() { Role = Role.User, Content = "Summarize section 1." }, new() { Role = Role.Assistant, Content = r1.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(), }, new() { Role = Role.User, 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.GetString()}", }); ``` ```go Go client := anthropic.NewClient() ctx := context.Background() system := []anthropic.BetaTextBlockParam{ {Text: "You are an AI assistant analyzing a large 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) } ``` ```java Java var client = AnthropicOkHttpClient.fromEnv(); var system = "You are an AI assistant analyzing a large 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(); // CacheMissReason 未提供具型別的 .type() 存取子；請從原始 JSON 讀取。 @SuppressWarnings("unchecked") var json = (Map) reason._json().orElseThrow().asObject().orElseThrow(); IO.println("cache_miss_reason: " + json.get("type").asStringOrThrow()); } ``` ```php PHP $client = new Client(); $system = 'You are an AI assistant analyzing a large 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", }; ``` ```ruby Ruby client = Anthropic::Client.new SYSTEM = "You are an AI assistant analyzing a large document. ..." 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: nil} ) 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} ) 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` 事件上。 ```bash cURL # 第 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: 2023-06-01" \ -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. ...", "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"'"} }' | jq -R 'select(startswith("data: ")) | ltrimstr("data: ") | fromjson | select(.type == "message_start") | .message.diagnostics' ``` ```bash CLI # 第 2 輪：串流。使用 --stream 時，CLI 會將每個 SSE 事件輸出為一個 JSON 物件。 # diagnostics 會隨 message_start 事件送達；請用 jq 將其擷取出來。 ant beta:messages create \ --stream --format jsonl <..." 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 jq -c 'select(.type == "message_start") | .message | {id,usage,diagnostics}' ``` ```python Python # 第 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}") ``` ```typescript TypeScript 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}`); } ``` ```csharp C# // 第 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() { Role = Role.User, Content = "Summarize section 1." }, new() { Role = Role.Assistant, Content = r1.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(), }, new() { Role = Role.User, 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.GetString()}", }); ``` ```go Go // 第 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) } ``` ```java Java // 第 2 輪：以串流（streaming）方式傳送，並參照前一個回應的 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(); // CacheMissReason 未提供具型別的 .type() 存取子；請從原始 JSON 讀取。 @SuppressWarnings("unchecked") var json = (Map) reason._json().orElseThrow().asObject().orElseThrow(); IO.println("cache_miss_reason: " + json.get("type").asStringOrThrow()); } ``` ```php PHP // 第 2 輪：串流（streaming），並參照前一個回應的 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", }; ``` ```ruby Ruby # 第 2 輪：串流，並參照前一個回應的 id 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} ) 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` 欄位；可能的值請參閱[回應格式](https://platform.claude.com/docs/zh-TW/build-with-claude/cache-diagnostics#response-format)。 ## 在對話迴圈中串接診斷 在多輪對話中，每一輪都將最新回應的 `id` 作為 `previous_message_id` 往下傳遞。第一次迭代傳入 `null` 以選擇加入；之後每次迭代都傳入上一個回應的 `id`。 此工作流程不太適合以單次 shell 指令呈現。迴圈模式請參閱各 SDK 分頁；每一輪的 HTTP 請求與[基本用法](https://platform.claude.com/docs/zh-TW/build-with-claude/cache-diagnostics#basic-usage)相同。 此工作流程不太適合以單次 shell 指令呈現。迴圈模式請參閱各 SDK 分頁；每一輪的 CLI 呼叫與[基本用法](https://platform.claude.com/docs/zh-TW/build-with-claude/cache-diagnostics#basic-usage)相同。 ```python client = anthropic.Anthropic() SYSTEM = "You are an AI assistant analyzing a large 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-5", max_tokens=1024, cache_control={"type": "ephemeral"}, system=SYSTEM, messages=messages, diagnostics={"previous_message_id": prev_id}, ) 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 ``` ```typescript const client = new Anthropic(); const SYSTEM = "You are an AI assistant analyzing a large document. ..."; const prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."]; const messages: BetaMessageParam[] = []; let prevId: string | null = null; for (const [i, prompt] of prompts.entries()) { messages.push({ role: "user", content: prompt }); const r: 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 (r.diagnostics?.cache_miss_reason) { console.log(`Turn ${i + 1} cache_miss_reason: ${r.diagnostics.cache_miss_reason.type}`); } messages.push({ role: "assistant", content: r.content }); prevId = r.id; } ``` ```csharp AnthropicClient client = new(); var system = "You are an AI assistant analyzing a large document. ..."; List messages = []; string? prevId = null; string[] prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."]; for (int i = 0; i < prompts.Length; i++) { messages.Add(new() { Role = Role.User, Content = prompts[i] }); var r = await client.Beta.Messages.Create( new() { Model = Messages::Model.ClaudeOpus5_5, MaxTokens = 1024, CacheControl = new(), System = system, Messages = messages, Diagnostics = new() { PreviousMessageID = prevId }, } ); if (r.Diagnostics?.CacheMissReason is { Type: var type }) { Console.WriteLine($"Turn {i + 1} cache_miss_reason: {type.GetString()}"); } messages.Add( new() { Role = Role.Assistant, Content = r.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(), } ); prevId = r.ID; } ``` ```go client := anthropic.NewClient() ctx := context.Background() system := []anthropic.BetaTextBlockParam{ {Text: "You are an AI assistant analyzing a large 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))) r, 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 r.JSON.Diagnostics.Valid() && r.Diagnostics.JSON.CacheMissReason.Valid() { fmt.Printf("Turn %d cache_miss_reason: %s\n", turn+1, r.Diagnostics.CacheMissReason.Type) } messages = append(messages, r.ToParam()) prevID = anthropic.String(r.ID) } ``` ```java var client = AnthropicOkHttpClient.fromEnv(); var system = "You are an AI assistant analyzing a large document. ..."; var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3."); var messages = new ArrayList(); String prevId = null; for (var turn = 0; turn < prompts.size(); turn++) { messages.add( BetaMessageParam.builder() .role(BetaMessageParam.Role.USER) .content(prompts.get(turn)) .build() ); var r = 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 (r.diagnostics().isPresent() && r.diagnostics().get().cacheMissReason().isPresent()) { var reason = r.diagnostics().get().cacheMissReason().get(); // CacheMissReason 未提供具型別的 .type() 存取子；請從原始 JSON 讀取。 @SuppressWarnings("unchecked") var json = (Map) reason._json().orElseThrow().asObject().orElseThrow(); IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + json.get("type").asStringOrThrow()); } messages.add(r.toParam()); prevId = r.id(); } ``` ```php $client = new Client(); $system = 'You are an AI assistant analyzing a large document. ...'; $messages = []; $prevId = null; foreach (['Summarize section 1.', 'Now section 2.', 'Now section 3.'] as $i => $userMsg) { $turn = $i + 1; $messages[] = ['role' => 'user', 'content' => $userMsg]; $r = $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 ($r->diagnostics?->cacheMissReason !== null) { echo "Turn {$turn} cache_miss_reason: {$r->diagnostics->cacheMissReason->type}\n"; } $messages[] = ['role' => 'assistant', 'content' => $r->content]; $prevId = $r->id; } ``` ```ruby client = Anthropic::Client.new SYSTEM = "You are an AI assistant analyzing a large document. ..." messages = [] prev_id = nil ["Summarize section 1.", "Now section 2.", "Now section 3."].each_with_index do |user_msg, i| messages << {role: "user", content: user_msg} r = 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 (reason = r.diagnostics&.cache_miss_reason) puts "Turn #{i + 1} cache_miss_reason: #{reason.type}" end messages << {role: "assistant", content: r.content} prev_id = r.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` 不為 null 時，其內容如下： ```json { "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` 中較早的項目被修改、重新排序或移除，而非僅附加新內容。通常是對話歷史被截斷或編輯，或是 assistant 輪次與 `tool_result` 區塊在重新傳送時以不同方式重新序列化。 | 將歷史視為僅可附加；將 assistant 的 `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` 標頭集合）不同的情況，以及分歧點超出比較範圍的極長對話。您的請求已正常處理。 | 在快取對話的整個生命週期內，保持會影響提示的請求參數不變。若問題持續，請套用提示快取頁面中[常見問題疑難排解](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#troubleshooting-common-issues)下的手動檢查。 | 四種 `*_changed` 類型還帶有一個 `cache_missed_input_tokens` 整數：估計有多少輸入 token 落在分歧點之後，讓您了解損失了多少可快取的前綴。它是在 token 化之前由位元組長度推導而來，因此請將其視為量級指標而非計費數字。它可能與 `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`（未產生比較結果）時，此矩陣亦不適用。 | 診斷結果 | 快取讀取 token 數 | 解讀 | | ------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `null` | 高 | 運作正常。您的前綴穩定且快取命中。 | | `null` | 低或零 | 您的請求相符，但快取項目已不再可用。請考慮縮短各輪之間的間隔，或使用 [1 小時快取 TTL](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#1-hour-cache-duration)。 | | `cache_miss_reason` 為 `*_changed` 類型 | 低或零 | 您的程式錯誤。請求發生了變化；請依 `type` 所指出的原因進行修正。 | | `cache_miss_reason` 為 `*_changed` 類型 | 高 | 罕見。變化發生在提示的後段，但較早的 `cache_control` 斷點仍然命中。值得修正，但影響不大。 | ## 限制 * **僅限 Claude API：** 不適用於 Amazon Bedrock 或 Google Cloud。 * **有限的保留期：** 用於 `previous_message_id` 查詢的指紋會在短時間後過期。請在時間間隔接近的請求之間執行診斷比較。 * **相同工作區：** 上一個請求必須在相同的組織與工作區中執行。若要確認，請比較兩個回應上的 `anthropic-workspace-id` [回應標頭](https://platform.claude.com/docs/zh-TW/api/overview#response-headers)。 * **比較範圍：** 對於唯一變化位於訊息清單深處的極長對話，回應可能是 `unavailable` 而非精確位置。 * **盡力而為：** 診斷絕不會阻擋您的請求或使其失敗。若無法取得診斷資訊，回應會傳回 `unavailable`；若比較仍在執行中，則傳回 `cache_miss_reason: null`。 ## 資料保留 快取診斷符合 ZDR 資格（有條件）。Anthropic 不會為此功能儲存您提示的原始文字或 Claude 的輸出。 API 只會為包含 `diagnostics` 物件的請求儲存指紋。指紋僅由加密雜湊值與 token 數量估計值組成，以回應 `id` 為鍵，且範圍限定於您的組織與工作區。指紋會在短時間後過期，且不會用於任何其他用途。 關於所有功能的 ZDR 資格，請參閱 [API 與資料保留](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention)。 ## 另請參閱 * [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching) * [Token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)