Claude APIのプロンプトキャッシュは、うまく使えば入力トークンのコストを最大90%近く削減できる強力な機能です。しかし「cache_controlを付けたのに全然効いている気配がない」というつまずきも非常によくあります。

本記事では、キャッシュの仕組みを1つの原則から理解した上で、エラーは出ないのに静かに効かなくなる原因を診断できるようになることを目指します。

スポンサーリンク

大原則：プロンプトキャッシュは「前方一致」

プロンプトキャッシュを理解する上で最も重要なのはこの一点です。キャッシュは各ブレークポイントまでの、レンダリングされたバイト列の完全一致で判定される「前方一致」の仕組みです。

レンダリング順序を意識する

リクエストはtools → system → messagesの順でレンダリングされます。この順序を理解した上で、安定した内容を前に、変動する内容を後ろに配置するのが設計の基本方針です。

基本の書き方

自動キャッシュ（迷ったらこれ）

トップレベルのcache_controlを指定すると、リクエスト内で最後にキャッシュ可能なブロックへ自動的に配置されます。細かい制御が不要なら、まずこれで十分です。

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    cache_control={"type": "ephemeral"},
    system="あなたは専門的なアシスタントです...",
    messages=[{"role": "user", "content": "要点をまとめて"}]
)

手動ブレークポイント（最大4箇所）

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=[{
        "type": "text",
        "text": "あなたはこの大規模ドキュメントの専門家です...",
        "cache_control": {"type": "ephemeral"}  # デフォルトは5分TTL
    }],
    messages=[{"role": "user", "content": "要点をまとめて"}]
)

TTLの選択

損益分岐点を理解する

キャッシュ読み取りは通常の約0.1倍、書き込みは5分TTLで1.25倍・1時間TTLで2倍のコストがかかります。ここから、何回読み取れば元が取れるかが逆算できます。

裏を返せば、同じプレフィックスを2回未満しか使わないなら、キャッシュを付けるだけ損です。1回きりのプロンプトにマーカーを付けても、書き込みコストが上乗せされるだけで回収できません。

キャッシュが効かない「サイレントな原因」チェックリスト

ここが本記事の核心です。エラーは一切出ないのに、キャッシュヒット率がゼロのままというケースの典型的な原因を列挙します。

効果測定の方法

レスポンスのusageフィールドには、キャッシュの状態を表す3つの数値が含まれます。

print(response.usage.cache_creation_input_tokens)  # 今回新たに書き込んだトークン数
print(response.usage.cache_read_input_tokens)      # キャッシュから読み取ったトークン数
print(response.usage.input_tokens)                 # キャッシュされていない通常トークン数

知っておくと差がつく上級知識

最小キャッシュ可能サイズはモデルごとに異なる

短いプロンプトは、マーカーを付けても黙ってキャッシュされません（エラーにはならず、cache_creation_input_tokensがゼロになるだけです）。最小サイズはモデルによって異なるため、想定より小さいプロンプトを扱う場合は注意してください。

並列リクエストの罠

キャッシュエントリは、最初のレスポンスのストリーミングが開始してから初めて読み取り可能になります。同一プレフィックスのリクエストをN本同時に並列発射すると、全リクエストがまだ何も書き込まれていない状態でキャッシュミスし、全員がフルプライスを払うことになります。

会話が長い場合のブレークポイント運用

マルチターンの会話では、最新ターンの末尾にブレークポイントを置く運用にすると、会話が伸びるたびに増分でヒット率を積み上げていけます。1つの会話中で多数のツール呼び出しがある場合は、ブレークポイントの20ブロックのルックバック制限にも注意が必要です。1ターンで20ブロックを超えるようなやり取りが多い場合、中間地点にもブレークポイントを置いておくと安全です。

よくある質問

まとめ

マーカーを増やす前に、まずプロンプトを組み立てるコード側が「毎回同じバイト列を生成しているか」を疑ってみてください。多くの場合、原因は設定ではなくコードの中に潜んでいます。