目次
同じ設計書やコーディング規約を毎回Claude APIへ送っているのに、入力料金も待ち時間も下がらない。そんなときは、モデルを小さくする前にプロンプトキャッシュの使われ方を確認すると、原因を切り分けられます。キャッシュは同じ質問への回答を保存する仕組みではなく、リクエスト先頭の共通部分を再利用する仕組みです。
本記事は2026年10月22日に確認したAnthropicの公式ドキュメントに基づく実装解説です。新機能の当日発表を伝える記事ではありません。APIを実行した実測値は扱わず、公式仕様と本サイトが提案する測定手順を分けて説明します。対象はClaude APIを組み込む開発者で、Claudeのチャット画面やClaude Codeの設定手順とは異なります。
スポンサーリンク
まず回答キャッシュとプロンプトキャッシュを分ける
FAQの質問と完成回答をアプリ側へ保存する回答キャッシュでは、同じキーに対して保存済みの回答を返します。プロンプトキャッシュでは、モデルへ渡す入力の共通部分を再利用し、その後ろに続く質問に応じて新しい出力を生成します。規約を使い回しながら、ファイルごとに異なるレビューを依頼する用途などに向いています。
そのため、キャッシュがヒットしても出力トークンは発生します。外部APIの実行結果やアプリの更新結果まで再利用するわけでもありません。削減したい費用が入力、長い回答、外部ツールのどこにあるかを先に分けると、キャッシュを入れたのに請求が変わらないという行き違いを減らせます。
固定部分を前へ動的な値を後ろへ置く
公式のPrompt caching資料は、共通の入力プレフィックスを再利用し、自動キャッシュと明示的なブレークポイントの二通りで設定できると説明しています。自動方式はリクエスト最上位へcache_controlを指定し、明示方式はコンテンツブロックへ指定します。どの部分を共通化したいかに合わせて選びます。
Anthropic公式資料｜Prompt caching：設定方式・保持期間・モデルごとの条件
例えばコードレビュー用のWeb機能なら、共通の指示、コーディング規約、固定の出力方針を先頭へ置き、レビュー対象の差分や依頼ごとの条件を後ろへ置く構成を検討できます。リクエストIDや現在時刻を共通指示の途中へ埋め込むと、それ以降が毎回別の入力になります。運用メタデータをモデルへ渡す必要がなければ、アプリのログだけで管理する方が単純です。
これは内容を変更してはいけないという意味ではありません。規約の改訂やモデルの切り替えは必要です。変更が入ったときに、キャッシュの作り直しが発生するものとして費用とリリースを扱います。古い前提を守ってまでヒット率を上げる設計にはしません。
スポンサーリンク
短すぎる入力と有効期間を確認する
キャッシュにはモデルごとの最小入力長があります。公式資料では、例えばClaude Sonnet 5.5とOpus 5.5の最小キャッシュ長は512トークンです。短い入力に設定を付けてもキャッシュされず、エラーにならない場合があります。日本語の文字数とトークン数は一致しないため、文字数だけで閾値を判定しないでください。
既定の有効期間は5分で、1時間の設定も用意されています。公式資料は、期間が応答の終了時点ではなく、書き込み・読み取りリクエストの開始時点から数えられる点も説明しています。長い生成の後に利用者が考えてから次の質問を送ると、見た目より再利用できる時間が短くなります。低頻度の管理画面では、共通部分が安定していてもヒットしにくいことがあります。
usageと診断は別の問いに答える
キャッシュの利用はusage.cache_read_input_tokensで確認します。新規書き込みはcache_creation_input_tokensとして確認できます。設定を送ったというログだけで成功と判定せず、応答で実際に読まれた量と書かれた量を記録します。一般入力や出力の利用量も一緒に残してください。
Cache diagnosticsは、前回と今回のリクエスト構造の差を調べる補助機能です。diagnostics.previous_message_idへ前回の応答IDを渡して比較します。最初の呼び出しから診断を有効にし、次の呼び出しへIDを引き継ぐ必要があります。このIDはキャッシュの手動選択キーではありません。
診断結果が差分なしでもキャッシュヒットが保証されるわけではなく、保持期間などを別に調べる必要があります。比較が間に合わない、以前の診断情報がない、情報が利用できないケースもあります。公式資料では診断はClaude API向けで、Amazon BedrockやGoogle Cloudでは利用できないとされています。クラウド経由の利用へ、そのまま設定を移さないようにします。
Anthropic公式資料｜Cache diagnostics：診断結果とusageの読み分け
スポンサーリンク
差分が起きる場所を順番に直す
本サイトでは、キャッシュミスが増えたらモデル、system、tools、messagesの順に確認することを提案します。フォールバックで別モデルへ切り替わった、共通指示に時刻が入った、ツール定義の順序が変わった、会話の途中を書き直した、といった変化を追います。公式診断は最初の差分を示すため、先頭の問題を直してから再測定します。
JavaScriptのオブジェクトからツール一覧を組み立てる場合は、毎回同じ順序になるかを確認します。組織やユーザーごとに許されるツールが違うなら、同じ一覧へ無理に統一する必要はありません。許可範囲を保ったまま、同一条件の利用者の間で定義が安定するようにします。キャッシュ効率のために権限を広げる理由はありません。
会話履歴は、APIから受け取ったassistantのcontentを保持して次へ渡す構成にすると、不用意な再整形を減らせます。表示用に短縮した文章で履歴を置き換えると、モデルへ渡す履歴まで変わってしまいます。画面表示用のデータと送信用履歴を分けると、最適化の影響を追いやすくなります。
TypeScriptで観測する値を決める
次はSDK固有の呼び出しを省いた、本サイト作成の観測例です。実行可能なAPI統合一式ではありません。応答のusageだけを受け取り、入力系のどこへトークンが割り当てられたかを記録する関数です。単価の計算はモデル別の料金表へ分離します。
type Usage = {
input_tokens?: number;
cache_read_input_tokens?: number;
cache_creation_input_tokens?: number;
output_tokens?: number;
};
function usageRecord(u: Usage) {
return {
input: u.input_tokens ?? 0,
cacheRead: u.cache_read_input_tokens ?? 0,
cacheWrite: u.cache_creation_input_tokens ?? 0,
output: u.output_tokens ?? 0,
};
}この関数だけでは請求金額もヒット率も計算できません。通常入力、読み取り、書き込みをそれぞれ該当単価で集計し、リクエスト全体で比較します。書き込みへ別の価格が適用されるため、初回だけの比較でキャッシュを不利と判断したり、読み取り料金だけで全体を安いと判断したりしないようにします。
同じ実行条件で費用と時間を比較する
試験は、固定の規約と異なるコード差分を使い、モデル・推論設定・出力上限を固定して行います。キャッシュを使わない構成、初回書き込み、期間内の再利用、期間を空けた再実行を分けて記録します。実際の利用間隔に近いデータを含めることが重要です。
記録する時間は、最初の応答が返るまでと、回答全体が完了するまでを分けます。キャッシュで入力処理が速くなっても、長い回答の生成が支配的なら全体時間は大きく変わらないことがあります。回線や混雑によるばらつきもあるため、単発の最速値ではなく複数回の分布で比較します。
仮に同じ規約を十回再利用する設計でも、十回分すべてが期間内に始まるとは限りません。ユーザー別の操作間隔、時間帯、バッチのまとまりを見て、書き込み回数と読み取り回数を見積もります。固定費用のない最適化に見えても、実装・観測・保守に使う開発時間は導入コストとして数えます。
導入を広げる前に品質も保つ
キャッシュを効かせるために指示の順序や文書の組み立てを変える場合は、回答品質も再確認します。共通部分の分離で対象ファイルの条件が欠落したり、規約の版が古いまま残ったりすると、安くても採用できない回答になります。キャッシュの有無だけを比較したつもりでも、入力内容を変えていないかレビューしてください。
既存の評価用質問集と合格条件は、関連記事の評価・回帰テストの手順を使えます。本記事では、その評価に入力内訳と時間を追加する位置付けです。最初は一つのAPI機能へ適用し、期待した頻度で再利用されることを確かめてから、他の画面へ広げると改善の理由を説明できます。
2026年10月22日時点の確認では、入力の安定化、usageによる利用確認、診断による差分調査を組み合わせられます。ただしキャッシュ設定だけで一定の削減率が得られるとは言えません。自社の呼び出し間隔と入力構成を測り、回答の品質を保ったまま費用と待ち時間が下がるかで採否を決めます。
スポンサーリンク
参考資料
Anthropic｜Tool use with prompt caching
