プロンプトキャッシュとは？繰り返されるプロンプトが再利用される仕組み

プロンプトキャッシュとは、APIがリクエストの先頭部分を記憶し、次に同じ先頭部分を送ったときにそれを再利用する仕組みです。毎回テキスト全体を送信しますが、プロバイダーは繰り返される部分を再度読み込む処理を省略でき、一部のプロバイダーはその部分を低い料金で請求します。これはリクエストの先頭にのみ作用し、その先頭が完全に同一である場合に限り機能します。

同じページを何度も読み直し続けるサポートボット#

1日に2,000件のチケットを処理するサポートボットを運用しているとします。各リクエストは同じ3,000トークンで始まります。話し方のトーン、返金ルール、配送ポリシーです。その後に「注文はどこですか？」のような1行の顧客メッセージが続きます。（トークンについてまだ曖昧な場合は、トークンとは何かから始めてください。）

キャッシュなしでは、プロバイダーはチケット1番、2番、そして2,000番のために3,000トークンのルールを毎回読み直します。同じページを2,000回読むわけです。キャッシュありでは、最初のリクエストがそれを読む全額を支払い、同じテキストで始まる後続のリクエストはその処理を再利用できます。

DeepSeekのAPIガイド（2026年10月24日確認）はまさにこれを説明しています。コンテキストキャッシュはデフォルトで有効で、コード変更は不要、プレフィックスが重複する後続のリクエストは「キャッシュヒット」とみなされます。キャッシュされるのは入力のみです。回答は毎回新たに生成されます。

「同じ」とは何か：プレフィックスのルール#

キャッシュは最初の文字から照合します。リクエストがキャッシュされたものと異なった瞬間、それ以降はすべて新規になります。だからこそ、リクエストの順序は長さよりも重要です。

キャッシュを静かに台無しにする間違いがあります。開発者がボットに時刻を知らせたいと考え、それを先頭に置きます。

Current time: 14:03:22
You are a support assistant for a shop...
(3,000 tokens of rules)

時刻は毎秒変わるため、最初の行がリクエストごとに異なり、それ以降は何も一致しません。修正方法は、変化するものを末尾に移動することです。

You are a support assistant for a shop...
(3,000 tokens of rules)
Current time: 14:03:22
Customer: Where is my order?

これで3,000トークンのルールが先頭に来て同一のままになります。同じ論理が他の2つの一般的なケースにも当てはまります。長いチャットは毎ターン履歴全体を再送するため、古いメッセージは既製の繰り返し先頭部分になります（詳細は長いチャットが高くつく理由を参照）。またエージェントは毎ステップでツール定義と指示を繰り返します。

キャッシュはベストエフォートでもあります。DeepSeekによると、キャッシュの構築には数秒かかり、ヒットには既存のキャッシュプレフィックスユニットとの完全一致が必要で、ヒット率は保証されず、未使用のキャッシュは通常数時間から数日以内にクリアされます。そのため、最初のリクエストの0.5秒後に送った2回目のリクエストはまだヒットしない可能性があり、ヒットがプレフィックス全体より少ない範囲しかカバーしないこともあります。

確認方法：usageのキャッシュフィールド#

機能したかどうかを推測する必要はありません。各プロバイダーはレスポンスのusage部分で、独自のフィールド名で報告します。

DeepSeekは2つのフィールドを使用します。

• prompt_cache_hit_tokens — キャッシュで見つかった入力トークン
• prompt_cache_miss_tokens — 見つからなかった入力トークン

最初のサポートチケットがprompt_cache_hit_tokens: 0とprompt_cache_miss_tokens: 3200を返し、1分後のチケットがprompt_cache_hit_tokens: 3000とprompt_cache_miss_tokens: 200を示したとします。3,000トークンのルールが再利用され、新しい顧客メッセージと少数のトークンだけがゼロから読み込まれました。毎回の呼び出しでヒット数がゼロのままなら、リクエストの先頭を確認してください。そこにある何かが変化しています。

Anthropicは仕組みが異なり、キャッシュする対象を自分でマークします。リクエストまたはコンテンツブロックに、typeがephemeralのcache_controlを追加します。

{
  "model": "your-model-id",
  "max_tokens": 300,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant... (long rules)",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Where is my order?"}]
}

Anthropicのプロンプトキャッシュのドキュメント（2026年10月24日確認）によると、レスポンスは3つの数値を報告します。cache_creation_input_tokens（現在キャッシュに書き込まれた）、cache_read_input_tokens（キャッシュから読み込まれた）、input_tokens（最後のキャッシュブレークポイント以降のもの）です。最初の呼び出しがcache_creation_input_tokens: 10000、cache_read_input_tokens: 0を示し、2回目が0と10000を示したとします。これはキャッシュ書き込みの後にキャッシュ読み込みが続いたことを意味します。

