プロンプトキャッシュ診断とは?ClaudeとGPT-6の確認方法を比較、EC向けAIエージェントのコストを見える化する手順とプロンプト4本【2026年版】

プロンプトキャッシュ診断とは、キャッシュが外れた原因をAPIが返す機能です。ClaudeのCache diagnosticsの4つの原因タイプとGPT-6系での確認方法の違い、EC向けAIエージェントのコストを見える化する5手順とプロンプト4本を解説します。

投稿日: カテゴリー AIニュース

プロンプトキャッシュ診断とは、キャッシュが外れた原因をAPIが示す機能です。

EC向けのAIエージェントで請求額が急に跳ねたとき、原因の多くは「毎回同じはずの長いプロンプト前半が、どこかで1文字だけ変わっていた」ことにあります。商品マスタの抜粋や返品規約、ブランドの表記ルールをシステムプロンプトに入れて使い回す設計では、キャッシュ(前回と同じ前半部分を再利用し、読み込み料金を下げる仕組み)が当たるかどうかで入力コストが大きく変わります。Anthropicは、外れた原因を4種類の「変化した場所」で返すCache diagnostics(キャッシュ診断)をClaude APIで提供しており、勘に頼っていた原因探しを1回のAPI応答で絞り込めるようになりました。本記事は、EC支援19年・5,000社超の実績を持ち、AI導入支援は2023年から提供する株式会社オルセル(うるチカラ運営)の現場知見にもとづき、Claudeの診断機能の使い方と、GPT-6系での確認方法との違い、EC業務での改善手順、そのまま使えるプロンプト4本を整理します。

なぜEC向けAIエージェントでキャッシュの当たり外れが請求額を左右するのか

端的に言えば、EC業務のAIは「長い固定情報+短い毎回の質問」という形になりやすく、キャッシュが外れると固定情報の読み込み料金を毎回フルで払うことになるからです。Claudeのプロンプトキャッシュでは、キャッシュから読んだ入力は通常の入力より大幅に安く計算される設計で、プロンプトキャッシュの公式ドキュメントに料金倍率が示されています(最新の倍率は公式の料金ページで要確認)。

EC事業者がAIエージェントを組むと、システムプロンプトには次のような情報が入りがちです。楽天市場やAmazonの禁止表現リスト、薬機法・景品表示法に関わるNGワード、ブランドのトーン&マナー、返品・交換ポリシー、よく使う商品カテゴリの属性定義などです。これらは数千〜数万トークンに及ぶことも珍しくありません。1日に数百件の問い合わせ返信や、数千SKUの商品説明リライトを回すと、この固定部分の読み込みが積み重なって請求の大半を占めます。

問題は、キャッシュが外れても処理自体は普通に成功してしまう点です。公式ドキュメントも、キャッシュ診断がない場合の手がかりはcache_read_input_tokensがゼロに落ちることだけで、何が変わったのかは分からないと説明しています。現場で繰り返し見るのは、「先月まで安かったのに、システムを少し直したら倍近くになった」という相談です。たとえば、システムプロンプトの冒頭に「今日の日付」を差し込む改修を入れただけで、毎日どころか毎回キャッシュが外れるようになっていた、というケースが典型です。

2026年秋の時点で、Claudeのフラッグシップ・中位・軽量モデルはOpus 5.5、Sonnet 5.5、Haiku 5.5の系列で、OpenAIはGPT-6.2 AstraとSolを11月に公開しています。モデルの単価が下がる局面でも、キャッシュが当たらない設計のままでは値下げの恩恵を取りこぼします。モデル選びより先に、キャッシュの当たり方を点検するほうが費用対効果の高い場面は多いと考えています。

Claudeのキャッシュ診断の仕組みと4つの「外れた理由」

Claudeのキャッシュ診断は、連続する2つのリクエストを比べ、プロンプトの前半が最初に食い違った場所を返す機能です。Cache diagnosticsの公式ドキュメントによると、リクエストにdiagnosticsオブジェクトを付けることがオプトインの合図になり、1回目はprevious_message_idをnull、2回目以降は直前の応答のidを渡します。APIは前回の「指紋」(ハッシュとトークン数の推定値だけで、プロンプト本文は保存しない)と今回の内容を比べ、応答に結果を付けて返します。

