Claude API のプロンプトキャッシュが本番で静かにヒットしなくなるとき — TTLと節約額の実測メモ

5分TTLと1時間TTLをどう選ぶか

キャッシュには有効期限があります。標準の ephemeral キャッシュは最後にアクセスしてから約5分で失効し、その間にアクセスがあるたびに期限がリセットされます。つまり5分以内に次のリクエストが来続けるかぎりキャッシュは生き続けますが、間隔が空くと失効し、次のリクエストは再び書き込み（通常入力の約1.25倍）からやり直しになります。

2026年6月に Developer Platform へ最大1時間のプロンプトキャッシュが追加され、TTLを長く取れるようになりました。これは「リクエストが散発的にしか来ないが、同じ大きなプレフィックスを使い回す」ワークロードに効きます。ただし1時間キャッシュは保持コストが上がるため、なんでも1時間にすればよいわけではありません。判断はトラフィックの間隔で決めるのが実用的です。

私の運用だと、日中ずっと動いているチャット系のエンドポイントは5分で十分ヒットし続けます。一方、1〜2時間おきにしか走らない記事整合性チェックのような低頻度ジョブは、5分キャッシュだと毎回書き込みからになっていて意味がありませんでした。後者を1時間キャッシュに切り替えたところ、同じプレフィックスの再書き込みが目に見えて減りました。「常時動いているか、ぽつぽつ動くか」でTTLを分けるのが、いちばん素直な指針だと感じています。

「効いているはず」を実測に変える

ここがいちばん伝えたい部分です。プロンプトキャッシュの怖さは、壊れても例外が飛ばないことにあります。ミスしてもリクエストは普通に成功し、ただ静かに通常料金で処理されるだけ。だから「効いているはず」という思い込みを、usage から取れる実数に置き換える計装を最初から入れておく必要があります。

レスポンスの usage には3つの数字が並びます。cache_creation_input_tokens（書き込み）、cache_read_input_tokens（読み取り＝ヒット）、input_tokens（キャッシュ対象外の通常入力）です。この3つを毎リクエスト記録するだけで、ヒット率も節約額も後から正確に出せます。

import anthropic
 
# Sonnet 4.6 の概算単価（USD / 1M tokens）。本番では最新の料金で更新する
PRICE_INPUT = 3.00          # 通常入力
PRICE_CACHE_WRITE = 3.75    # キャッシュ書き込み（1.25倍）
PRICE_CACHE_READ = 0.30     # キャッシュ読み取り（0.1倍）
 
 
def record_usage(usage) -> dict:
    """1リクエスト分の usage を、実コストと「キャッシュなしだったらいくらか」に換算する"""
    read = getattr(usage, "cache_read_input_tokens", 0) or 0
    write = getattr(usage, "cache_creation_input_tokens", 0) or 0
    normal = usage.input_tokens
 
    # 実際に払ったコスト
    actual = (
        normal * PRICE_INPUT
        + write * PRICE_CACHE_WRITE
        + read * PRICE_CACHE_READ
    ) / 1_000_000
 
    # キャッシュを一切使わなかった場合の仮想コスト（read/write も通常単価で計算）
    baseline = (normal + write + read) * PRICE_INPUT / 1_000_000
 
    cached_tokens = read + write
    hit_rate = read / cached_tokens if cached_tokens else 0.0
 
    return {
        "actual_usd": round(actual, 6),
        "baseline_usd": round(baseline, 6),
        "saved_usd": round(baseline - actual, 6),
        "cache_hit_rate": round(hit_rate, 3),
    }

この record_usage を全リクエストに通し、saved_usd と cache_hit_rate を時系列でログに流しておけば、「先週の火曜から急にヒット率が0.9から0.4へ落ちた」といった変化が目に見えます。私はこれを入れて初めて、あるデプロイでツール定義の組み立て順が変わってミスが増えていたことに気づきました。例外も警告も出ないので、計装がなければ請求が来るまで分からなかったはずです。

しきい値を決めてアラートにつなぐところまでやると、運用がぐっと楽になります。

def check_cache_health(metrics: list[dict], min_hit_rate: float = 0.6) -> str | None:
    """直近のメトリクスからヒット率の低下を検知する。問題があれば理由文字列を返す"""
    recent = metrics[-50:]
    cached = [m for m in recent if m["cache_hit_rate"] > 0 or m["actual_usd"] > 0]
    if not cached:
        return None
    avg_hit = sum(m["cache_hit_rate"] for m in cached) / len(cached)
    if avg_hit < min_hit_rate:
        return f"キャッシュヒット率が低下: 直近平均 {avg_hit:.1%}（しきい値 {min_hit_rate:.0%}）"
    return None

ヒット率の「正常値」はワークロードによって違うので、最初の1〜2週間で自分のシステムのベースラインを掴んでから、そこから明確に落ちたら鳴る、くらいの緩いしきい値にしておくのが現実的です。最初から厳しくすると、トラフィックの自然な揺れで鳴り続けて誰も見なくなります。

ブレークポイントは「変更頻度の階段」で置く

ヒット率を底上げするうえで効くのが、ブレークポイントを変更頻度の順に並べることです。キャッシュは最大4つのブレークポイントを置けますが、大事なのは数より順序で、「めったに変わらないもの」を先頭に、「よく変わるもの」を後ろに、という階段状の配置にします。

system = [
    {
        "type": "text",
        "text": BASE_INSTRUCTIONS,   # ほぼ不変。半年に一度しか触らない
        "cache_control": {"type": "ephemeral"},   # BP1
    },
    {
        "type": "text",
        "text": weekly_knowledge_base,   # 週次更新。前半より変わる
        "cache_control": {"type": "ephemeral"},   # BP2
    },
]
# tools は週単位で安定しているので、その末尾に3つ目のBPを置く
tools[-1]["cache_control"] = {"type": "ephemeral"}   # BP3

こうしておくと、週次のナレッジベースを更新して BP2 以降が無効になっても、BP1（基本指示）のヒットは維持されます。逆に全部を一つのブロックにまとめてしまうと、末尾を少し直しただけで全体が再書き込みになり、せっかくの安定部分まで巻き添えで失効します。「どの粒度で変わるか」でブロックを分けておくのが、長く効かせるコツです。

なお、Token-Efficient Tool Use のようなツール周りの最適化フラグを併用する場合、ヘッダーやベータ指定を変えるとキャッシュの名前空間が変わって再書き込みになることがあります。最適化フラグを切り替える検証は、本番のキャッシュが温まっている時間帯を避けて行うのが無難です。

運用に落とすときの最小チェック

最後に、新しいエンドポイントでプロンプトキャッシュを使い始めるときに自分が毎回確認している項目を挙げておきます。キャッシュ対象（system・tools・先頭側の messages）に動的な値が入っていないか、キャッシュ対象を組み立てる箇所で順序が固定されているか、リクエスト間隔に対してTTLの選択が噛み合っているか、そして usage の3数値をログに流して cache_hit_rate と saved_usd を可視化できているか。この4点が揃っていれば、ヒット率が落ちても請求ではなくダッシュボードで先に気づけます。

プロンプトキャッシュは、入れた瞬間の削減率より「数週間後もその削減率を保てているか」のほうがずっと難しい機能です。効かせ続けるための監視を一緒に組み込んでおくこと——同じところでコストを取りこぼした経験から、これがいちばん効くと考えています。お読みいただきありがとうございました。