画面上の罠が1つあります。モデルの最小値（モデルによって512、1,024、4,096トークン）より短いプロンプトは、キャッシュなしで処理され、エラーも出ません。両方のキャッシュフィールドにゼロが表示され、警告はありません。デフォルトの有効期間は5分で、使用のたびに無料で更新されます。オプションの1hを指定したttlはそれをより長く保持します。

請求額への影響#

キャッシュは繰り返される部分の価格を変えるため、一度計算する価値があります。Anthropicは基本入力価格に対する倍率を公表しています。5分の有効期間でのキャッシュ書き込みは1.25倍、読み込みは0.1倍（Opus 5.5とSonnet 5.5では0.05倍）です。10,000トークンのプレフィックスが5分のウィンドウ内で20回のリクエストで再利用され、標準の0.1倍の読み込みを使用するとします。

10,000 × 20 = 200,000トークン（キャッシュなしの基本価格）

10,000 × 1.25 = 12,500（キャッシュを書き込む最初のリクエスト）

19 × 10,000 × 0.1 = 19,000（それを読み込む19回のリクエスト）

12,500 + 19,000 = 31,500トークン相当（キャッシュあり）

つまり、繰り返される部分のコストはキャッシュなしの5分の1を大きく下回ります。注意点は、リクエスト間で5分が経過すると、次のリクエストが1.25倍でキャッシュを再び書き込み、めったに使われないプレフィックスはキャッシュなしよりも高くつく可能性があることです。

では、冒頭のボットを通常の全額ベースラインとして見てみましょう。1日2,000リクエスト、各3,000入力トークンと約300出力トークンです。

2,000 × 3,000 = 1日6,000,000入力トークン

2,000 × 300 = 1日600,000出力トークン

この表は、その日のワークロードを利用可能なすべてのCheapTokensモデルとOpenRouterで価格設定したものです。

DeepSeek-V4-Flashは入力と出力を合計するとOpenRouterより安く、ワークロードも余裕で収まります。380Kのコンテキストと回答あたり最大32,768出力トークンです。これはワークロードの全額コストです。入力トークン × トークンあたりの価格。長く安定したプレフィックスは、この入力の割合が最も大きくなる場所です。

5分で自分で試す#

計画は、同じ長いシステムプロンプトを異なる質問とともに2回送り、usageを確認することです。support_rules.txtに自分のルールテキストを入れてください（1〜2ページのテキストで十分です）。エンドポイントはOpenAI互換のCheapTokens APIで、キーはアカウントから取得できます。

from openai import OpenAI

client = OpenAI(base_url='https://api.cheaptokens.dev/v1', api_key='YOUR_API_KEY')

SYSTEM = open('support_rules.txt').read()  # long, never changes

for question in ['Where is my order?', 'Can I change the address?']:
    r = client.chat.completions.create(
        model='deepseek-ai/DeepSeek-V4-Flash-0731',
        messages=[
            {'role': 'system', 'content': SYSTEM},
            {'role': 'user', 'content': question},
        ],
        max_tokens=300,
    )
    print(r.usage)

出力で確認すること：prompt_tokensはリクエストの大きさを教えてくれます。両方のリクエストは同じSYSTEMテキストを持つため、その数値のほとんどはリクエスト間で繰り返されます。おおよそルールファイルのサイズです。この繰り返される先頭部分こそ、上記のDeepSeek APIやAnthropicのようなキャッシュを持つプロバイダーが再利用できる部分です。次に順序に関する演習です。SYSTEMの先頭に現在時刻（datetime.now()）を含む行を追加して、もう一度実行してください。2つのリクエストは最初の行から異なるため、先頭部分を共有しなくなります。同じ行をプロンプトの末尾に置けば、共有される先頭部分が戻ります。

自分のプロンプト用の短いチェックリスト：

1. 安定したテキストを先頭に：指示、ルール、ツール定義、例。
2. 変化するテキストを末尾に：日付、ユーザー名、最新のメッセージ。
3. プレフィックスをバイト単位で同一に保つ — 余分なスペース1つでも影響します。
4. 何もキャッシュされない理由を考える前に、プロバイダーの最小サイズを確認する。
5. 変更後ではなく、変更前にusageフィールドを確認する。

自分のワークロードの価格を計算するには、料金ページを開いて入力と出力のサイズを入力するか、DeepSeekページから始めてください。最初のリクエストが機能すれば、同じ見積もりはどんなプロンプトでも1分でできます。リクエストの両側のコストについては、入力トークンと出力トークンを参照してください。