返ってくるcache_miss_reasonのtypeは、変化した場所を示す4種類と、比較できなかった2種類に分かれます。変化系は、モデルが前回と違うmodel_changed、システムプロンプトが違うsystem_changed、ツール定義の配列が違うtools_changed、そしてモデル・システム・ツールは同じなのに過去の会話履歴が書き換わったmessages_changedです。比較できなかった系は、前回の指紋が見つからないprevious_message_not_foundと、診断情報が出せなかったunavailableです。

変化系の4種類にはcache_missed_input_tokensという推定値も付きます。食い違った地点より後ろにあった入力トークンの目安で、失ったキャッシュの大きさをつかむのに使えます。ただし公式ドキュメントは、トークン化前のバイト長から出した概算なので請求額としては扱わないよう注意を促しています。

制約も押さえておきましょう。前回の指紋は短時間で失効するため、比較は間隔の近いリクエスト同士で行います。前回と同じ組織・ワークスペースで実行されている必要があり、違えばprevious_message_not_foundになります。会話が非常に長く、変化が履歴の奥深くにある場合はunavailableになることがあります。診断は「ベストエフォート」で、リクエストを止めたり失敗させたりはしません。対応プラットフォームはClaude APIと、Google Cloud上のAnthropic管理版の2つが公式ドキュメントに記載されています。

対応モデルは、Opus 5.5、Sonnet 5.5、Haiku 5.5に加え、Fable 5.2やOpus 4.8、Sonnet 4.5などの旧世代まで幅広く列挙されています。ゼロデータ保持(ZDR)の扱いについても、プロンプトと出力は保存せず、比較用の指紋だけを短時間保持すると明記されているため、顧客対応の文面を扱うEC事業者でも導入の説明はしやすい部類です。

GPT-6系での確認方法との違い

OpenAIのモデルでは、キャッシュは一定の長さ以上のプロンプトに自動で適用され、応答のusageに含まれるキャッシュ済みトークン数(cached_tokens)で当たり具合を確認するのが基本です。つまり「どれだけ当たったか」は分かりますが、「なぜ外れたか」は自分でリクエストを比べて推理する必要があります。第三者の比較記事ではOpenAI側にも類似の診断があると紹介されていますが、公式ドキュメントでの確認は本記事執筆時点で取れていないため、GPT-6系の診断機能の有無は要確認とします。

運用上の違いをまとめると、Claudeはcache_controlで「どこまでをキャッシュするか」を明示し、診断で外れた場所まで返してくれる設計です。OpenAIは自動キャッシュで設定の手間が少ない一方、原因の切り分けはログ設計に依存します。どちらでも共通して有効なのは、「固定部分を前に、変わる部分を後ろに」という並べ方の原則です。この原則は、以前GPT-5.6のプロンプトキャッシュとブレークポイント設計の解説でも整理しました。

ClaudeとGPT-6を併用しているEC事業者は、モデルを切り替えるルーター(振り分け処理)にも注意が必要です。Claudeの診断では、ルーターやA/Bテスト、フォールバックで別モデルが選ばれた場合はmodel_changedとして明確に出ます。キャッシュはモデルごとなので、1つの会話の途中でモデルが入れ替わる設計はコスト面で不利です。会話単位でモデルを固定するのが定石になります。

EC業務でキャッシュ診断を回す5つの手順

ここからは、EC事業者が自社のAIエージェントにキャッシュ診断を組み込み、外れの原因をつぶしていく手順を5段階で示します。開発会社に依頼している場合も、この順番で依頼内容を伝えると話が早く進みます。

手順1は、診断のオプトインをすべての呼び出しに入れることです。公式ドキュメントは、毎ターンdiagnosticsオブジェクトを含めるよう推奨しています。途中のリクエストで付け忘れると、次の比較はprevious_message_not_foundになり、原因が分かりません。

