Claudeのプロンプトキャッシュ — 料金、usageオブジェクト、ゲートウェイ経由でヒット率が低下する理由

プロンプトキャッシュはエージェントの請求額を左右する最大の単一要因であり、ひそかに機能していない可能性が最も高い要因でもあります。正しく指定すれば、リクエストの繰り返し部分は入力料金の10分の1で課金されます。指定を誤った場合 — またはプレフィックスを書き換えるものを経由した場合 — 誰も読み取らないキャッシュエントリへの書き込み料金を支払うため、通常料金より高く課金されます。

仕組み自体は他の場所で詳しく説明されています。どこにも記載されていないのは、リクエストがゲートウェイを経由したときに何が変わるかという点です。これは、このページを読む人の多くが置かれている状況です。以下で両方を説明します。

仕組みの概要

安定したプレフィックス — システムプロンプト、ツールスキーマ、ドキュメント — を指定すると、プロバイダーがその処理済み形式を保存します。次回、プレフィックスが完全一致するリクエストでは、再処理せずにそれを読み戻します。

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

すべてを機能させ、同時にすべての問題を引き起こすのは、2つの性質です。一致判定はプレフィックスに対して行われるため、先頭付近で何かが変わると、その後のすべてが無効になります。また、エントリには有効期間があるため、ターン間の間隔が長い会話では、読み取りではなく再構築が行われます。

料金

3列目は標準比率です。読み取りは入力料金の10分の1です。4列目も標準的な値で、キャッシュ書き込みは入力の1.25倍です。これはAnthropicが5分間のエントリについて示している倍率です。両方の比率がKunavoの入力価格に適用されるため、Anthropicの定価に対する割引率はモデル入力と同じです。KunavoがAnthropicと異なるのは、1時間のエントリです。Anthropicではその書き込みを入力の2倍としていますが、Kunavoでは同じ1.25倍で請求します。これは、頻繁に再構築されるワークロード — 長時間稼働するエージェント、進行の遅い会話、プレフィックスが頻繁に変化するもの — に特に重要です。こうしたワークロードでは、キャッシュ行の請求額を左右するのは読み取りではなく書き込みだからです。

両方の数値はレンダリング時にカタログから読み取られます。これは料金表とClaude計算ツールが読み取るものと同じソースであり、このページに手入力された料金はありません。

usageオブジェクトの読み方

キャッシュの挙動を請求額から推測しないでください。すべてのレスポンスが直接知らせてくれます。3つのトークン数だけで完全に診断できます。

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

ゲートウェイ経由でヒット率が低下する理由

キャッシュはそれを作成したアップストリームに存在し、プレフィックスの一致は完全一致です。この2つの事実により、1つのプロバイダーを直接呼び出す場合には決して発生しない、3つの障害パターンが生じます。

ルーティングが変わった。連続するリクエストが異なるアップストリームに到達すると、2つ目はキャッシュを見つけられません。1つ目が書き込んだエントリは、2つ目が実行された場所からは見えないためです。これは独自のログには現れず、読み取りであるはずのキャッシュ作成数としてのみ現れます。最も一般的な原因であり、ゲートウェイがアップストリーム間で自由に再ルーティングすると、トークン単価は安くてもセッション単価は高くなり得る理由です。

プレフィックスの前に何かが挿入された。システムメッセージを書き換えたり、ツール定義を正規化したり、フィールドの順序を変更したりするレイヤーは、別のプレフィックスを生成します。別のプレフィックスはミスになります。エラーは発生せず、請求額だけが増えます。

間隔がエントリの有効期間を超えた。ターン間に数分考えるエージェントは、毎回再構築することがあります。これはゲートウェイではなくワークロードの性質ですが、1つ目の要因と悪く作用します。再構築は、再ルーティングの機会にもなるためです。

3つすべてに共通する診断方法は、セッション全体でcache_creation_input_tokensを確認することです。大きな値が一定のままなら、再構築しています。最初だけ大きく、その後ゼロなら機能しています。Kunavoでは、リクエスト単位のコストとキャッシュ済みトークン数を使用量ビューで確認でき、キャッシュリファレンスにはエンドポイントレベルの詳細があります。

対処方法

キャッシュするプレフィックスを本当に安定させてください。リクエストごとに変わるものは、指定したブロックの後ろに置き、前には決して置かないでください。短時間で失効するエントリではアイドル時間が敵になるため、可能ならエージェントのターンを近い間隔でまとめてください。また、リクエスト単位ではなくセッション全体を測定してください。キャッシュは一連の処理に関する性質であり、リクエスト単位の見積もりでは確認できません。Claudeトークンコスト計算ツールには、このためにキャッシュ済みトークンのフィールドがあります。プロンプトのうち実際に繰り返される割合を設定すれば、月額料金が現実を反映するようになります。

よくある質問