キャッシュ診断

プロンプトキャッシングはレイテンシとコストを大幅に削減しますが、それはプロンプトの先頭部分が最近のリクエストとバイト単位で完全に一致している場合に限られます。ツールの順序変更、システムプロンプトに挿入されたタイムスタンプ、または以前のメッセージへの編集は、気づかないうちにキャッシュを無効化する可能性があります。キャッシュ診断がなければ、唯一のシグナルは usage.cache_read_input_tokens がゼロに落ちることだけで、何が変わったのかは示されません。

キャッシュ診断はこのギャップを埋めます。前回のレスポンスの id を渡すと、APIは2つのリクエストを比較し、どこで分岐したか（モデル、システムプロンプト、ツール、またはメッセージ履歴）を教えてくれるため、推測ではなく根本原因を修正できます。

キャッシュ診断の仕組み

ベータヘッダーが存在する場合、APIは各リクエストの軽量なフィンガープリントをレスポンスの id をキーとして保存します。次のリクエストで、その id を diagnostics.previous_message_id として含めます。APIは新しいリクエストのフィンガープリントを再構築し、保存されたものと比較して、最初の分岐点を説明する diagnostics オブジェクトをレスポンスに添付します。

この比較はリクエスト構造に関するものであり、キャッシュが実際にヒットしたかどうかとは独立しています。diagnostics の結果と usage.cache_read_input_tokens を組み合わせる方法については、使用状況と併せて診断結果を読むを参照してください。

フィンガープリントにはハッシュとトークン数の推定値のみが含まれ（生のプロンプト内容は含まれません）、限られた期間のみ保持され、組織とワークスペースにスコープが限定され、他の目的には使用されません。

基本的な使用方法

すべてのターンでベータヘッダーを送信してください。最初のターンでは、比較対象となる前のメッセージがない状態でオプトインするために "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-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}")

ストリーミング

ストリーミングレスポンスでは、diagnostics は message_start イベントに表示されます。

# ターン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}")

message_start イベントには完全な diagnostics フィールドが含まれます。取り得る値についてはレスポンス形式を参照してください。

会話ループを通じた診断の引き継ぎ

マルチターンの会話では、最新のレスポンスの id を各ターンで previous_message_id として引き継ぎます。最初のイテレーションではオプトインのために null を渡し、以降の各イテレーションでは前回のレスポンスの id を渡します。

レスポンス形式

レスポンスの Message にある diagnostics フィールドには、4つの状態があります。

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 による判別共用体です。レスポンスは最も早い分岐のみを報告するため、まずそれを修正してください。後続の分岐はその背後に隠れている可能性があります。

使用状況と併せて診断結果を読む

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 の場合（比較が生成されなかった）にも、このマトリックスは適用されません。

制限事項

• ベータ版： フィールド名とセマンティクスは一般提供前に変更される可能性があります。
• Claude APIのみ： Amazon BedrockおよびVertex AIでは利用できません。
• 限定的な保持期間： previous_message_id 検索用のフィンガープリントは短期間で期限切れになります。診断比較は時間的に近いリクエスト間で実行してください。
• 同一ワークスペース： 前回のリクエストは、同じ組織およびワークスペースのAPIキーで行われている必要があります。
• 比較範囲： 唯一の変更がメッセージリストの深い位置にある非常に長い会話では、正確な位置ではなく unavailable が返される場合があります。
• ベストエフォート： 診断がリクエストをブロックしたり失敗させたりすることはありません。診断情報が利用できない場合、レスポンスは unavailable を返すか、比較がまだ実行中だった場合は cache_miss_reason: null を返します。

データ保持

キャッシュ診断はZDR適格（条件付き）です。Anthropicはこの機能のためにプロンプトの生テキストやClaudeの出力を保存しません。

各リクエストに対して保存されるフィンガープリントは、暗号学的ハッシュとトークン数の推定値のみで構成され、レスポンスの id をキーとし、組織とワークスペースにスコープが限定されます。フィンガープリントは短期間で期限切れになり、他の目的には使用されません。

すべての機能にわたるZDR適格性については、APIとデータ保持を参照してください。

関連項目

• プロンプトキャッシング
• トークンカウント
• ベータヘッダー