プロンプトキャッシング

プロンプトキャッシングは、プロンプト内の特定のプレフィックスからの再開を可能にすることで、API使用を最適化する強力な機能です。このアプローチにより、反復的なタスクや一貫した要素を持つプロンプトの処理時間とコストが大幅に削減されます。

以下は、cache_control ブロックを使用してMessages APIでプロンプトキャッシングを実装する方法の例です：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# キャッシュチェックポイントまでの同じ入力でモデルを再度呼び出す
curl https://api.anthropic.com/v1/messages # rest of input

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

この例では、「高慢と偏見」の全文が cache_control パラメータを使用してキャッシュされています。これにより、この大きなテキストを毎回再処理することなく、複数のAPI呼び出しで再利用できます。ユーザーメッセージのみを変更することで、キャッシュされたコンテンツを活用しながら本についてさまざまな質問をすることができ、より高速な応答と効率の向上につながります。

プロンプトキャッシングの仕組み

プロンプトキャッシングを有効にしてリクエストを送信すると：

1. システムは、指定されたキャッシュブレークポイントまでのプロンプトプレフィックスが、最近のクエリからすでにキャッシュされているかどうかを確認します。
2. 見つかった場合、キャッシュされたバージョンを使用し、処理時間とコストを削減します。
3. 見つからない場合、完全なプロンプトを処理し、応答が開始されるとプレフィックスをキャッシュします。

これは特に以下の場合に有用です：

• 多くの例を含むプロンプト
• 大量のコンテキストや背景情報
• 一貫した指示を持つ反復的なタスク
• 長いマルチターン会話

デフォルトでは、キャッシュの有効期間は5分です。キャッシュされたコンテンツが使用されるたびに、追加コストなしでキャッシュが更新されます。

料金

プロンプトキャッシングは新しい料金体系を導入しています。以下の表は、サポートされている各モデルの100万トークンあたりの価格を示しています：

プロンプトキャッシングの実装方法

サポートされているモデル

プロンプトキャッシングは現在以下のモデルでサポートされています：

• Claude Opus 4.6
• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7（非推奨）
• Claude Haiku 4.5
• Claude Haiku 3.5（非推奨）
• Claude Haiku 3

プロンプトの構造化

静的コンテンツ（ツール定義、システム指示、コンテキスト、例）をプロンプトの先頭に配置します。cache_control パラメータを使用して、再利用可能なコンテンツの終わりをキャッシング用にマークします。

キャッシュプレフィックスは次の順序で作成されます：tools、system、次に messages。この順序は、各レベルが前のレベルの上に構築される階層を形成します。

自動プレフィックスチェックの仕組み

静的コンテンツの最後に1つのキャッシュブレークポイントを使用するだけで、システムは自動的にキャッシュされたブロックの最長一致シーケンスを見つけます。この仕組みを理解することで、キャッシング戦略を最適化できます。

3つの基本原則：

1. キャッシュキーは累積的：cache_control でブロックを明示的にキャッシュすると、キャッシュハッシュキーは会話内のすべての前のブロックを順次ハッシュすることで生成されます。つまり、各ブロックのキャッシュは、それ以前のすべてのコンテンツに依存します。

2. 逆方向の順次チェック：システムは、明示的なブレークポイントから逆方向に作業し、各前のブロックを逆順にチェックすることでキャッシュヒットを確認します。これにより、可能な限り最長のキャッシュヒットが得られます。

3. 20ブロックのルックバックウィンドウ：システムは、各明示的な cache_control ブレークポイントの前の最大20ブロックのみをチェックします。一致なしで20ブロックをチェックした後、チェックを停止し、次の明示的なブレークポイント（存在する場合）に移動します。

例：ルックバックウィンドウの理解

30のコンテンツブロックがある会話で、ブロック30にのみ cache_control を設定した場合を考えてみましょう：

• 前のブロックに変更なしでブロック31を送信した場合：システムはブロック30をチェック（一致！）。ブロック30でキャッシュヒットが得られ、ブロック31のみが処理される必要があります。

• ブロック25を変更してブロック31を送信した場合：システムはブロック30 → 29 → 28... → 25（一致なし）→ 24（一致！）と逆方向にチェックします。ブロック24は変更されていないため、ブロック24でキャッシュヒットが得られ、ブロック25-30のみが再処理される必要があります。

