Prompt Caching でコスト削減

English	日本語	説明
Prompt Caching	プロンプトキャッシング	繰り返す入力部分の料金を割引する仕組み
cache_control	キャッシュ制御	ブロックにキャッシュ対象であることを指示するフィールド
TTL	有効期限	キャッシュが保持される時間 (デフォルト 5 分)
cache hit rate	ヒット率	キャッシュ読み出し / 全入力の比率

Prompt Caching (プロンプトキャッシング)

長くて同じ内容を繰り返し送る場合、入力トークンを大幅に割引 できる仕組みです。チャットボットの system prompt や RAG の参考資料、Tool 一覧などに最適。

キャッシュ可能な場所

system
messages (一部)
tools

使い方

res = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "あなたは社内ヘルプデスクです。"},
        {
            "type": "text",
            "text": "<長い社内ドキュメント (10,000 トークン)>",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "経費精算のやり方は?"}],
)

料金

キャッシュ書き込み: 通常入力の 1.25 倍。
キャッシュ読み出し: 通常入力の 0.1 倍 (約 90% 割引)。
保存自体は無料。

TTL (有効期限)

デフォルトで 5 分。最後にアクセスされた時点で延長されます。 24 時間 TTL も指定可能 (料金は若干高い)。

"cache_control": {"type": "ephemeral", "ttl": "24h"}

設計のコツ

長く・固定 な部分にだけ付ける。
ブレークポイントは 最大 4 つ まで設定可能。最も粒度の大きい単位で 1 つ、細かく分けるなら複数。
可変な部分にキャッシュを付けない (ヒット率がゼロになる)。
最低トークン数 (~1024) を満たさないとキャッシュ対象外。

usage で確認

print(res.usage.cache_creation_input_tokens)   # 書き込み
print(res.usage.cache_read_input_tokens)        # 読み出し (キャッシュヒット)
print(res.usage.input_tokens)                   # それ以外の入力

Hit rate を測る

def hit_rate(usage) -> float:
    total = usage.cache_read_input_tokens + usage.cache_creation_input_tokens + usage.input_tokens
    return usage.cache_read_input_tokens / total if total else 0

60-80% 以上 を目標にしましょう。

4 ブレークポイント戦略

[system 共通プロンプト]              <- ブレークポイント 1 (永続)
[ガイドライン本文 (大きい)]            <- ブレークポイント 2
[直近 10 ターン履歴]                  <- ブレークポイント 3 (やや更新頻度高い)
[最新ターンの user]                  <- キャッシュなし

コスト削減シミュレーション

長い system (10K トークン) を 100 回呼ぶ場合: - キャッシュなし: 10K × 100 = 1M トークン入力課金 - キャッシュあり: 10K (1.25x 書き込み) + 10K × 0.1 × 99 (読み出し) ≒ 0.11M トークン課金 - → 約 89% コスト削減

試す: usage を Playground で観察

Playground でも cache_read_input_tokens の表示が可能です。同じ system を 2 回送ってみてください。