Claude Opus 5 徹底検証

プロンプトキャッシュは、APIに毎回送る「同じ前置き」をサーバー側に覚えさせておいて、2回目以降は読み直す手間を省く仕組みです。

### なぜ必要になるのか

AIのAPIはステートレス、つまり毎回のリクエストが完全に独立しています。会話を続けたいなら、これまでのやりとり全部を毎回送り直さなければいけません。同じように、長いシステムプロンプトや、参照させたいマニュアル、コードベースの説明といった「毎回変わらない部分」も、リクエストごとに丸ごと送ることになります。

ここで問題になるのが料金と速度です。入力トークンは送った分だけ課金されるので、5万トークンのマニュアルを100回参照させたら、500万トークン分の請求が来ます。しかも毎回そのマニュアルを読み込む時間がかかるので、最初の応答が返ってくるまでの待ち時間も伸びます。

プロンプトキャッシュは、この「毎回変わらない部分」に印をつけて、サーバー側に一時保存させる機能です。2回目以降のリクエストでは、保存済みの部分を読み直す代わりにキャッシュから引くので、料金が約10分の1になり、応答も速くなります。

### 仕組み：前方一致という大前提

ここが最も重要で、かつ最もつまずきやすいところです。

プロンプトキャッシュは**前方一致**でしか働きません。プロンプトの先頭から数えて、1バイトでも違いが出た瞬間、それ以降のキャッシュは全部無効になります。

レンダリング順序は tools → system → messages の順です。つまりツール定義がいちばん先頭に来て、次にシステムプロンプト、最後に会話履歴が並びます。

この性質から、実務上のルールが導かれます。

- **変わらないものを前に、変わるものを後ろに置く**。システムプロンプトの冒頭に「現在時刻: 2026-07-25 14:32:11」などを埋め込むと、リクエストごとに先頭が変わるので、その後ろにある全部がキャッシュされません
- **ツール定義を途中で変えない**。ツールは先頭にレンダリングされるので、1つ足すだけでキャッシュが丸ごと吹き飛びます
- **モデルを途中で切り替えない**。キャッシュはモデルごとに別管理です
- **JSONのシリアライズを固定する**。json.dumps() をソートなしで使うと、キーの順序が実行ごとに変わってバイト列が変わることがあります

### 料金の考え方

キャッシュは無料ではありません。3種類の値段があります。

| 種別 | 料金 |
|---|---|
| キャッシュへの書き込み | 通常の入力料金の1.25倍（5分TTL）/ 2倍（1時間TTL） |
| キャッシュからの読み出し | 通常の入力料金の約0.1倍 |
| キャッシュなしの入力 | 通常料金 |

5分TTLなら2回目で損益分岐します（1.25 + 0.1 = 1.35 対 キャッシュなし2回分の2.0）。1時間TTLは書き込みが2倍になるので、3回以上使わないと元が取れません（2.0 + 0.2 = 2.2 対 3.0）。

つまり「1回しか投げないプロンプト」にキャッシュをつけるのは純粋な損です。逆に、同じ前置きを何度も使い回すなら効果は大きいです。

### 最小トークン数の壁

キャッシュできる最小の長さはモデルごとに違います。しかもこれが世代順に並んでいないので、要注意です。

| モデル | 最小トークン数 |
|---|---|
| Claude Opus 5 / Fable 5 | 512 |
| Claude Opus 4.8 / Sonnet 5 / Sonnet 4.6 | 1024 |
| Claude Opus 4.7 | 2048 |
| Claude Opus 4.6 / Haiku 4.5 | 4096 |

これを下回るプロンプトは、cache_control をつけてもエラーにならず、ただ黙ってキャッシュされません。「印はつけたのに安くならない」と悩む原因の多くがこれです。

### 効いているかどうかの確認方法

レスポンスの usage を見ます。

- cache_creation_input_tokens — 今回キャッシュに書き込んだ量（1.25倍払った分）
- cache_read_input_tokens — 今回キャッシュから読んだ量（0.1倍で済んだ分）
- input_tokens — キャッシュに載らず通常料金だった分

同じプロンプトを繰り返し投げているのに cache_read_input_tokens がずっと0なら、どこかに「毎回変わる何か」が混ざっています。上に挙げた無効化要因を上から順に潰していくのが定石です。

なお input_tokens はキャッシュされなかった残りだけを指します。プロンプト全体の大きさは3つの合計です。「長時間動かしたのに input_tokens が4000しかない」と驚くケースは、残りがキャッシュから読まれていたということです。

### 最初にやるべきこと

いちばん簡単なのは、リクエストのトップレベルに cache_control を1つ置く方法です。これで「キャッシュ可能な最後のブロック」が自動的にキャッシュされます。細かい配置を考える必要がありません。

    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=16000,
        cache_control={"type": "ephemeral"},
        system="（長い共通プロンプト）",
        messages=[{"role": "user", "content": "質問"}],
    )

慣れてきたら、ブロック単位で cache_control を置いて、セッション単位・会話単位で区切りを作っていく形に発展させられます。ブレークポイントは1リクエストあたり最大4つまでです。