プロンプトキャッシュ：初回リクエストと繰り返しリクエストのコスト

この検証で測るもの

プロンプトキャッシュは、入力のうち変わらない部分を再処理する量を減らします。対象はシステムプロンプト、指示の集合、大きなドキュメント、固定のストーリーなどです。変更する質問は、共通プレフィックスの後ろに置きます。

検証には 3 つの状態が必要です。

A. first request: stable prefix + question 1
B. cache hit:     stable prefix + question 2
C. cache miss:    changed prefix + question 3

A と B は同じモデル、同じ設定、同じキャッシュポリシーで実行します。C ではキャッシュ対象領域の 1 文字だけを変えるか、TTL が確実に切れた後に実行します。モデル、出力、プロンプト長を同時に変えると、結果をキャッシュだけで説明できません。

自分の usage で式を確認したいですか？ BetterToken アカウントと API Key を作成し、現行レートを料金ページで確認して、同じプレフィックスで初回と繰り返しのリクエストを行えます。次に Dashboard で input、output、該当するキャッシュ Token、消費量を照合し、まずAPI リファレンスとプロバイダーのドキュメントでキャッシュと TTL のルールを確認してください。

OpenAI と Anthropic ではキャッシュの数え方が異なる

同じ「キャッシュ」という言葉でも、同じ仕組みを指すとは限りません。

OpenAI のプロンプトキャッシュ

OpenAI の対応 API とモデルでは、適切なプレフィックスに対してキャッシュが自動的に適用されます。usage には input の詳細内にキャッシュ済み Token が表示されます。通常、コードで別個のキャッシュオブジェクトを作成する必要はありませんが、共通プレフィックスはそのまま保つ必要があります。正確なしきい値、保持期間、割引は、公式 Prompt Caching ページで確認してください。

Anthropic のプロンプトキャッシュ

Anthropic Messages では、cache_control によりキャッシュ境界を指定できます。usage ではキャッシュの作成と読み取りが別々に示されることがあります。最小サイズ、TTL、ブロック順序、コストは現行の契約とモデルによって異なるため、Anthropic 公式ドキュメントで検証が必要です。

2 つのプロトコルの usage フィールド名や係数を相互に流用しないでください。検証表には、現在の endpoint が返した区分だけを正確に記録します。

安定したプレフィックスを準備する

入力を 2 つの部分に分けます。

STABLE_PREFIX
  system instructions
  tool definitions, if they are needed
  unchanged reference document

DYNAMIC_SUFFIX
  current user question

最初の検証では、tools と streaming を外すほうがよいでしょう。これらは自動的にキャッシュを妨げるものではありませんが、usage と出力に変数を増やします。

プレフィックスは、選択したモデルのルールに従って十分な長さでなければなりません。最小しきい値より短い場合、キャッシュヒットがないことは想定どおりの結果です。本番で無意味な文を足して長くしないでください。検証には、実際に問題で繰り返されるドキュメントを使用します。

呼び出し前に、キャッシュ対象部分のハッシュを保存します。

import hashlib

prefix_hash = hashlib.sha256(STABLE_PREFIX.encode("utf-8")).hexdigest()
print(prefix_hash)

ハッシュにより、内容を公開せずに A と B が同一のプレフィックスを受け取ったことを確認できます。

記録するフィールド

各リクエストで次を保存します。

• 時刻と request ID
• モデル ID とプロトコル
• prefix_hash
• 通常の input Token
• 契約で区分される場合はキャッシュ作成／書き込み Token
• 契約で区分される場合はキャッシュ読み取り／キャッシュ済み Token
• output Token
• 実際の消費量
• 診断用フィールドとしての status と latency のみ

latency は価格の証拠ではありません。応答が速くてもキャッシュミスのことがあり、キャッシュヒットでも待ち行列で待つことがあります。コストの結論は usage と料金表に基づいて出します。

初回クエリの式

次のように表します。

I  — regular input tokens
W  — cache write / creation tokens
R  — cache read / cached tokens
O  — output tokens
Pi — regular input price per 1,000,000 tokens
Pw — cache write price per 1,000,000 tokens
Pr — cache read price per 1,000,000 tokens
Po — output price per 1,000,000 tokens

