Prompt Caching

Prompt Caching でコスト削減

約 12 分 · クイズ 4 問 · 演習 1 問

重要キーワード (4 語)

Prompt Caching (プロンプトキャッシング) — 繰り返す入力部分の料金を割引する仕組み

cache_control (キャッシュ制御) — ブロックにキャッシュ対象であることを指示するフィールド

TTL (有効期限) — キャッシュが保持される時間 (デフォルト 5 分)

cache hit rate (ヒット率) — キャッシュ読み出し / 全入力の比率

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

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

キャッシュ可能な場所

system
messages (一部)
tools

使い方

[default] > ユーザー認証に Google OAuth を追加して
              ↓ Shift+Tab
[plan]    > (同じ依頼)
              ↓
Claude: 計画を提示...
  1. requirements.txt に authlib を追加
  2. app/auth/oauth.py を新規作成 (OAuth フロー実装)
  3. app/routes/auth.py に /login/google, /callback ルート追加
  4. app/templates/login.html に「Googleでログイン」ボタン追加
  5. .env.example に GOOGLE_CLIENT_ID/SECRET を追記
  6. tests/test_oauth.py で 5 ケース追加
              ↓ ユーザーがレビュー → 「OK、進めて」
              ↓ Shift+Tab
[acceptEdits] > 計画通り実装して

料金

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

TTL (有効期限)

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

# 1. 不安なら一時コミット (作業ベースを残す)
git checkout -b refactor/services
git commit -am "wip: before refactor"

# 2. Claude に任せる
claude
> services 層を別ファイルに分離。テストも新パスに合わせて修正。

# 3. テスト
pytest -q

# 4a. OK → squash で綺麗な 1 コミットに
git rebase -i HEAD~5

# 4b. NG → 一発でロールバック
git reset --hard HEAD~5

設計のコツ

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

usage で確認

git worktree add ../my-project-experiment -b experiment
cd ../my-project-experiment
claude

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 回送ってみてください。