• ブロック5を変更してブロック31を送信した場合：システムはブロック30 → 29 → 28... → 11（チェック#20）と逆方向にチェックします。一致を見つけることなく20回チェックした後、チェックを停止します。ブロック5は20ブロックのウィンドウを超えているため、キャッシュヒットは発生せず、すべてのブロックが再処理される必要があります。ただし、ブロック5に明示的な cache_control ブレークポイントを設定していた場合、システムはそのブレークポイントからチェックを続行します：ブロック5（一致なし）→ ブロック4（一致！）。これにより、ブロック4でキャッシュヒットが可能になり、編集可能なコンテンツの前にブレークポイントを配置すべき理由を示しています。

重要なポイント：キャッシュヒットの可能性を最大化するために、常に会話の最後に明示的なキャッシュブレークポイントを設定してください。さらに、編集される可能性のあるコンテンツブロックの直前にブレークポイントを設定して、それらのセクションが独立してキャッシュされるようにしてください。

複数のブレークポイントを使用するタイミング

以下の場合、最大4つのキャッシュブレークポイントを定義できます：

• 異なる頻度で変更されるセクションをキャッシュする場合（例：ツールはめったに変更されないが、コンテキストは毎日更新される）
• キャッシュされる内容をより細かく制御したい場合
• 最終ブレークポイントの20ブロック以上前のコンテンツのキャッシングを確保する場合
• 編集可能なコンテンツの前にブレークポイントを配置して、20ブロックウィンドウを超えた変更が発生してもキャッシュヒットを保証する場合

キャッシュの制限

キャッシュ可能な最小プロンプト長は以下の通りです：

• Claude Opus 4.6、Claude Opus 4.5の場合は4096トークン
• Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7（非推奨）の場合は1024トークン
• Claude Haiku 4.5の場合は4096トークン
• Claude Haiku 3.5（非推奨）およびClaude Haiku 3の場合は2048トークン

短いプロンプトは、cache_control でマークされていてもキャッシュできません。このトークン数未満をキャッシュするリクエストは、キャッシングなしで処理されます。プロンプトがキャッシュされたかどうかを確認するには、レスポンスのusageフィールドを参照してください。

並行リクエストの場合、キャッシュエントリは最初のレスポンスが開始された後にのみ利用可能になることに注意してください。並行リクエストでキャッシュヒットが必要な場合は、後続のリクエストを送信する前に最初のレスポンスを待ってください。

現在、「ephemeral」が唯一サポートされているキャッシュタイプで、デフォルトで5分の有効期間を持ちます。

キャッシュブレークポイントのコストの理解

キャッシュブレークポイント自体にはコストがかかりません。 課金されるのは以下のみです：

• キャッシュ書き込み：新しいコンテンツがキャッシュに書き込まれる場合（5分TTLの場合、基本入力トークンの25%増）
• キャッシュ読み取り：キャッシュされたコンテンツが使用される場合（基本入力トークン価格の10%）
• 通常の入力トークン：キャッシュされていないコンテンツの場合

cache_control ブレークポイントを追加してもコストは増加しません。実際にキャッシュされ読み取られるコンテンツに基づいて同じ金額が課金されます。ブレークポイントは、どのセクションを独立してキャッシュできるかを制御するだけです。

キャッシュ可能なもの

リクエスト内のほとんどのブロックは、cache_control でキャッシング用に指定できます。これには以下が含まれます：

• ツール：tools 配列内のツール定義
• システムメッセージ：system 配列内のコンテンツブロック
• テキストメッセージ：messages.content 配列内のコンテンツブロック（ユーザーターンとアシスタントターンの両方）
• 画像とドキュメント：messages.content 配列内のコンテンツブロック（ユーザーターン）
• ツール使用とツール結果：messages.content 配列内のコンテンツブロック（ユーザーターンとアシスタントターンの両方）

これらの各要素は、リクエストのその部分のキャッシングを有効にするために cache_control でマークできます。

キャッシュできないもの

ほとんどのリクエストブロックはキャッシュできますが、いくつかの例外があります：

• 思考ブロックは cache_control で直接キャッシュできません。ただし、思考ブロックは、以前のアシスタントターンに表示される場合、他のコンテンツと一緒にキャッシュできます。この方法でキャッシュされた場合、キャッシュから読み取られるときに入力トークンとしてカウントされます。

• サブコンテンツブロック（引用など）自体は直接キャッシュできません。代わりに、トップレベルのブロックをキャッシュしてください。

  引用の場合、引用のソース資料として機能するトップレベルのドキュメントコンテンツブロックをキャッシュできます。これにより、引用が参照するドキュメントをキャッシュすることで、引用とプロンプトキャッシングを効果的に使用できます。

• 空のテキストブロックはキャッシュできません。

