メインコンテンツまでスキップ
上級

キャッシュの仕組み、価格ティア、TTLの長さ、最小トークン閾値は、Anthropicがプラットフォームを更新するにつれて変わります。サードパーティのガイドにある具体的な数字に頼らないでください。常に公式のプロンプトキャッシュドキュメントとモデルと価格ページで現在の値を確認してください。

プロンプトキャッシュの経済学

What you'll learn
  • 素朴なAPI呼び出しがなぜ過払いになるのか:同じ安定したプレフィックスが毎回ゼロから処理される
  • メンタルモデル — 安定したプレフィックス、揮発するサフィックス — そしてキャッシュを可能にする唯一の順序ルール
  • 入力価格の3通りの分け方(キャッシュ書き込み、キャッシュ読み込み、通常入力)と、損益分岐点がいつ回収されるか
  • キャッシュが投資を回収する場面と、それが静かに回収しない4つのシナリオ
  • ヒット率が90%になるか0%になるかを決める5つのキャッシュ無効化ルール
  • キャッシュを事前ウォーミングし、usage フィールドを読んで節約が本物であることを証明する方法

Claude APIを呼び出すたびに、送信するすべての入力トークンに対して支払います — システムプロンプト、ツール定義、注入するあらゆるコンテキストを含めて。同じ大きなプレフィックスで何度も呼び出しているなら、毎回そのプレフィックスをゼロから処理する代金を払っていることになります。

プロンプトキャッシュはそれを変えます。プロンプトの安定した部分をキャッシュ可能と印を付けます。最初の呼び出しがそれを処理して保存します。キャッシュにヒットする後続の呼び出しは、その処理をスキップし — それらのトークンについて通常料金のごく一部を払います。

その節約は見せかけではありません。大きく安定したシステムプロンプトや重いコンテキストを持つアプリケーションでは、キャッシュは機能の経済性を「出荷するには高すぎる」から「実質ほぼ無料で動かせる」へと変えられます。

メンタルモデル:安定したプレフィックス、揮発するサフィックス​

すべてのAPI呼び出しを2つの部分として考えてください。

安定したプレフィックス — 呼び出しをまたいで変わらないコンテンツ。ここにキャッシュが適用されます。例:

  • システムプロンプト
  • ツール定義
  • 毎回注入する大きな参照文書やコードベース
  • 長いフューショットの例ブロック

揮発するサフィックス — 呼び出しごとに変わるコンテンツ。ここにはキャッシュが適用されません。例:

  • 現在のユーザーメッセージ
  • リクエストごとに注入するリアルタイムデータ
  • ターンごとに増えていく会話履歴

ルールはシンプルです。安定したコンテンツが最初に来て、変わるコンテンツが最後に来るようにプロンプトを構成する。 キャッシュの区切り点は位置に基づきます — 印を付けた区切り点より前のものはすべてキャッシュの対象となり、後のものはなりません。

静的なコンテンツの前に動的なコンテンツを置くと、プレフィックスがリクエストごとに変わるため、キャッシュが壊れます。

コストモデルの仕組み​

プロンプトキャッシュは、入力トークンの価格付けに3通りの分かれ方を導入します。

トークンの種類いつ発生するか通常入力に対するコスト
キャッシュ書き込み最初の呼び出し、またはキャッシュ失効後通常入力より高い
キャッシュ読み込みキャッシュにヒットする後続の呼び出し通常入力よりはるかに低い
通常の入力最後のキャッシュ区切り点より後のトークン通常料金

正確な倍率は公式の価格ページにあり、変動します — 直接確認してください。変わらないのは構造です。書き込みは通常より高く、読み込みははるかに安い。損益分岐点 — 書き込みのオーバーヘッドを回収できるだけキャッシュ呼び出しを重ねた時点 — は、相当量の安定したコンテンツを持つどんなプロンプトでもすぐに訪れます。

レイテンシーも同じパターンに従います。キャッシュ読み込みはキャッシュ部分の完全な処理をスキップするため、大きなプレフィックスを持つ呼び出しで、最初のトークンまでの時間を意味のある形で短縮します。

プロンプトキャッシュが役立つとき​

キャッシュが報われるのは、2つの条件が両方とも真のときです。

  1. 相当量の安定したプレフィックスを持っている(最小トークン閾値があり、それを下回るとキャッシュは利用できません — モデルごとの正確な数字は現在のドキュメントを確認してください)。
  2. そのプレフィックスが、たまにではなく十分な頻度でキャッシュにヒットするほど再利用される。

キャッシュが自然に適合するシナリオ:

  • 文書Q&A — 同じ大きな文書が多くのユーザーの質問に対して注入される。
  • コーディングアシスタント — 大きなコードベースやファイルツリーがすべてのリクエストに含まれる。
  • エージェント的ループ — 同じシステムプロンプトとツール定義が、多段階ワークフローのすべてのステップで送られる。
  • 長い指示を持つ会話エージェント — 呼び出しごとに変わらない、詳細なペルソナ、ルールセット、ナレッジベース。
  • バッチ処理 — 多くの入力が同じテンプレートに対して実行される。

プロンプトキャッシュが役立たないとき​

キャッシュが役立たないのは、次のときです。

  • プロンプトが短い(最小キャッシュ可能トークン閾値を下回る)。
  • プレフィックスが呼び出しごとに変わる — タイムスタンプ、ユーザー固有のコンテキスト、あるいは何らかのパーソナライズを「安定した」部分に注入すると、キャッシュが無効になる。
  • 呼び出しの頻度が低く、間隔が長い。キャッシュされたコンテンツはTTL(APIがサポートする範囲内で設定できる長さ)の後に失効します。トラフィックがまばらなら、ほとんど書き込みコストを払い、読み込みはわずかになります。
  • プレフィックスが、呼び出しごとの動的コンテンツに対して小さい。節約はキャッシュされるものの大きさに比例して増えます。

