キャッシュの仕組み、価格ティア、TTLの長さ、最小トークン閾値は、Anthropicがプラットフォームを更新するにつれて変わります。サードパーティのガイドにある具体的な数字に頼らないでください。常に公式のプロンプトキャッシュドキュメントとモデルと価格ページで現在の値を確認してください。
プロンプトキャッシュの経済学
Claude APIを呼び出すたびに、送信するすべての入力トークンに対して支払います — システムプロンプト、ツール定義、注入するあらゆるコンテキストを含めて。同じ大きなプレフィックスで何度も呼び出しているなら、毎回そのプレフィックスをゼロから処理する代金を払っていることになります。
プロンプトキャッシュはそれを変えます。プロンプトの安定した部分をキャッシュ可能と印を付けます。最初の呼び出しがそれを処理して保存します。キャッシュにヒットする後続の呼び出しは、その処理をスキップし — それらのトークンについて通常料金のごく一部を払います。
その節約は見せかけではありません。大きく安定したシステムプロンプトや重いコンテキストを持つアプリケーションでは、キャッシュは機能の経済性を「出荷するには高すぎる」から「実質ほぼ無料で動かせる」へと変えられます。
メンタルモデル:安定したプレフィックス、揮発するサフィックス
すべてのAPI呼び出しを2つの部分として考えてください。
安定したプレフィックス — 呼び出しをまたいで変わらないコンテンツ。ここにキャッシュが適用されます。例:
- システムプロンプト
- ツール定義
- 毎回注入する大きな参照文書やコードベース
- 長いフューショットの例ブロック
揮発するサフィックス — 呼び出しごとに変わるコンテンツ。ここにはキャッシュが適用されません。例:
- 現在のユーザーメッセージ
- リクエストごとに注入するリアルタイムデータ
- ターンごとに増えていく会話履歴
ルールはシンプルです。安定したコンテンツが最初に来て、変わるコンテンツが最後に来るようにプロンプトを構成する。 キャッシュの区切り点は位置に基づきます — 印を付けた区切り点より前のものはすべてキャッシュの対象となり、後のものはなりません。
静的なコンテンツの前に動的なコンテンツを置くと、プレフィックスがリクエストごとに変わるため、キャッシュが壊れます。
コストモデルの仕組み
プロンプトキャッシュは、入力トークンの価格付けに3通りの分かれ方を導入します。
| トークンの種類 | いつ発生するか | 通常入力に対するコスト |
|---|---|---|
| キャッシュ書き込み | 最初の呼び出し、またはキャッシュ失効後 | 通常入力より高い |
| キャッシュ読み込み | キャッシュにヒットする後続の呼び出し | 通常入力よりはるかに低い |
| 通常の入力 | 最後のキャッシュ区切り点より後のトークン | 通常料金 |
正確な倍率は公式の価格ページにあり、変動します — 直接確認してください。変わらないのは構造です。書き込みは通常より高く、読み込みははるかに安い。損益分岐点 — 書き込みのオーバーヘッドを回収できるだけキャッシュ呼び出しを重ねた時点 — は、相当量の安定したコンテンツを持つどんなプロンプトでもすぐに訪れます。
レイテンシーも同じパターンに従います。キャッシュ読み込みはキャッシュ部分の完全な処理をスキップするため、大きなプレフィックスを持つ呼び出しで、最初のトークンまでの時間を意味のある形で短縮します。
プロンプトキャッシュが役立つとき
キャッシュが報われるのは、2つの条件が両方とも真のときです。
- 相当量の安定したプレフィックスを持っている(最小トークン閾値があり、それを下回るとキャッシュは利用できません — モデルごとの正確な数字は現在のドキュメントを確認してください)。
- そのプレフィックスが、たまにではなく十分な頻度でキャッシュにヒットするほど再利用される。
キャッシュが自然に適合するシナリオ:
- 文書Q&A — 同じ大きな文書が多くのユーザーの質問に対して注入される。
- コーディングアシスタント — 大きなコードベースやファイルツリーがすべてのリクエストに含まれる。
- エージェント的ループ — 同じシステムプロンプトとツール定義が、多段階ワークフローのすべてのステップで送られる。
- 長い指示を持つ会話エージェント — 呼び出しごとに変わらない、詳細なペルソナ、ルールセット、ナレッジベース。
- バッチ処理 — 多くの入力が同じテンプレートに対して実行される。
プロンプトキャッシュが役立たないとき
キャッシュが役立たないのは、次のときです。
- プロンプトが短い(最小キャッシュ可能トークン閾値を下回る)。
- プレフィックスが呼び出しごとに変わる — タイムスタンプ、ユーザー固有のコンテキスト、あるいは何らかのパーソナライズを「安定した」部分に注入すると、キャッシュが無効になる。
- 呼び出しの頻度が低く、間隔が長い。キャッシュされたコンテンツはTTL(APIがサポートする範囲内で設定できる長さ)の後に失効します。トラフィックがまばらなら、ほとんど書き込みコストを払い、読み込みはわずかになります。
- プレフィックスが、呼び出しごとの動的コンテンツに対して小さい。節約はキャッシュされるものの大きさに比例して増えます。
キャッシュに優しいプロンプトの構成
唯一の構造的要件は順序です。安定したコンテンツは揮発するコンテンツの前に来なければならない。
実際には:
[システムプロンプト — 指示、ペルソナ、ルール]
[ツール定義 — 静的なら]
[大きな注入文書やコンテキスト — 呼び出しをまたいで同じなら]
--------- ここにキャッシュ区切り点 ---------
[呼び出しごとの動的コンテンツ — ユーザーメッセージ、このリクエスト固有の検索チャンク]
区切り点は、キャッシュに含めたい最後のブロックにcache_controlフィールドを付けて印を付けます。その印より前のものはすべてキャッシュの対象であり、後のものはすべて通常の入力です。
単一のリクエストには最大4つの明示的な区切り点を置けます。これは、プロンプトの異なる部分が異なる頻度で変わるときに有用です — 例えば、ツール定義はめったに変わらず、会話履歴は毎ターン変わる、といった場合です。各セクションが自分自身の区切り点を持てます。
キャッシュ無効化のルール
キャッシュは順序に敏感です。キャッシュされたブロックへの変更、またはプロンプト内でそれより前に来る任意のブロックへの変更は、その区切り点とそれ以降のすべての区切り点でキャッシュを無効にします。
ツール定義への変更はすべてのキャッシュを無効にします。システムプロンプトへの変更はシステムとメッセージのキャッシュを無効にします。会話の途中での変更はメッセージキャッシュだけに影響します。
実用上の含意。リクエストごとに変わるものを注入しているなら、それが最後のキャッシュ区切り点より後ろに存在することを絶対に確かめてください。前でもなく、その中でもなく。
事前ウォーミングとモニタリング
ユーザーのトラフィックが来る前に、max_tokens: 0でリクエストを送ることでキャッシュを事前ウォーミングできます — これは出力を生成せずにキャッシュを書き込みます。バッチジョブや、オフピーク時間帯に書き込みコストを前倒しするのに有用です。
APIレスポンスのusageフィールドは、キャッシュから読み込まれたトークン数(cache_read_input_tokens)、キャッシュに書き込まれたトークン数(cache_creation_input_tokens)、そして通常入力として課金されたトークン数を教えてくれます。これらをモニタリングして、キャッシュが実際にヒットしていることを検証し、実現している節約を測定してください。
キャッシュアーキテクチャに踏み切る前に、コスト計算機で期待される節約をモデル化してください。
結論
プロンプトキャッシュはマイクロ最適化ではありません。同じ大きなプレフィックスを繰り返し送るどんなアプリケーションにとっても、それは構造的な経済判断です。それを考えるためのモデルは単純明快です。安定したコンテンツが最初、揮発するコンテンツが最後、境界に区切り点を置く。
APIに対して構築していて、まだキャッシュを見ていないなら、現在のプロンプトに大きな安定セクションがないか確認してください。あれば、キャッシュを有効にするのはたいてい少ない労力で済み、節約は本物です。