キャッシュを無効にするもの

キャッシュされたコンテンツの変更は、キャッシュの一部またはすべてを無効にする可能性があります。

プロンプトの構造化で説明したように、キャッシュは tools → system → messages の階層に従います。各レベルでの変更は、そのレベルとそれ以降のすべてのレベルを無効にします。

以下の表は、異なるタイプの変更によってキャッシュのどの部分が無効になるかを示しています。✘はキャッシュが無効になることを示し、✓はキャッシュが有効なままであることを示します。

キャッシュパフォーマンスの追跡

レスポンス内の usage（ストリーミングの場合は message_start イベント）にある以下のAPIレスポンスフィールドを使用してキャッシュパフォーマンスを監視します：

• cache_creation_input_tokens：新しいエントリを作成する際にキャッシュに書き込まれたトークン数。
• cache_read_input_tokens：このリクエストのためにキャッシュから取得されたトークン数。
• input_tokens：キャッシュから読み取られなかった、またはキャッシュの作成に使用されなかった入力トークン数（つまり、最後のキャッシュブレークポイント以降のトークン）。

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

効果的なキャッシングのベストプラクティス

プロンプトキャッシングのパフォーマンスを最適化するには：

• システム指示、背景情報、大きなコンテキスト、頻繁なツール定義など、安定した再利用可能なコンテンツをキャッシュします。
• 最高のパフォーマンスを得るために、キャッシュされたコンテンツをプロンプトの先頭に配置します。
• キャッシュブレークポイントを戦略的に使用して、異なるキャッシュ可能なプレフィックスセクションを分離します。
• 特に20を超えるコンテンツブロックを持つプロンプトで作業する場合、キャッシュヒット率を最大化するために、会話の最後と編集可能なコンテンツの直前にキャッシュブレークポイントを設定します。
• キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整します。

さまざまなユースケースの最適化

シナリオに合わせてプロンプトキャッシング戦略を調整します：

• 会話エージェント：特に長い指示やアップロードされたドキュメントを含む拡張会話のコストとレイテンシーを削減します。
• コーディングアシスタント：関連するセクションやコードベースの要約版をプロンプトに保持することで、オートコンプリートとコードベースQ&Aを改善します。
• 大規模ドキュメント処理：レスポンスレイテンシーを増加させることなく、画像を含む完全な長文資料をプロンプトに組み込みます。
• 詳細な指示セット：Claudeのレスポンスを微調整するための広範な指示、手順、例のリストを共有します。開発者はプロンプトに1つか2つの例を含めることが多いですが、プロンプトキャッシングを使用すると、20以上の多様な高品質回答の例を含めることで、さらに優れたパフォーマンスを得ることができます。
• エージェントツール使用：複数のツール呼び出しと反復的なコード変更を含むシナリオのパフォーマンスを向上させます。各ステップは通常、新しいAPI呼び出しを必要とします。
• 書籍、論文、ドキュメント、ポッドキャストのトランスクリプト、その他の長文コンテンツとの対話：ドキュメント全体をプロンプトに埋め込み、ユーザーが質問できるようにすることで、あらゆるナレッジベースを活性化します。

一般的な問題のトラブルシューティング

予期しない動作が発生した場合：

• キャッシュされたセクションが同一であり、呼び出し間で同じ場所にcache_controlがマークされていることを確認します
• 呼び出しがキャッシュの有効期間内（デフォルトで5分）に行われていることを確認します
• tool_choice と画像の使用が呼び出し間で一貫していることを確認します
• 最小トークン数以上をキャッシュしていることを検証します
• システムは以前のコンテンツブロック境界でキャッシュヒットを自動的にチェックします（ブレークポイントの前の最大約20ブロック）。20を超えるコンテンツブロックを持つプロンプトの場合、すべてのコンテンツがキャッシュされるようにするために、プロンプトの早い段階で追加の cache_control パラメータが必要になる場合があります
• tool_use コンテンツブロック内のキーが安定した順序を持っていることを確認します。一部の言語（例：Swift、Go）はJSON変換時にキーの順序をランダム化し、キャッシュを破壊します

思考ブロックでのキャッシング

拡張思考をプロンプトキャッシングと一緒に使用する場合、思考ブロックには特別な動作があります：

他のコンテンツと一緒の自動キャッシング：思考ブロックは cache_control で明示的にマークすることはできませんが、ツール結果を使用して後続のAPI呼び出しを行う際に、リクエストコンテンツの一部としてキャッシュされます。これは、会話を続行するために思考ブロックを返すツール使用時に一般的に発生します。