これらの区分を分離する endpoint では、計算は次のとおりです。

cost = I / 1_000_000 × Pi
     + W / 1_000_000 × Pw
     + R / 1_000_000 × Pr
     + O / 1_000_000 × Po

初回リクエストでは、W がゼロより大きくなることがあり、R もゼロより大きくなることがあります。自動キャッシュではフィールドの組み合わせが異なる場合があります。実際の usage にある未キャッシュ input とキャッシュ済み input を使用し、存在しない区分を作らないでください。

キャッシュ作成が別途課金される場合、初回リクエストの価格はキャッシュなしのリクエストより高くなることがあります。これはそれ自体では誤りではありません。十分な回数の読み取りがあって初めて元が取れます。

繰り返しリクエストの式と損益分岐点

次のようにします。

C0 — cost of the first request that creates the cache
Ch — cost of one request with a cache hit
Cu — cost of one comparable request without cache
n  — total number of requests

1 回の作成と n - 1 回のヒットからなる系列は、次の式で表せます。

C_cached(n) = C0 + (n - 1) × Ch
C_uncached(n) = n × Cu

キャッシュが元を取る最小の n は、次の条件を満たす最初の整数です。

C_cached(n) < C_uncached(n)

別モデルの価格を式に代入しないでください。Ch >= Cu なら、現在の設定では節約になりません。キャッシュヒット、プレフィックスサイズ、料金区分を確認してください。

対照となるキャッシュミス

A と B の後に C を実行します。モデルと期待する応答長は維持し、キャッシュ対象のプレフィックスだけを変えます。契約に応じてキャッシュ読み取り区分は減少または消失し、通常の処理またはキャッシュ作成が変化するはずです。

予期しないミスの理由は次のとおりです。

• プレフィックス内の記号または空白が変わった
• tool definitions の順序が異なった
• system block が移動した
• モデルまたは endpoint が変わった
• リクエストが TTL の範囲外になった
• プレフィックスが最小しきい値より短かった
• クライアントが同じデータを異なる順序でシリアライズした

安定したプレフィックスの後ろにある質問を変えることは想定どおりです。プレフィックス内を変えると、異なるキャッシュ ID が作られます。

「ドルでの結果」を公開しない理由

この記事には特定アカウントの API Key や usage へのアクセスがないため、実施したテストの計算済み例は提示しません。価格、モデル、キャッシュルールは変化します。任意の数値を公開すると、再現可能な検証がすぐに古い広告になってしまいます。

自分の結果を得るには、次の手順を行います。

1. モデルとプロトコルを 1 つずつ選ぶ
2. 現在の BetterToken 料金ページを開く
3. A、B、C を実行する
4. Dashboard から usage と消費量を書き写す
5. C0、Ch、Cu と損益分岐点を計算する
6. 確認日と prefix_hash を保存する

FAQ

キャッシュありの初回リクエストが高くなるのはなぜですか？

プロトコルによっては、キャッシュの作成／書き込みを別途課金します。初期の上乗せ分は、繰り返しのキャッシュ読み取りによってのみ回収されます。特定モデルの現在価格を確認してください。

繰り返しリクエストでキャッシュヒットにならなかったのはなぜですか？

プレフィックスの長さと不変性、ブロック順序、モデル、endpoint、TTL、最小しきい値を確認してください。prefix_hash を比較します。

OpenAI と Anthropic を 1 つの usage フィールドで比較できますか？

できません。仕組み、設定、区分名が異なります。元のフィールドを保持したまま、値を独自の I、W、R、O フィールドへ正規化してください。

キャッシュは常にコストを下げますか？

いいえ。短いプレフィックス、まれな繰り返し、頻繁な変更、低いキャッシュヒット率では、キャッシュ作成の費用を回収できない場合があります。

BetterToken の実際の引き落としはどこで確認できますか？

Dashboard で時刻、モデル、request status ごとに確認できます。料金は料金ページから、キャッシュルールは対応するプロトコルのドキュメントから取得してください。