プロンプトキャッシング

自動キャッシングでは、システムは最後のキャッシュ可能なブロックまでのすべてのコンテンツをキャッシュします。同じプレフィックスを持つ後続のリクエストでは、キャッシュされたコンテンツが自動的に再利用されます。

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

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

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

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

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

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

価格設定

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

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

プロンプトキャッシング（自動と明示的の両方）は、すべてのアクティブなClaudeモデルでサポートされています。

自動キャッシング

自動キャッシングは、プロンプトキャッシングを有効にする最も簡単な方法です。個別のコンテンツブロックにcache_controlを配置する代わりに、リクエストボディのトップレベルに単一のcache_controlフィールドを追加します。システムは自動的にキャッシュブレークポイントを最後のキャッシュ可能なブロックに適用します。

複数ターン会話での自動キャッシングの仕組み

自動キャッシングでは、会話が成長するにつれてキャッシュポイントが自動的に前に移動します。各新しいリクエストは最後のキャッシュ可能なブロックまでのすべてをキャッシュし、以前のコンテンツはキャッシュから読み取られます。

キャッシュブレークポイントは各リクエストの最後のキャッシュ可能なブロックに自動的に移動するため、会話が成長するにつれてcache_controlマーカーを更新する必要はありません。

TTLサポート

デフォルトでは、自動キャッシングは5分のTTLを使用します。基本入力トークン価格の2倍で1時間のTTLを指定できます：

ブロックレベルのキャッシングとの組み合わせ

自動キャッシングは明示的なキャッシュブレークポイントと互換性があります。一緒に使用する場合、自動キャッシュブレークポイントは4つの利用可能なブレークポイントスロットの1つを使用します。

これにより、両方のアプローチを組み合わせることができます。たとえば、明示的なブレークポイントを使用してシステムプロンプトとツールを独立してキャッシュし、自動キャッシングが会話を処理します：

変わらないもの

自動キャッシングは同じ基盤となるキャッシングインフラストラクチャを使用します。価格設定、最小トークン閾値、コンテキスト順序要件、および20ブロックのルックバックウィンドウはすべて、明示的なブレークポイントと同じように適用されます。

エッジケース

• 最後のブロックが同じTTLで明示的なcache_controlを既に持っている場合、自動キャッシングは何もしません。
• 最後のブロックが異なるTTLで明示的なcache_controlを持っている場合、APIは400エラーを返します。
• 4つの明示的なブロックレベルのブレークポイントが既に存在する場合、APIは400エラーを返します（自動キャッシング用のスロットがありません）。
• 最後のブロックが自動キャッシュブレークポイントターゲットとして適格でない場合、システムは静かに後ろに歩いて最も近い適格なブロックを見つけます。見つからない場合、キャッシングはスキップされます。

明示的なキャッシュブレークポイント

キャッシングをより細かく制御するために、個別のコンテンツブロックに直接cache_controlを配置できます。これは、異なる頻度で変わるさまざまなセクションをキャッシュする必要がある場合、または何がキャッシュされるかについて細かく制御する必要がある場合に便利です。

プロンプトの構造化

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

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

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

最後の静的コンテンツの終わりに1つのキャッシュブレークポイントを使用でき、システムは自動的に前のリクエストがすでにキャッシュに書き込んだ最長のプレフィックスを見つけます。これがどのように機能するかを理解することは、キャッシング戦略を最適化するのに役立ちます。

3つの中核原則：

1. キャッシュ書き込みはブレークポイントでのみ発生します。 ブロックをcache_controlでマークすると、正確に1つのキャッシュエントリが書き込まれます：そのブロックで終わるプレフィックスのハッシュです。システムは以前の位置のエントリを書き込みません。ハッシュは累積的であり、ブレークポイントまでのすべてをカバーするため、ブレークポイント以前のブロックを変更すると、次のリクエストで異なるハッシュが生成されます。

2. キャッシュ読み取りは前のリクエストが書き込んだエントリを後ろに探します。 各リクエストで、システムはブレークポイントでプレフィックスハッシュを計算し、一致するキャッシュエントリを確認します。存在しない場合、1ブロックずつ後ろに歩いて、各以前の位置でプレフィックスハッシュが既にキャッシュに存在するものと一致するかどうかを確認します。これは安定したコンテンツを探しているのではなく、前の書き込みを探しています。

3. ルックバックウィンドウは20ブロックです。 システムはブレークポイントあたり最大20の位置をチェックし、ブレークポイント自体を最初としてカウントします。そのウィンドウ内で一致するエントリが見つからない場合、チェックは停止します（または、別の明示的なブレークポイントがある場合は、そこから再開します）。

例：成長する会話でのルックバック

各ターンで新しいブロックを追加し、各リクエストの最後のブロックにcache_controlを設定します：

