プロンプトキャッシュ実践ガイド — Anthropic APIで入力料金を最大90%削減する設計パターン

プロンプトキャッシュとは何か

LLMアプリケーションを運用していると、ほぼ同じシステムプロンプトや長いコンテキストを 毎回送信していることに気づきます。ツール定義が数千トークン、RAGの参考ドキュメントが数万トークン、 そこに毎回数十トークンのユーザーメッセージを足して投げる——という構造です。

プロンプトキャッシュは、この「毎回同じ部分」をAnthropic側で保存しておき、 次回以降は入力料金を0.1倍（90%オフ）、レイテンシを大幅削減できる機能です。 2026年現在、Claudeを本番運用する上で「使わない理由がない」レベルの必須テクニックになっています。

仕組み — プレフィックスハッシュと breakpoint

プロンプトキャッシュは「プレフィックスマッチング」という素朴な仕組みで動きます。 リクエストの先頭から cache_control breakpoint までのプレフィックスをハッシュ化し、 同じハッシュが既にキャッシュされていれば読み出し、なければ書き込む、というだけです。

graph LR
    subgraph "1回目のリクエスト"
        A1["tools"] --> B1["system"]
        B1 --> C1["messages[0]"]
        C1 --> D1["★ cache_control"]
        D1 --> E1["messages[1]<br/>（動的）"]
        D1 -.->|hash計算| F1["キャッシュ書き込み<br/>1.25×料金"]
    end
    subgraph "2回目のリクエスト（5分以内）"
        A2["tools"] --> B2["system"]
        B2 --> C2["messages[0]"]
        C2 --> D2["★ cache_control"]
        D2 --> E2["messages[1]<br/>（別の値）"]
        D2 -.->|hash一致| F2["キャッシュ読み出し<br/>0.1×料金"]
    end

ここで肝になるのが「breakpointは必ず動的な内容の前に置く」という原則です。 breakpoint 以降は毎回変わっていい（むしろ変わる想定）ですが、 それ以前は1バイト単位で完全一致していないとキャッシュヒットしません。 タイムスタンプや乱数、ユーザーIDをうっかりキャッシュ対象に含めると、 毎回書き込みが発生してむしろ料金が1.25倍に増えます。

検索順序 — tools → system → messages

Anthropic API はキャッシュ参照時、tools → system → messages の順で プレフィックスを構築します。この順序は固定で変えられません。 そのため、ツール定義を変更すると system や messages のキャッシュも連鎖失効します （ツール定義はプレフィックスの最上流にあるため）。

料金モデル — 書き込みは高く、読み出しは安い

プロンプトキャッシュは「書き込み」と「読み出し」で料金が大きく異なります。 TTL（保持時間）の選択も料金に影響します。基本入力料金を1.0×とした時の倍率で整理します。

損益分岐点は2回目の呼び出しです。5分TTLの場合、 同じプレフィックスを1.25 + 0.1 × N回使えば通常入力のN+1回分より安くなるので、 N ≥ 1つまり2回以上再利用すれば必ず得になる計算です。

一方、1時間TTLは書き込みが2×と高いため、5分以内に確実に再利用される場合は5分TTLで十分です。 1時間TTLは「5分ごとにアクセスが来るとは限らないが、1時間以内には使う」ユースケース—— 例えば人間のユーザーが断続的に質問を投げるチャットや、低頻度のバッチ処理——に向きます。

最小キャッシュトークン数の壁

キャッシュ対象プレフィックスが一定トークン数に満たないと、 エラーを出さずに静かにキャッシュされません。これは初学者が最もハマるポイントです。

実装の基本 — cache_control の置き方

実装はcache_controlオブジェクトを対象ブロックに付けるだけです。 breakpointは1リクエストあたり最大4箇所まで置けます。 以下は典型的な使い方の例です。

import anthropic

client = anthropic.Anthropic()

# 10,000トークン級のシステムプロンプト（アプリ全体で固定）
SYSTEM_PROMPT = open("prompts/system.md").read()

# 5,000トークン級のドキュメント（ユーザー単位で固定）
USER_DOCS = load_docs(user_id)

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},  # ← breakpoint 1
        },
        {
            "type": "text",
            "text": USER_DOCS,
            "cache_control": {"type": "ephemeral"},  # ← breakpoint 2
        },
    ],
    messages=[
        {"role": "user", "content": "ドキュメントを要約して"},
    ],
)

# キャッシュ状況を確認
u = response.usage
print(f"cache_write: {u.cache_creation_input_tokens}")
print(f"cache_read:  {u.cache_read_input_tokens}")
print(f"fresh_input: {u.input_tokens}")  # breakpoint 以降の入力トークン

ポイントはbreakpointを「変化の頻度」で階層化していることです。 SYSTEM_PROMPT は全ユーザー共通（変化頻度：低）、USER_DOCS はユーザー単位で同じ（変化頻度：中）、 messages はリクエスト毎に変わる（変化頻度：高）—— この3層の境目にbreakpointを置くことで、できる限り長いプレフィックスの再利用を狙います。

マルチターン会話での自動キャッシュ