キャッシュに優しいプロンプトの構成​

唯一の構造的要件は順序です。安定したコンテンツは揮発するコンテンツの前に来なければならない。

Guided walkthrough1 of 5
  1. 指示、ペルソナ、ルール — ユーザーリクエストごとに変わらない部分。

キャッシュに優しいプロンプトの形

[System prompt — instructions, persona, rules]
[Tool definitions — if static]
[Large injected documents or context — same across calls]
--------- cache breakpoint here ---------
[Dynamic per-call content — user message, retrieved chunks]

区切り点は、キャッシュに含めたい最後のブロックにcache_controlフィールドを付けて印を付けます。その印より前のものはすべてキャッシュの対象であり、後のものはすべて通常の入力です。

単一のリクエストには最大4つの明示的な区切り点を置けます。これは、プロンプトの異なる部分が異なる頻度で変わるときに有用です — 例えば、ツール定義はめったに変わらず、会話履歴は毎ターン変わる、といった場合です。各セクションが自分自身の区切り点を持てます。

キャッシュ無効化のルール​

キャッシュは順序に敏感です。キャッシュされたブロックへの変更、またはプロンプト内でそれより前に来る任意のブロックへの変更は、その区切り点とそれ以降のすべての区切り点でキャッシュを無効にします。

Watch out
  • ツール定義への変更はすべてのキャッシュを無効にする — ツールリストは最大限に安定したものとして扱う。
  • システムプロンプトへの変更はシステムとメッセージのキャッシュを無効にする。
  • 会話の途中での変更はメッセージキャッシュだけに影響する。
  • タイムスタンプ、ユーザーID、リクエストごとのパーソナライズを『安定した』セクションに注入するとヒット率が静かに死ぬ — そのコンテンツは最後の区切り点の後に属する。
  • 空白、句読点、順序はバイト単位で重要 — 『小さな』編集でも無効化される。

実用上の含意。リクエストごとに変わるものを注入しているなら、それが最後のキャッシュ区切り点より後ろに存在することを絶対に確かめてください。前でもなく、その中でもなく。

事前ウォーミングとモニタリング​

ユーザーのトラフィックが来る前に、max_tokens: 0でリクエストを送ることでキャッシュを事前ウォーミングできます — これは出力を生成せずにキャッシュを書き込みます。バッチジョブや、オフピーク時間帯に書き込みコストを前倒しするのに有用です。

APIレスポンスのusageフィールドは、キャッシュから読み込まれたトークン数(cache_read_input_tokens)、キャッシュに書き込まれたトークン数(cache_creation_input_tokens)、そして通常入力として課金されたトークン数を教えてくれます。これらをモニタリングして、キャッシュが実際にヒットしていることを検証し、実現している節約を測定してください。

usage フィールドを読んでキャッシュが機能していることを証明する

# From any Claude API response, inspect response.usage:
{
"usage": {
  "input_tokens": 42,                    # billed at normal rate
  "cache_creation_input_tokens": 0,      # tokens written on this call
  "cache_read_input_tokens": 8912,       # tokens served from cache (cheap)
  "output_tokens": 384
}
}
# Healthy state after warm-up: cache_read >> cache_creation, run over run.
# If cache_creation stays high, something upstream of your breakpoint is changing.

キャッシュアーキテクチャに踏み切る前に、コスト計算機で期待される節約をモデル化してください。

結論​

プロンプトキャッシュはマイクロ最適化ではありません。同じ大きなプレフィックスを繰り返し送るどんなアプリケーションにとっても、それは構造的な経済判断です。それを考えるためのモデルは単純明快です。安定したコンテンツが最初、揮発するコンテンツが最後、境界に区切り点を置く。

APIに対して構築していて、まだキャッシュを見ていないなら、現在のプロンプトに大きな安定セクションがないか確認してください。あれば、キャッシュを有効にするのはたいてい少ない労力で済み、節約は本物です。

自己チェック

0/5
  1. キャッシュを機能させるには、リクエスト内のどこに区切り点が座る必要がありますか？
  2. 通常の入力トークンよりコストが高いのはどれですか？
  3. 『モデルが時間を知る』ために毎回のリクエストの先頭に現在のタイムスタンプを注入します。キャッシュはどうなりますか？
  4. 本番でキャッシュが実際にお金を節約していることをどう証明しますか？
  5. ツール定義の1単語を変えました。何が無効化されますか？
Key takeaways
  • キャッシュは入力価格を3通りに分ける:キャッシュ書き込み(プレミアム)、キャッシュ読み込み(安い)、通常入力(通常) — 見返りはプレフィックスサイズ × 再利用頻度に比例する。
  • キャッシュに優しいプロンプトを形作る1つのルール:安定したコンテンツは区切り点の前、揮発するコンテンツは後 — これを逆にすればキャッシュは毎回死ぬ。
  • 最大4つの区切り点を置けるので、ツール、システムプロンプト、文書、履歴がそれぞれ独自の頻度でキャッシュされる。
  • キャッシュされたブロックへの変更、またはプロンプトのそれより早いブロックへの変更は、その区切り点とそれ以降のすべてを無効にする。
  • usage フィールドの cache_read_input_tokens vs cache_creation_input_tokens で節約を証明し、バッチジョブは max_tokens: 0 で事前ウォーミングする。
  • プレフィックスが短いとき、トラフィックがまばらなとき(キャッシュされたコンテンツは失効する)、またはプレフィックスが呼び出しごとの動的コンテンツに対して小さいときはキャッシュをスキップする。

関連項目​