手順2は、結果をログに残すことです。応答のcache_miss_reason.typeとcache_missed_input_tokens、usageのcache_read_input_tokensを、業務名(問い合わせ返信、商品説明生成など)と一緒に1行ずつ記録します。CSVでもスプレッドシートでも構いません。

手順3は、原因別の典型的な直し方を当てることです。system_changedなら、システムプロンプトに入れている日付や問い合わせ番号、担当者名などの毎回変わる値を、ユーザーメッセージ側へ移します。tools_changedなら、ツール定義を毎回同じ順番で送り、入力スキーマのJSONはキーを並べ替えて決定的に作ります。messages_changedなら、会話履歴を「追記だけ」にし、過去のアシスタント応答やツール結果を再整形せずそのまま送り返します。model_changedなら、会話単位でモデルを固定します。

手順4は、比較できなかったケースの扱いです。unavailableは、tool_choiceやthinkingなどプロンプトに影響する他のパラメーターが変わった場合にも出ると説明されています。会話の途中で推論の深さ設定を切り替える実装は、キャッシュの面では避けたほうが無難です。

手順5は、月次でキャッシュ読み込み比率を見ることです。入力トークン全体のうち、キャッシュから読めた割合を業務別に並べると、どの業務の設計を直すべきかが一目で分かります。ある食品ジャンルの中規模店舗の事例では、問い合わせ返信ボットのシステムプロンプトに受付日時を入れていたことが原因で、読み込み比率がほぼゼロでした。日時をユーザーメッセージへ移すだけで、比率が大きく改善しています。

キャッシュ改善に使えるプロンプト4本

ここでは、ChatGPT・Claude・Geminiのいずれでも使える形で、キャッシュ改善の作業を補助するプロンプトを4本紹介します。社内の担当者が、開発会社に修正を依頼する前の整理にも使えます。

1本目は、システムプロンプトを固定部分と変動部分に分ける依頼です。毎回変わる値が混ざっていないかを洗い出させます。

プロンプト1:システムプロンプトの固定部分と変動部分を分離

あなたはAIエージェントのコスト最適化に詳しいエンジニアです。
以下は当社のEC業務用AIのシステムプロンプトです。
{システムプロンプト全文}

次の作業をしてください。
1. リクエストごとに変わりうる値(日付、時刻、注文番号、顧客名、担当者名、在庫数など)をすべて列挙
2. それらを取り除いた「毎回同一の固定部分」を出力
3. 取り除いた値をユーザーメッセージ側に渡すときのテンプレートを出力
4. 固定部分のうち、更新頻度が月1回以下の情報と週1回以上の情報を分類

2本目は、診断ログの集計から改善の優先順位を付ける依頼です。外れた理由と失ったトークン量の大きさで並べ替えます。

プロンプト2:キャッシュ診断ログから改善優先度を決める

以下は当社のAIエージェントのキャッシュ診断ログ(CSV)です。
列:日時, 業務名, cache_miss_reasonのtype, cache_missed_input_tokens, cache_read_input_tokens, input_tokens
{CSVデータ}

次の観点で集計し、改善の優先順位を付けてください。
1. 業務名×typeごとの件数と、cache_missed_input_tokensの合計
2. 失ったトークン量が多い順に上位5つの組み合わせ
3. 各組み合わせについて考えられる原因と、修正方針を1〜2文で
cache_missed_input_tokensは概算値なので、請求額としては扱わないでください。

3本目は、ツール定義の安定性チェックです。ツールの並び順やスキーマの書き方が毎回ぶれていないかを確認させます。

プロンプト3:ツール定義の並び順とスキーマの安定性チェック

以下は当社のEC業務用AIエージェントが使うツール定義を、2回分のリクエストから抜き出したものです。
1回目:{ツール定義JSON_1}
2回目:{ツール定義JSON_2}