会話が進むと過去のturnも全部送信することになり、どこまでキャッシュすべきか迷います。 そんな時はトップレベルのcache_control（自動キャッシュ）が便利です。 APIが賢く breakpoint を前進させてくれます。

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},  # ← 自動キャッシュ（4スロットのうち1つを使用）
    system="You are a helpful assistant.",
    messages=conversation_history,  # 過去のturnが全部入っている
)

自動キャッシュは4つのbreakpointスロットのうち1つを消費しますが、 会話が伸びるごとに手動でbreakpointを付け替える必要がないため保守性が高いです。 細かい制御が必要な場面では明示配置、それ以外は自動、という使い分けが定石です。

キャッシュの失効条件 — 知らないと詰む

「同じプロンプトを送っているはずなのにキャッシュが効かない」時、 だいたい以下のどれかが原因です。失効の影響範囲はキャッシュ階層によって異なります。

ベストプラクティス

1. breakpointは「最後の静的ブロック」に置く

これがプロンプトキャッシュの第一原則です。breakpoint自身が含むブロックまでがキャッシュ対象なので、 「これ以上後ろは変わってしまう」という直前に置きます。 時刻やリクエストIDを挿入するなら、その前にbreakpointを配置してください。

2. 変化頻度で階層化する

アプリ全体で固定の部分、ユーザー単位で固定の部分、会話セッション単位で固定の部分、 をそれぞれ別の breakpoint で区切ると、部分的なキャッシュヒットで恩恵を得られます。 4スロットしかないので「ツール定義」「全体システム」「ユーザー固有コンテキスト」「会話履歴末尾」あたりが典型配置です。

3. TTL選択は「再利用頻度」で決める

5分以内に確実にヒットする（チャットの連続turn、Agentの連続Tool呼び出し）なら5分TTL一択。 断続的に使われる・バッチで15分おきに走る、といったケースのみ1時間TTLを検討します。 1時間TTLは書き込みが2×高いので、ヒット率が十分でないと逆にコスト増です。

4. usage を必ずロギングする

本番ではキャッシュヒット率が施策の成否を握ります。cache_read_input_tokens / (cache_read + cache_creation + input) でヒット率を計算し、モニタリングダッシュボードに出しましょう。 ヒット率が想定より低ければ、breakpoint位置・失効条件・最小トークン数のいずれかを疑います。

def log_cache_metrics(response):
    u = response.usage
    total = u.cache_read_input_tokens + u.cache_creation_input_tokens + u.input_tokens
    hit_rate = u.cache_read_input_tokens / total if total else 0

    metrics.gauge("claude.cache.read_tokens", u.cache_read_input_tokens)
    metrics.gauge("claude.cache.write_tokens", u.cache_creation_input_tokens)
    metrics.gauge("claude.cache.fresh_tokens", u.input_tokens)
    metrics.gauge("claude.cache.hit_rate", hit_rate)

2026年の変更点 — workspace単位の分離

2026年2月5日から、Anthropic APIおよびAzure AI Foundry（Preview）では プロンプトキャッシュの分離単位が組織（organization）単位からワークスペース単位に変更されました。 Amazon Bedrock と Google Vertex AI は従来通り組織単位です。

よくある落とし穴

• 最小トークン数未達で黙って失敗: Opus 4.7 なら4,096トークン未満のプレフィックスはキャッシュされない。エラーは出ないので usage で確認
• タイムスタンプ混入: "Current time: ..." をシステムプロンプトに含めると毎回失効。別ブロックに分離
• ツール定義の微修正で全失効: ツール定義の順序替え・description文字数変更でも失効する。ツール定義は特に慎重に
• 画像の追加忘れ→途中追加で messages キャッシュ失効: 画像を追加するかもしれない会話では、最初から画像前提の構造にする
• 1時間TTLをデフォルトにしてコスト増: 5分以内に再利用される用途で1時間TTLを使うと、書き込み2×分の損失
• breakpointを4つ全部使い切って増やせない: 長い会話で自動キャッシュと手動を併用する時は枠を意識

まとめ — プロンプトキャッシュは「使わないと損」

プロンプトキャッシュは地味ですが、LLMアプリのランニングコストを桁で変える機能です。 特にツール定義・システムプロンプト・RAGコンテキストが大きいアプリでは、 導入するだけで入力料金が半分以下になるケースも珍しくありません。

• キャッシュヒット時は入力料金0.1倍: 2回以上再利用すれば必ず得
• breakpointは動的コンテンツの直前に: 時刻・乱数・ユーザー単位の動的値は breakpoint より後ろに
• 変化頻度で階層化: tools（最下流）→ system（共通/ユーザー固有）→ messages の順で4スロットを使い分け
• 5分TTL が基本・1時間TTL は断続的アクセス専用: 書き込みコスト2× のトレードオフを理解して選ぶ
• usage でヒット率をモニタ: 本番運用するなら必須の観測項目
• 2026年2月からworkspace分離: 環境間でキャッシュは共有されない設計を前提に

「入力料金を最適化する」という観点では、モデル選択（Opus→Sonnet→Haiku）と並んで プロンプトキャッシュ設計が最大の打ち手です。今日からcache_controlを一箇所置くだけでも 効果を体感できるので、まずは一番呼び出し頻度の高いエンドポイントから試してみてください。