プロンプトキャッシュ徹底解説 — 同じコンテキストを毎回全額で読み直すのをやめる
エージェントループを回したり、同じ長いシステムプロンプトを毎回送ったりしているなら、あなたは一瞬前に読んだばかりのテキストをモデルに読み直させるために、入力の全額を払っている。プロンプトキャッシュはそれを直す。プロバイダがプロンプトのプレフィックスを保存し、次の呼び出しでは全額ではなくその一部だけで読み出す。
仕組み自体は単純だが、課金には多くの記事が飛ばす「ひねり」がある——そしてそのひねりこそ、プロンプトをどう構成するかを気にすべき理由だ。
要点だけ
- キャッシュ読み込み（ヒット）：最低 0.1x の入力レート。キャッシュ済み部分が約90%オフ。
- キャッシュ書き込み：一度だけ割増（Anthropicの5分ウィンドウで約 1.25x）。
- だからキャッシュが得になるのは同じプレフィックスが呼び出し間で再利用されるとき——最初のヒットで書き込み分の元は取れる。静的を前、動的を後ろ、プレフィックスはバイト単位で不変に。
- byesuではキャッシュがそのまま透過され、公式アップストリームで 0.1x の読み込みが得られる。
課金のひねり：書き込みは「高く」、読み込みは「はるかに安い」
キャッシュエントリの料金は1つではなく2つある。
| イベント | 何が起きるか | Anthropic公式の構造 |
|---|---|---|
| キャッシュ書き込み | プレフィックスが保存される（初回、または期限切れ後） | 約 1.25x の入力レート（5分TTL）、1時間TTLは約2x |
| キャッシュ読み込み（ヒット） | 後続の呼び出しが保存済みプレフィックスを再利用 | 0.1x の入力レート |
| 未キャッシュ入力 | キャッシュ済みプレフィックスより後ろの全部 | 1x（通常の入力） |
書き込み割増があるからこそ「とにかく全部キャッシュしろ」は誤りだ。キャッシュエントリを書いて二度と読まなければ、キャッシュしなかった場合より高くつく。計算が合うのは、その割増を取り返せるだけプレフィックスが読まれたときだけ：
最初の再利用ですでに元が取れる。 書き込みは通常の読み込みより約25%高い（1.25x 対 1x）が、1回のキャッシュヒットで 0.9x（0.1x 対 1x）節約でき、その割増を十分に上回る。つまり2回目の呼び出しから得になり、以降のヒットはキャッシュ済みトークンが約90%オフ。同じシステムプロンプトとツール定義を20回ループするエージェントなら、これは誤差ではなく構造的な大幅コスト削減になる。
byesuは読み込み部分を最低 0.1x で課金し、この公式構造をそのまま踏襲する——ゲートウェイがキャッシュに上乗せしないので、コスト効率は直接叩くのと同じだ。
なぜエージェントループが理想的なのか
プロンプトキャッシュは同一プレフィックスの繰り返しに報いる。次の3つがこのパターンに強く当てはまる：
- エージェント / ツールループ — Claude Code、Codex、自作のReActエージェント。各ステップが同じシステムプロンプト、同じツールスキーマ、伸びていく会話を再送する。静的な先頭は毎ターン同一 → キャッシュされる。
- 長文ドキュメントQ&A — 50ページの契約書や大きなコードベースを一度貼り、それに対して10問投げる。ドキュメントがプレフィックス、変わるのは質問だけ。
- 大量分類 / 抽出 — 大きな指示ブロック＋few-shotは不変、変わるのは入力行だけ。
いずれも高い部分（長く安定した先頭）が一度書かれて何度も読まれる。まさにキャッシュが設計された形だ。
実際の有効化
Claudeモデル — 明示的な cache_control 境界
Anthropicのキャッシュはコンテンツブロック単位のオプトイン。安定プレフィックスの終端を境界で示すと、そこまでがキャッシュキーになる。
import anthropic
client = anthropic.Anthropic(
base_url="https://byesu.com", # ゲートウェイ；キャッシュは透過する
api_key="sk-your-own-key",
)
resp = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system=[
{
"type": "text",
"text": LONG_STABLE_INSTRUCTIONS, # 大きくて変わらないシステムプロンプト
"cache_control": {"type": "ephemeral"}, # <-- 境界：ここまでをキャッシュ
}
],
messages=[{"role": "user", "content": todays_question}], # 変わるのはここだけ
)
print(resp.usage) # cache_creation_input_tokens / cache_read_input_tokensヒットを左右するルール：
- 順序が効く。 キャッシュ対象プレフィックスは、変わるものより前に置く。静的なシステムプロンプトとツール定義を先に、変化するユーザーターンを最後に。タイムスタンプやリクエスト別IDがプレフィックスの中にあると、毎回キーが変わり「書いて二度と読まない」最悪ケースになる。
- バイト単位で同一。 プレフィックスは一字一句完全一致が必要。JSONキーの並べ替え、空白の削り、日付文字列の違い——どれ一つでキャッシュが外れる。
- 最小サイズ。 キャッシュ可能なプレフィックスは概ね1024トークン以上（最小モデルはもう少し必要）。それ未満はキャッシュするものがない。
- TTLは都度延長される。 既定ウィンドウは約5分で、ヒットのたびに更新される。安定した呼び出しの流れがあればエントリは温まり続け、TTLを超える空白があれば次の呼び出しで再び書き込みを払う。
OpenAIモデル（GPT-5.6 / GPT-5.5）— 自動
OpenAIは約1024トークン超のプロンプトを自動でキャッシュする——境界指定は不要。直近リクエストの最長共通プレフィックスに一致させ、キャッシュ済みトークンを割り引く。Claudeとの違いが2つある：書き込み割増がない（キャッシュ作成は無料なので無駄になりようがない）、そして読み込みの割引はClaudeの0.1xより小さい——節約はできるが90%オフではない。やるべきことは同じ規律：静的なコンテンツを前方に、安定させ、変わるものを末尾に流す。効果は prompt_tokens_details.cached_tokens に出る。
本当に当たっているか確認する
推測せず、usageオブジェクトを読む：
| プロバイダ | 書き込みフィールド | 読み込み（ヒット）フィールド |
|---|---|---|
| Claude | cache_creation_input_tokens | cache_read_input_tokens |
| OpenAI | (暗黙) | prompt_tokens_details.cached_tokens |
2回目の同一呼び出しで cache_read_input_tokens（または cached_tokens）が0なら、プレフィックスのどこかが安定していない——節約を信じる前に、動いている箇所を突き止めること。
ゲートウェイ経由ではキャッシュが静かに壊れうる — ここでは壊れない
これがゲートウェイ固有で知っておく価値のある点だ。一部のアグリゲータはリクエストを書き換える——フィールドを並べ替え、cache_control を落とし、リクエスト別ヘッダをプロンプト本文に差し込む——そしてプレフィックス一致を静かに壊す。答えは返るが、キャッシュには当たらず毎回全額を払い、エラーは何も出ない。
byesuは cache_control とキャッシュトークンのusageフィールドを公式アップストリームへそのまま透過するので、自分が組み立てたキャッシュキーがそのまま使われる。直接叩くのと同じ0.1xの読み込みが、同じ公式モデルで、ダウングレードなしに得られる。倍率の仕組みは料金と課金を参照。
FAQ
キャッシュヒットでどれくらい安くなりますか？
キャッシュ済み部分は入力レートの最低 0.1x、つまりそのトークンが約90%オフで課金される。書き込みには一度だけ割増（5分ウィンドウで約1.25x）がかかるが、最初のキャッシュヒットで元が取れるため、2回目の呼び出しから節約に転じる。
コードを変える必要がありますか？
Claudeはキャッシュしたいブロックに cache_control 境界を付け、その手前をバイト単位で同一に保つ。OpenAI系は約1024トークン超で自動——静的なコンテンツを前方に置くだけ。
byesu経由でもキャッシュは効きますか？
効く。byesuは cache_control とキャッシュトークンのusageフィールドを公式アップストリームへそのまま透過するので、同じコスト効率——読み込みは公式構造どおり最低 0.1x——が得られる。
効いているか確認するには？
レスポンスの cache_read_input_tokens（Claude）または prompt_tokens_details.cached_tokens（OpenAI）を見る。繰り返し呼び出しで0なら、プレフィックスが安定していないか、キャッシュ対象の位置が動いている。
キャッシュ倍率はbyesuが透過する公式アップストリームの課金構造を示す。コンソールにはリクエストごとの実課金額が表示される。参考として引用した各社の公式レートはそれぞれの提供元に帰属する。