次を確認してください。
1. ツールの並び順に違いがあるか
2. 各ツールのinput_schemaで、キーの順序や記述に違いがあるか
3. 違いがある場合、毎回同一の内容を生成するための実装上の修正案
4. 業務によってツールを増減させている場合、キャッシュを壊さない構成案

4本目は、経営層向けの月次コストレポートの下書きです。技術用語を減らし、業務別の改善余地を金額感で伝える形にします。

プロンプト4:AIエージェントのキャッシュ効率の月次レポート

あなたはEC事業者の経営企画担当です。
以下の当月データをもとに、経営会議向けのA4一枚のレポートを作成してください。
{業務名ごとの入力トークン合計, キャッシュ読み込みトークン合計, 主なcache_miss_reason, 当月のAPI請求額}

構成:
1. 結論(今月のキャッシュ読み込み比率と前月比)
2. 業務別の比率と、改善余地が大きい業務の上位3つ
3. 改善策と、来月の想定効果(概算であることを明記)
専門用語には括弧で短い説明を付けてください。

キャッシュ改善で起きやすい失敗例と回避策

最も多い失敗は、「便利だから」とシステムプロンプトに動的な情報を足していくことです。今日の日付、在庫数、キャンペーン名、担当者名などを冒頭に入れると、その時点でキャッシュは毎回外れます。回避策は、システムプロンプトを「月に1回しか変えない文書」と位置づけ、変わる情報はすべてユーザーメッセージ側に置くことです。

2つ目は、会話履歴の要約や切り詰めを毎ターンやり直す実装です。トークン節約のつもりで履歴を整形し直すと、messages_changedで毎回キャッシュが外れ、かえって高くつくことがあります。履歴は追記のみで扱い、要約が必要なら一定の区切りで一度だけ行う設計が安全です。

3つ目は、診断の付け忘れによる誤解です。previous_message_not_foundは、公式ドキュメントでも「リクエストが変わった証拠ではない」と明記されています。前回のリクエストに診断オブジェクトが付いていなかった、別のワークスペースだった、時間が空きすぎた、のいずれかが典型的な原因です。この結果を見て設計を疑う前に、ログの取り方を確認してください。

KPI設計と費用・工数の目安

KPIは「入力トークン全体に占めるキャッシュ読み込みの比率」を業務別に追うのが基本です。問い合わせ返信や商品説明生成のように、同じシステムプロンプトを繰り返し使う業務では、比率が低いこと自体が改善の余地を示します。直近の支援案件で観測した範囲では、システムプロンプトの動的情報を移動しただけで、入力コストが目に見えて下がるケースが少なくありません(効果の大きさは業務とプロンプトの長さ次第で、目安として扱ってください)。

工数面では、診断オブジェクトの追加とログ出力は、既存の呼び出し処理に数行足す程度の改修で済むことが多いと考えられます。原因別の修正も、システムプロンプトの分離やツール定義の並び順の固定が中心で、大規模な作り直しは不要な場合がほとんどです。開発会社に依頼する場合は、半日〜数日の規模感を目安に見積もりを取るとよいでしょう。

費用面では、キャッシュ診断そのものに追加料金がかかるという記載は公式ドキュメントに見当たりません。ただし、料金体系は改定されることがあるため、導入前にAnthropicの公式料金ページで最新条件を確認してください。AIのタスク単位のコスト感については、Opus 5.5のタスク単価とキャッシュの関係の解説もあわせて参考になります。

今後の展望と独自考察

キャッシュ診断の登場で、AIのコスト管理は「月末の請求額を見て驚く」段階から「リクエスト単位で原因を特定して直す」段階へ進みました。EC事業者にとっての意味は、AI活用の費用を経営側に説明しやすくなる点にあります。

今後は、AIエージェントが複数のツールを呼び分け、長い会話を続ける場面が増えます。ツールの増減や履歴の扱いがキャッシュに与える影響は大きくなる一方なので、診断ログを業務KPIと並べて見る運用は、早めに型を作っておくほど有利です。Claude Codeでも、利用状況の表示でキャッシュが外れた理由の推定を示す改善が第三者の解説記事で報告されており、開発ツール側でも同じ方向の改善が進んでいます。