• ターン1： 10ブロック、ブロック10のブレークポイント。前のキャッシュエントリは存在しません。システムはブロック10にエントリを書き込みます。
• ターン2： 15ブロック、ブロック15のブレークポイント。ブロック15にはエントリがないため、システムはブロック10に戻ってターン1のエントリを見つけます。ブロック10でキャッシュヒット；システムはブロック11から15までのみを新たに処理し、ブロック15に新しいエントリを書き込みます。
• ターン3： 35ブロック、ブロック35のブレークポイント。システムは20の位置（ブロック35から16）をチェックして何も見つかりません。ターン2のエントリはウィンドウの外側の1つの位置にあるため、キャッシュヒットはありません。ブロック15に2番目のブレークポイントを追加すると、そこで2番目のルックバックウィンドウが開始され、ターン2のエントリが見つかります。

一般的な間違い：毎回変わるコンテンツのブレークポイント

プロンプトには大きな静的システムコンテキスト（ブロック1から5）があり、その後にタイムスタンプとユーザーメッセージを含むリクエストごとのブロック（ブロック6）があります。ブロック6にcache_controlを設定します：

• リクエスト1： ブロック6でキャッシュ書き込み。ハッシュにはタイムスタンプが含まれます。
• リクエスト2： タイムスタンプが異なるため、ブロック6でのプレフィックスハッシュが異なります。ルックバックはブロック5、4、3、2、1を通過しますが、システムはこれらの位置のいずれにもエントリを書き込みませんでした。キャッシュヒットなし。毎回新しいキャッシュ書き込みに対して支払い、読み取りを取得しません。

ルックバックはブレークポイントの後ろの安定したコンテンツを見つけてキャッシュしません。前のリクエストが既に書き込んだエントリを見つけ、書き込みはブレークポイントでのみ発生します。cache_controlをブロック5（リクエスト全体で同じままのブロック）に移動すると、その後のすべてのリクエストがキャッシュされたプレフィックスを読み取ります。自動キャッシングは同じ罠に陥ります：ブレークポイントを最後のキャッシュ可能なブロックに配置しますが、この構造ではリクエストごとに変わるブロックなので、代わりにブロック5の明示的なブレークポイントを使用します。

重要なポイント： cache_controlを、共有したいリクエスト全体でプレフィックスが同じ最後のブロックに配置します。成長する会話では、各ターンが20ブロック未満を追加する限り、最後のブロックは機能します：以前のコンテンツは変わらないため、次のリクエストのルックバックは前の書き込みを見つけます。タイムスタンプ、リクエストごとのコンテキスト、受信メッセージを含む変動するサフィックスを持つプロンプトの場合、ブレークポイントを変動するブロックではなく、静的プレフィックスの終わりに配置します。

複数のブレークポイントを使用する場合

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

• 異なる頻度で変わるセクションをキャッシュする（たとえば、ツールはめったに変わりませんが、コンテキストは毎日更新されます）
• 何がキャッシュされるかについてより細かく制御する
• 成長する会話がブレークポイントを最後のキャッシュ書き込みから20ブロック以上先に押し出すときにキャッシュヒットを確保する

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

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

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

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

キャッシング戦略と考慮事項

キャッシュの制限

最小キャッシュ可能プロンプト長は：

• Claude Mythos Preview、Claude Opus 4.6、Claude Opus 4.5の場合は4096トークン
• Claude Sonnet 4.6の場合は2048トークン
• 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でマークされていても、キャッシュできません。この数より少ないトークンをキャッシュするリクエストは、キャッシングなしで処理され、エラーは返されません。プロンプトがキャッシュされたかどうかを確認するには、レスポンス使用フィールドを確認します：cache_creation_input_tokensとcache_read_input_tokensの両方が0の場合、プロンプトはキャッシュされませんでした（おそらく最小長要件を満たさなかったため）。

プロンプトが使用しているモデルの最小値をわずかに下回る場合、キャッシュされたコンテンツを拡張して閾値に達することは、多くの場合価値があります。キャッシュ読み取りはキャッシュされていない入力トークンよりも大幅に低コストなので、最小値に達することは頻繁に再利用されるプロンプトのコストを削減できます。

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

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

キャッシュできるもの

リクエスト内のほとんどのブロックはキャッシュできます。これには以下が含まれます：

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

これらの各要素は、自動的に、またはそれらをcache_controlでマークすることでキャッシュできます。

キャッシュできないもの

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

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

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

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

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

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

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

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

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

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

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

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

シンキングブロックを使用したキャッシング

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

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

入力トークンカウント: シンキングブロックがキャッシュから読み込まれる場合、使用メトリクスの入力トークンとしてカウントされます。これはコスト計算とトークン予算に重要です。

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

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

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

