マルチモデル API ゲートウェイでのプロンプト キャッシュ制御: 安定したプレフィックス、テナントの分離、およびキャッシュ ヒット分析
OpenAI、Anthropic、および Gemini スタイルの API 全体でプロンプト キャッシュ ヒット率を保護するための実用的なゲートウェイ アーキテクチャ: 安定したプロンプト領域、プロバイダー メトリックの正規化、テナントの分離、請求の帰属、ロールアウト チェック。
即時キャッシュは無駄になりやすいです。チームには、再利用可能である必要がある 40,000 トークンのシステム プロンプト、ツール スキーマ、ポリシー ブロック、リポジトリ マップ、またはエージェント メモリがある場合に、誤ってタイムスタンプ、リクエスト ID、ユーザー名、取得スニペット、またはランダム化されたツールの順序をプロンプトの先頭付近に配置してしまう可能性があります。プロバイダーは別のプレフィックスを認識し、キャッシュが失われ、遅延が増加し、請求書がわかりにくくなります。
単一プロバイダーのアプリケーションでは、アプリケーション テンプレート内でこれを修正できます。マルチモデルのゲートウェイでは、問題はさらに大きくなります。各プロバイダーは、異なるキャッシュ制御、トークンしきい値、有効期間の動作、使用状況フィールド、および請求セマンティクスを公開しています。ゲートウェイには、キャッシュセーフなプロンプトの組み立て、キャッシュの動作の測定、テナントの分離、コストの帰属を行うためのポータブルなコントロール プレーン パターンが必要です。
この記事では、リファレンス アーキテクチャについて説明します。これは顧客のケーススタディではなく、ベンチマーク結果を主張するものではありません。以下の事実は、プロバイダーの文書と公的調査から得られたものです。設計上の推奨事項は、ゲートウェイ レベルの運用ガイダンスです。
障害モード: キャッシュ破壊プロンプト アセンブリ
プロンプト キャッシュでは、通常、プロンプト プレフィックスが繰り返されると報酬が得られます。正確な仕組みはプロバイダーによって異なりますが、実際的な意味は一貫しています。プロンプトの先頭が変更されると、再利用が困難になります。
一般的なキャッシュ ブレーカーには次のようなものがあります:
- 上部のリクエストごとのメタデータ: タイムスタンプ、トレース ID、セッション ID、デプロイメント ID、または生成されたリクエスト ラベル。
- プレフィックス内のユーザー固有のデータ: 再利用可能なポリシーまたはツール ブロックの前に配置される名前、アカウント属性、権限、またはプライベート設定。
- ツールのシリアル化が不安定です: ツール スキーマが非決定的な順序で発行され、空白または生成された ID が変更されます。
- スニペットの取得が早すぎます: 安定したシステム命令または共有リポジトリ コンテキストの前に RAG コンテキストが挿入されました。
- テンプレートのドリフト: バージョン管理やキャッシュ診断なしで頻繁にリリースされる小さな文言の変更。
ゲートウェイは、魔法のように不安定なプレフィックスをキャッシュ可能にすることはできませんが、プロンプト アセンブリ コントラクトを強制し、キャッシュ ミスを可視化することはできます。
設計に必要な事実を提供する
ゲートウェイはプロバイダーが同一であるかのように振る舞うことなく動作を正規化する必要があるため、詳細が重要です。
- OpenAI: OpenAI には、以前に計算された最長のプロンプト プレフィックスのプロンプト キャッシュが文書化されています。 1,024 トークンから始まり、128 トークンずつ増加し、キャッシュされたトークン数が使用状況フィールドに公開されます。 OpenAI は、プロンプト キャッシュは通常、非アクティブ状態が 5 ～ 10 分間続くとクリアされ、キャッシュが最後に使用されてから 1 時間以内に常に削除されるとも述べています。
- Anthropic: Anthropic プロンプト キャッシュは
cache_controlでリクエストできます。そのドキュメントでは、ツール、システム コンテンツ、メッセージなどのプロンプト コンポーネントをキャッシュ制御でマークされたブロックまでのキャッシュ マッチングについて説明しています。 Anthropic には、5 分間の期間と、追加料金で 1 時間のオプションを含む一時キャッシュが文書化されています。 - Gemini: Google Gemini コンテキスト キャッシュは、
total_cached_tokensなどの使用状況メタデータを通じてキャッシュ ヒット トークン数を公開し、そのドキュメントにはモデルごとの最小入力トークン数がリストされています。 - データ制御の意味: OpenAI の API データ制御ドキュメントには、拡張プロンプト キャッシュではキー/値テンソルをアプリケーションの状態として GPU ローカル ストレージに保存する必要があると記載されています。プロバイダーが分離保証を維持する場合でも、ゲートウェイはキャッシュの動作を共有アプリケーション データストアとしてではなく、機密性の高いインフラストラクチャとして扱う必要があります。
- 調査シグナル: 公的調査では、ゲートウェイ スタイルのアーキテクチャが、プロバイダー レベルのキャッシュ分離の前提をバイパスするプロンプト キャッシュの脆弱性を導入する可能性があるかどうかを調査しました。これは特定のゲートウェイが脆弱であることを証明するものではありませんが、保守的なテナント分離設計をサポートしています。
推奨事項: キャッシュ制御は、プロンプトの繰り返しによる偶発的な副作用としてではなく、明示的なポリシーを備えたゲートウェイ機能として実装します。
3 地域の即時組み立て契約
最も重要な設計上の決定は、リクエストがプロバイダー アダプターに到達する前に、安定したコンテンツと揮発性のコンテンツを分離することです。
リージョン 1: 安定したプレフィックス
安定したプレフィックスは、同じアプリケーション、モデル ルート、プロンプト テンプレート バージョンに対する多くのリクエストにわたって同一のままであると予想されるコンテンツです。例:
- コア システム命令;
- 安全性とポリシーのブロック;
- ツールスキーマ;
- 静的な製品ドキュメント;
- コーディング エージェント用のリポジトリ マップ;
- 出力形式の命令を修正しました。
この領域は決定的である必要があります。ゲートウェイは、バージョン管理されたテンプレート、正規化された JSON、および安定した順序付けルールからそれを構築する必要があります。ツール レジストリが含まれている場合は、安定したツール ID でツールを並べ替えます。 JSON スキーマが含まれている場合は、決定的なキー順序付けと生成されたタイムスタンプなしでシリアル化します。
リージョン 2: 準安定テナントまたはワークスペース コンテキスト
準安定領域は、個々のリクエストよりも頻繁に変更されませんが、グローバルに共有されません。例:
- テナント固有のポリシーの上書き;
- ワークスペースレベルのツール許可リスト;
- 顧客固有の用語;
- チームのコーディング規約;
- 長期にわたるプロジェクトのコンテキスト。
このリージョンは、テナント、ワークスペース、またはアプリケーション境界にスコープする必要があります。まだキャッシュ可能である可能性がありますが、ゲートウェイは別のテナントがそれを安全に再利用できると想定してはいけません。
領域 3: 揮発性サフィックス
揮発性サフィックスはリクエストごとの部分です:
- ユーザーメッセージ;
- このクエリのスニペットを取得しました;
- 本当に必要な場合は現在のタイムスタンプ;
- プロンプトに含まれている場合は、ID とトレース メタデータをリクエストします。
- 短期間の会話の転換;
- ランタイム ツールの結果。
アプリケーションの設計が原因で発生するキャッシュ ミスのほとんどは、揮発性のサフィックス データが誤ってプレフィックスに配置されたために発生します。ゲートウェイ側のビルダーはそれを困難にする必要があります。
実装パターン: 安定したプレフィックス ビルダー
実際のゲートウェイ実装では、すべてのアプリケーションから 1 つの不透明なプロンプト文字列を受け入れるのではなく、プロンプト アセンブリ インターフェイスを公開できます。
{
"template_id": "code-agent-v3",
"tenant_id": "tenant_123",
"route": "coding-long-context",
"stable_prefix": {
"system_policy_version": "2026-08-01",
"toolset_version": "tools-v12",
"repo_context_version": "repo-map-8491"
},
"semi_stable_context": {
"workspace_policy_version": "workspace-44-v6"
},
"volatile_suffix": {
"user_message": "Explain why this test fails...",
"retrieval_context_ids": ["chunk_7", "chunk_19"],
"trace_id": "not_inserted_into_prompt"
}
}その後、ゲートウェイはプロバイダー固有のリクエストをレンダリングします。これにより、ゲートウェイにルールを適用する場所が与えられます:
- 安定したプレフィックス フィールドのタイムスタンプを拒否します;
- ツール スキーマを正規化する;
- 各リージョンを個別にハッシュする;
- プロバイダーがサポートするキャッシュ コントロールを接続します;
- 揮発性マテリアルを後で移動する間、プロンプト セマンティクスを保持します;
- 診断用のテンプレートとプレフィックス フィンガープリントを記録します。
生のメッセージのみを送信するレガシー アプリケーションの場合でも、ゲートウェイは引き続き lint モードを提供できます。最初にプロンプトを書き換えることなく、メッセージの順序を検査し、プレフィックス フィンガープリントを計算し、キャッシュ ブレーカーの可能性を報告します。
プロバイダー アダプター層: 違いを隠さずにキャッシュの使用量を正規化します
マルチモデル ゲートウェイは、無関係な 3 つのキャッシュ レポートを開発者に公開すべきではありません。また、請求書を説明できなくなるほど、プロバイダー固有の経済性をあまりにも積極的に平坦化すべきではありません。
次のようなフィールドを含む正規化されたキャッシュ台帳を作成します:
{
"request_id": "req_abc",
"tenant_id": "tenant_123",
"app_id": "code-agent",
"route": "coding-long-context",
"provider": "provider_name",
"model": "model_id",
"template_id": "code-agent-v3",
"stable_prefix_hash": "sha256:...",
"semi_stable_hash": "sha256:...",
"input_tokens_total": 58200,
"input_tokens_uncached": 8200,
"cache_write_tokens": 50000,
"cache_read_tokens": 0,
"output_tokens": 1300,
"cache_ttl_class": "ephemeral_5m",
"provider_cache_fields": {
"raw_field_names": "stored_or_redacted_provider_usage"
}
}アダプターはプロバイダーの使用状況を正規化されたカテゴリにマッピングします:
- キャッシュされていない入力トークン: トークンは、キャッシュ読み取り割引またはキャッシュ読み取りアカウンティングなしで処理されました。
- キャッシュ書き込みトークン: プロバイダーがこの区別を報告したときにプロバイダー側のキャッシュ エントリを作成または更新したトークン。
- キャッシュ読み取りトークン: キャッシュから提供されるトークン、またはプロバイダーの使用状況メタデータによってキャッシュされたものとしてカウントされるトークン。
- 出力トークン: 生成されたトークン。これはプロンプト キャッシュの経済性から切り離されている必要があります。
- TTL オプション: プロバイダが選択肢を公開する、選択されたキャッシュ期間クラス。
推奨事項: 生のプロバイダーの使用状況を、正規化されたフィールドとともに編集され、スキーマ バージョン管理された形式で保存します。正規化はダッシュボードに役立ちます。生のフィールドは、プロバイダーのセマンティクスが変更された場合の調整に必要です。
キャッシュの可観測性: ミスを説明するダッシュボード
便利なキャッシュ ダッシュボードは、キャッシュされたトークンの合計を表示するだけではありません。これは、チームが「どのワークロードがプレフィックスを壊しているのか、何が変更されたのか?」に答えるのに役立つはずです
次の方法でキャッシュ指標を追跡します:
- テナント;
- ワークスペースまたはアプリ;
- モデルルート;
- プロバイダーとモデル;
- プロンプト テンプレート バージョン;
- 安定したプレフィックス ハッシュ;
- 半安定コンテキストハッシュ;
- API キーまたはサービス アカウント (該当する場合);
- 時間枠、特に多くのワークロードではキャッシュ TTL が短いためです。
有用な派生指標には次のものがあります:
- キャッシュ読み取り率: キャッシュされた入力トークンをキャッシュ対象の合計入力トークンで割った値。
- プレフィックス チャーン: テンプレート バージョンごとの 1 時間あたりの個別の安定したプレフィックス ハッシュの数。
- テンプレートのドリフト: テンプレートのリリース後にキャッシュ ヒットが変更されます。
- コールド スタート コスト: バースト内の最初のリクエストに対するキャッシュ書き込みまたはキャッシュされていない入力の消費。
- ルートの比較: 同じ論理ワークロードのプロバイダ ルート間のヒット率。
デバッグ用に生のプロンプトをデフォルトで保存しないでください。ハッシュ、領域の長さ、テンプレート ID、正規化の警告、および編集された差分を優先します。チームがより詳細なデバッグを必要とする場合は、明示的なアクセス制御と保持制限を必要とします。
テナント分離ポリシー: テナント間で再利用できるように設計しないでください
ゲートウェイの最も安全な前提は単純です。キャッシュ可能な動作はテナント スコープである必要があります。 2 つのテナントが同一のパブリック ポリシー ブロックを共有している場合でも、ゲートウェイは、クロステナント キャッシュの再利用を利用するためにトラフィックを意図的にルーティングまたはシェーピングすべきではありません。
保守的なポリシーには次のものが含まれます:
- テナント対応ルーティング: テナント、ワークスペース、アプリケーションの境界を使用してキャッシュ可能なトラフィックをルーティングします。
- 共有シークレットを含むプレフィックスを使用しない: 再利用可能な共有プレフィックスにテナントのシークレット、資格情報、プライベート ドキュメント、またはユーザー固有のデータを決して配置しないでください。
- プレフィックス フィンガープリントを分離する: レンダリングされたテキストが同一であっても、ゲートウェイ台帳に含まれるテナント スコープでフィンガープリントを計算します。
- 組織レベルの制御: 管理者は機密ワークロードのプロバイダー キャッシュ機能を無効にできます。
- プロバイダの分離は再販できる製品機能ではありません: プロバイダのキャッシュ分離は、顧客間キャッシュ プーリングを構築するための許可としてではなく、ベースラインの保護として扱います。
予測: ロングコンテキスト エージェントがより一般的になるにつれて、キャッシュの動作はコストのレビューだけでなくセキュリティのレビューの一部になるでしょう。テナントを対象としたキャッシュ ポリシーを証明できるゲートウェイは、管理が容易になります。
課金属性: 個別のキャッシュ読み取り、書き込み、および通常のトークン
すべての入力トークンが 1 つの数字として表示される場合、プロンプト キャッシュにより請求書が理解しにくくなる可能性があります。請求元帳には少なくとも 5 つのカテゴリを保存する必要があります:
- キャッシュされていない入力トークン;
- キャッシュ書き込みトークン;
- キャッシュ読み取りトークン;
- 出力トークン;
- プロバイダー固有の TTL またはキャッシュ制御料金。
これは、あるプロバイダーがキャッシュされた読み取りを割引し、別のプロバイダーがキャッシュ書き込みに対して異なる料金を請求し、別のプロバイダーがより長い TTL オプションを公開している場合に重要になります。顧客の請求書には、同様の合計入力トークンを持つ 2 つのリクエストでコストが異なる理由を説明できる必要があります。
内部チャージバックの場合、キャッシュの影響をリクエストを行ったテナントとアプリケーションに帰属させます。キャッシュ読み取りの利点をあるテナントから別のテナントに割り当てることは避けてください。共有内部プラットフォーム チームが安定したプロンプト テンプレートを所有している場合は、テナントの請求書とは別にテンプレート レベルのキャッシュ パフォーマンスを報告します。
キャッシュ lint チェックリスト
キャッシュの強制を有効にする前に、lint チェックリストを通じてプロンプト テンプレートを実行します:
- 安定したシステム命令は、不安定なユーザー入力の前に表示されます。
- ツール スキーマは安定した ID または名前で並べ替えられます。
- JSON は決定的にシリアル化されます。
- 安定したプレフィックスには、タイムスタンプ、ランダム ID、リクエスト ID、またはトレース ID は表示されません。
- 共有再利用可能ブロックにはユーザー固有のシークレットは表示されません。
- 意図的な理由がない限り、RAG スニペットは再利用可能なポリシーとツールのセクションの後に配置されます。
- プロンプト テンプレートには明示的なバージョンがあります。
- テンプレートのリリースは、キャッシュ ヒット率の変化と関連付けることができます。
- プロバイダー キャッシュ コントロールは、散在するアプリケーション ロジックではなく、アダプター コードを通じてのみ使用されます。
- 生のプロンプト ログはデフォルトで無効になっているか、厳密な保持ルールとアクセス ルールによって保護されています。
展開計画
1.プロンプトを変更する前に注意してください
まず、プロバイダーの使用状況フィールドと既存のトラフィックの正規化されたキャッシュ メトリックを収集します。最初の N 個のトークンまたはゲートウェイ定義のプロンプト領域のプレフィックス フィンガープリントを計算します。目標は、プレフィックス チャーンの多い大量のコンテキストの長いルートを見つけることです。
2.ワークロードの分類
トラフィックをカテゴリにグループ化します: エージェント セッション、コーディング アシスタント、RAG、サポート自動化、ドキュメント分析、バッチ ジョブ、短いチャット。プロンプト キャッシュ作業では、通常、長いコンテキストと繰り返しのプレフィックスのワークロードに最も注意が払われます。プロバイダーのしきい値を下回る短いプロンプトでは効果が得られない可能性があります。
3.安定したプレフィックス ビルダーを導入
1 つのワークロードを生のプロンプト構築からリージョンベースのアセンブリに移動します。レンダリングされたプロバイダー要求を意味的に同等に保ちます。この変更をモデルの移行、ツールの再設計、またはプロンプトの大幅な書き換えと組み合わせないでください。そうしないと、メトリクスの変更の原因が分からなくなります。
4.カナリア 1 ルート
1 つのテナントまたは内部アプリの小さなスライスに対してキャッシュ制御を有効にします。キャッシュ読み取り率、プレフィックス チャーン、最初のトークンまでの時間、エラー率、コスト カテゴリを比較します。プロバイダーの請求書がゲートウェイ台帳と一致するまでは、節約の請求を避けてください。
5.段階的に強制
カナリアの後は、lint 警告をポリシー チェックに変えます。たとえば、最初に不安定なツールの順序について警告し、その後、安定したプレフィックスに揮発性のメタデータを含む新しいテンプレート バージョンを拒否します。
トレードオフ
- 高いキャッシュ ヒット率とプロンプトの柔軟性: 安定したプレフィックスにより再利用性が向上しますが、チームは後で動的命令を移動するか、テンプレートを再設計する必要がある場合があります。
- プロバイダー ネイティブのキャッシュと移植性: 各プロバイダーのキャッシュ制御を使用すると経済性が向上しますが、しきい値、TTL、フィールド、および価格設定のセマンティクスが異なります。
- 可観測性と機密性の高いロギング: プロンプトの差分はデバッグミスの解決に役立ちますが、ハッシュと編集された診断はより安全なデフォルトです。
- テナントの分離と最大限の再利用: 広範な再利用は魅力的に見えるかもしれませんが、テナントを対象とした動作の方が安全で説明が簡単です。
- 長期保存とコストとポリシーの複雑さ: TTL オプションを長くすると、エージェント セッションに役立ちますが、料金設定やデータ管理の考慮事項が異なる可能性があります。
実用的な結論
プロンプト キャッシュをプロバイダーのチェックボックスではなく、ゲートウェイ コントロール プレーンの問題として扱います。実際のパターンは次のとおりです。安定、半安定、および揮発性のプロンプト領域を定義します。それらを決定論的にレンダリングします。プロバイダー固有のキャッシュ制御を 1 つのインターフェイスの背後に適応させます。キャッシュの使用量を台帳に正規化します。テナント、アプリ、ルート、テンプレートのバージョンごとにキャッシュ ヒットの診断を公開します。テナントを対象とした前提条件を適用します。
最初の有用なステップは書き換えではありません。最長のプロンプトにキャッシュの可観測性を追加し、プレフィックスのチャーンを特定し、最も多くのミスの原因となっているテンプレートをリントします。キャッシュの動作を説明できれば、キャッシュを安全に最適化できます。