GPT-6系やGeminiでも同様の診断が整えば、モデル横断で「どの業務がどのモデルで一番安く回るか」を、キャッシュ込みで比較できるようになります。そのときに効いてくるのは、どのモデルでも通用する「固定部分を前、変動部分を後ろ」という設計の徹底です。トークンコスト全体の考え方は、AIのトークンコスト最適化の解説でも整理しています。

よくある質問

プロンプトキャッシュ診断とは何ですか?

プロンプトキャッシュ診断とは、キャッシュが外れたときに、前回のリクエストとどこが違ったのかをAPIが返す機能のことです。Claudeでは、モデル・システムプロンプト・ツール・会話履歴のどこで食い違ったかが分かります。原因を推測で探す時間を減らせるのが利点です。

キャッシュ診断を使うと追加料金はかかりますか?

公式ドキュメントには追加料金の記載は見当たりません。ただし料金体系は変わることがあるため、導入前に公式の料金ページで最新条件を確認してください。診断はリクエストを止めない設計なので、本番環境に入れても処理への影響は小さいとされています。

Amazon BedrockでもClaudeのキャッシュ診断は使えますか?

公式ドキュメントの対応プラットフォームには、Claude APIとGoogle Cloud上のAnthropic管理版の2つだけが記載されています。Amazon Bedrock経由で使っている場合は、対応状況を公式ドキュメントで確認してください。本記事執筆時点では記載がないため、要確認です。

previous_message_not_foundが出たら設定ミスですか?

いいえ、リクエストの内容が変わったという意味ではありません。前回のリクエストに診断オブジェクトが付いていなかった、別のワークスペースで実行された、時間が空きすぎて記録が失効した、のいずれかが典型的な原因です。毎ターン診断を付け、連続するリクエストの間隔を短く保つと解消します。

GPT-6系でも同じように外れた理由が分かりますか?

現時点では、OpenAIの公式ドキュメントで同等の診断機能は確認できていません(要確認)。GPT-6系では、応答のusageに含まれるキャッシュ済みトークン数で当たり具合を見て、外れた理由はリクエストの比較ログで推理するのが基本です。

小規模なEC事業者でも取り組む価値はありますか?

はい、同じシステムプロンプトを繰り返し使う業務があるなら価値があります。問い合わせ返信や商品説明の一括生成は、件数が少なくてもシステムプロンプトが長いと固定部分の読み込みコストが目立ちます。まずは日付などの動的情報をシステムプロンプトから外すだけでも効果を確かめられます。

まとめ

プロンプトキャッシュ診断は、キャッシュが外れた原因を「モデル・システムプロンプト・ツール・会話履歴」のどこで食い違ったかとして返してくれる、Claude APIの機能です。GPT-6系では当たり具合の確認が中心で、原因の切り分けはログ設計に頼る部分が残ります。EC事業者は、システムプロンプトを固定の文書として扱い、動的情報を後ろへ移す設計を徹底したうえで、業務別のキャッシュ読み込み比率を月次で追うことから始めるのが現実的です。

参考文献


著者:齋藤竹紘(株式会社オルセル 編集長/5,000社以上のEC支援実績/書籍3冊)


※うるチカラでは、生成AIの導入支援から運用最適化まで、貴社のEC事業に合わせたカスタマイズ提案を行っています。無料相談(30分)も実施中ですので、お気軽にお問い合わせください。
https://uruchikara.jp/contact/


【監修】齋藤竹紘(株式会社オルセル代表 / 19年・5,000社のEC支援実績)


投稿者: 齋藤竹紘

株式会社オルセル代表取締役 / うるチカラ編集長。19年・5,000社以上のEC支援実績を持ち、楽天市場・Amazon・Yahoo!ショッピング・Shopify・Shopee越境ECの実装ノウハウを保有。AI×ECに関する書籍を3冊執筆。「現場で使えるAI実装」を一次情報として発信しています。

お問い合わせ