プロンプトキャッシング

プロンプトキャッシングは、プロンプト内の特定のプレフィックスから再開することで、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-sonnet-4-5",
    "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."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
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分です。キャッシュされたコンテンツが使用されるたびに、追加コストなしでキャッシュが更新されます。

価格設定

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

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

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

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

• 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
• Claude Opus 3 (非推奨)

プロンプトの構造化

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

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

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

静的コンテンツの終わりに1つのキャッシュブレークポイントを使用でき、システムは自動的にキャッシュされたブロックの最長マッチングシーケンスを見つけます。これがどのように機能するかを理解することは、キャッシング戦略を最適化するのに役立ちます。

3つの核となる原則：

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

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

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

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

30個のコンテンツブロックを持つ会話を考えてください。ここで、cache_controlをブロック30にのみ設定します：

• 前のブロックに変更がなくブロック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.5の場合4096トークン
• Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4.5、Claude Sonnet 4、Claude Sonnet 3.7（非推奨）、Claude Opus 3（非推奨）の場合1024トークン
• Claude Haiku 4.5の場合4096トークン
• Claude Haiku 3.5（非推奨）およびClaude Haiku 3の場合2048トークン

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

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

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

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

キャッシュブレークポイント自体はコストを追加しません。 以下の場合にのみ課金されます：

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

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

キャッシュできるもの

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

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

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

キャッシュできないもの

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

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

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

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

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

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

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

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

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

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

これらのAPI応答フィールドを使用してキャッシュパフォーマンスを監視します。応答内のusage内（またはストリーミングの場合はmessage_startイベント）：

• 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マーカーがなくても発生します

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

ツール使用の例：

リクエスト1：ユーザー：「パリの天気は？」
応答：[thinking_block_1] + [tool_use block 1]

リクエスト2：
ユーザー：[「パリの天気は？」]、
アシスタント：[thinking_block_1] + [tool_use block 1]、
ユーザー：[tool_result_1、cache=True]
応答：[thinking_block_2] + [text block 2]
# リクエスト2はリクエストコンテンツをキャッシュします（応答ではなく）
# キャッシュには以下が含まれます：ユーザーメッセージ、thinking_block_1、tool_use block 1、tool_result_1

リクエスト3：
ユーザー：[「パリの天気は？」]、
アシスタント：[thinking_block_1] + [tool_use block 1]、
ユーザー：[tool_result_1、cache=True]、
アシスタント：[thinking_block_2] + [text block 2]、
ユーザー：[テキスト応答、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時間ごとより頻繁に使用される可能性があるプロンプトがある場合。例えば、エージェンティック副エージェントが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