ツール使用の例:

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

詳細については、拡張シンキングドキュメントを参照してください。

キャッシュストレージと共有

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

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

• 出力トークン生成: プロンプトキャッシングは出力トークン生成に影響を与えません。受け取るレスポンスは、プロンプトキャッシングが使用されていない場合と同じになります。

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

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

• マルチターン会話には自動キャッシングから始めてください。ブレークポイント管理を自動的に処理します。
• 異なるセクションを異なる変更頻度でキャッシュする必要がある場合は、明示的なブロックレベルのブレークポイントを使用してください。
• システム指示、背景情報、大規模なコンテキスト、または頻繁なツール定義など、安定した再利用可能なコンテンツをキャッシュしてください。
• キャッシュされたコンテンツをプロンプトの最初に配置して、最高のパフォーマンスを実現してください。
• キャッシュブレークポイントを戦略的に使用して、異なるキャッシュ可能なプレフィックスセクションを分離してください。
• ブレークポイントをリクエスト全体で同じままのラストブロックに配置してください。静的なプレフィックスと変動するサフィックス(タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ)を持つプロンプトの場合、それはプレフィックスの終わりであり、変動するブロックではありません。
• キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整してください。

異なるユースケースに対する最適化

シナリオに合わせてプロンプトキャッシング戦略をカスタマイズしてください:

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

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

予期しない動作が発生している場合:

• キャッシュされたセクションが呼び出し全体で同一であることを確認してください。明示的なブレークポイントの場合、cache_controlマーカーが同じ場所にあることを確認してください
• 呼び出しがキャッシュライフタイム内(デフォルトでは5分)で行われていることを確認してください
• tool_choiceと画像の使用が呼び出し間で一貫していることを確認してください
• 使用しているモデルのトークンの最小数をキャッシュしていることを確認してください(キャッシュの制限を参照)。長さベースのキャッシング失敗はサイレントです: リクエストは成功しますが、cache_creation_input_tokensとcache_read_input_tokensの両方が0になります
• ブレークポイントがリクエスト全体で同じままのブロック上にあることを確認してください。キャッシュ書き込みはブレークポイントでのみ発生し、そのブロックが変更される場合(タイムスタンプ、リクエストごとのコンテキスト、受信メッセージ)、プレフィックスハッシュは一致しません。ルックバックはブレークポイントの背後にある安定したコンテンツを見つけません。それは以前のリクエストが独自のブレークポイントで書き込んだエントリのみを見つけます
• tool_useコンテンツブロック内のキーが安定した順序を持つことを確認してください。一部の言語(例えば、Swift、Go)はJSON変換中にキーの順序をランダム化し、キャッシュを破壊します

1時間のキャッシュ期間

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

拡張キャッシュを使用するには、cache_control定義にttlを含めてください:

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

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

1時間キャッシュを使用する場合

5分ごとより頻繁に使用されるプロンプト(つまり、システムプロンプト)がある場合は、5分キャッシュを引き続き使用してください。これは追加料金なしで引き続き更新されるためです。

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

• 5分ごとより頻繁に使用される可能性があるが、1時間ごとより頻繁に使用される可能性があるプロンプトがある場合。例えば、エージェンティックサイドエージェントが5分以上かかる場合、またはユーザーとの長いチャット会話を保存し、一般的にそのユーザーが次の5分以内に応答しない可能性がある場合。
• レイテンシが重要で、フォローアップのプロンプトが5分を超えて送信される可能性がある場合。
• レート制限の利用を改善したい場合。キャッシュヒットはレート制限に対して差し引かれません。

異なるTTLの混合

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

TTLを混合する場合、APIはプロンプト内の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つのリクエストの入力トークンを示しており、各リクエストは異なるキャッシュヒットとキャッシュミスを持っています。各リクエストは異なる計算された価格を持ち、カラーボックスで示されています。

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

プロンプトキャッシングを始めるのに役立つように、プロンプトキャッシングクックブックには詳細な例とベストプラクティスが記載されています。

以下のコードスニペットは、様々なプロンプトキャッシングパターンを紹介しています。これらの例は、異なるシナリオでキャッシングを実装する方法を示し、この機能の実用的な応用を理解するのに役立ちます。

データ保持

プロンプトキャッシング（自動と明示的の両方）はZDR対象です。Anthropicはプロンプトの生テキストやClaudeの応答を保存しません。

KV（キー値）キャッシュ表現とキャッシュされたコンテンツの暗号化ハッシュはメモリ内にのみ保持され、保存時には保存されません。キャッシュエントリの最小ライフタイムは5分（標準）または60分（拡張）で、その後は迅速に（ただし即座ではなく）削除されます。キャッシュエントリは組織間で分離されます。

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

FAQ