入力トークンのカウント：思考ブロックがキャッシュから読み取られると、使用量メトリクスで入力トークンとしてカウントされます。これはコスト計算とトークンバジェットにとって重要です。

キャッシュ無効化パターン：

• ユーザーメッセージとしてツール結果のみが提供される場合、キャッシュは有効なままです
• 非ツール結果のユーザーコンテンツが追加されると、キャッシュが無効になり、以前のすべての思考ブロックが削除されます
• このキャッシング動作は、明示的な cache_control マーカーがなくても発生します

キャッシュの無効化の詳細については、キャッシュを無効にするものを参照してください。

ツール使用の例：

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2はリクエストコンテンツをキャッシュします（レスポンスではありません）
# キャッシュには以下が含まれます：ユーザーメッセージ、thinking_block_1、tool_use block 1、tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# 非ツール結果のユーザーブロックにより、すべての思考ブロックが無視されます
# このリクエストは、思考ブロックが存在しなかったかのように処理されます

非ツール結果のユーザーブロックが含まれると、新しいアシスタントループが指定され、以前のすべての思考ブロックがコンテキストから削除されます。

より詳細な情報については、拡張思考ドキュメントを参照してください。

キャッシュの保存と共有

• 組織の分離：キャッシュは組織間で分離されています。異なる組織は、同一のプロンプトを使用しても、キャッシュを共有することはありません。

• 完全一致：キャッシュヒットには、キャッシュコントロールでマークされたブロックを含むまでのすべてのテキストと画像を含む、100%同一のプロンプトセグメントが必要です。

• 出力トークンの生成：プロンプトキャッシングは出力トークンの生成に影響しません。受け取るレスポンスは、プロンプトキャッシングが使用されなかった場合に得られるものと同一です。

1時間キャッシュ期間

5分では短すぎる場合、Anthropicは追加コストで1時間のキャッシュ期間も提供しています。

拡張キャッシュを使用するには、cache_control 定義に ttl を含めます：

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

レスポンスには以下のような詳細なキャッシュ情報が含まれます：

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

現在の cache_creation_input_tokens フィールドは、cache_creation オブジェクト内の値の合計に等しいことに注意してください。

1時間キャッシュを使用するタイミング

定期的な頻度で使用されるプロンプト（5分以上の頻度で使用されるシステムプロンプトなど）がある場合は、追加料金なしで更新され続ける5分キャッシュを引き続き使用してください。

1時間キャッシュは以下のシナリオで最適に使用されます：

• 5分未満の頻度では使用されないが、1時間に1回以上の頻度で使用されるプロンプトがある場合。例えば、エージェントのサブエージェントが5分以上かかる場合や、ユーザーとの長いチャット会話を保存していて、そのユーザーが次の5分以内に応答しない可能性がある場合。
• レイテンシーが重要で、フォローアップのプロンプトが5分を超えて送信される可能性がある場合。
• キャッシュヒットはレート制限から差し引かれないため、レート制限の利用率を改善したい場合。

異なるTTLの混合

同じリクエストで1時間と5分の両方のキャッシュコントロールを使用できますが、重要な制約があります：TTLが長いキャッシュエントリは、短いTTLの前に表示される必要があります（つまり、1時間のキャッシュエントリは5分のキャッシュエントリの前に表示される必要があります）。

TTLを混合する場合、プロンプト内の3つの課金位置を決定します：

1. 位置 A：最も高いキャッシュヒットのトークン数（ヒットがない場合は0）。
2. 位置 B：A の後の最も高い1時間 cache_control ブロックのトークン数（存在しない場合は A と等しい）。
3. 位置 C：最後の cache_control ブロックのトークン数。

課金される内容：

1. A のキャッシュ読み取りトークン。
2. (B - A) の1時間キャッシュ書き込みトークン。
3. (C - B) の5分キャッシュ書き込みトークン。

以下に3つの例を示します。これは3つのリクエストの入力トークンを示しており、それぞれ異なるキャッシュヒットとキャッシュミスがあります。結果として、色付きのボックスに示されているように、それぞれ異なる計算された料金になります。

プロンプトキャッシュの例

プロンプトキャッシュの使い方を理解していただくために、詳細な例とベストプラクティスを含むプロンプトキャッシュクックブックを用意しています。

以下に、さまざまなプロンプトキャッシュパターンを紹介するコードスニペットをいくつか掲載しています。これらの例は、さまざまなシナリオでキャッシュを実装する方法を示しており、この機能の実用的な活用方法を理解するのに役立ちます：

FAQ