マルチモデル 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": "コードエージェント-v3",
"テナントID": "テナント_123",
"ルート": "コーディング-ロングコンテキスト",
"stable_prefix": {
"system_policy_version": "2026-08-01",
"toolset_version": "tools-v12",
"repo_context_version": "repo-map-8491"
}、
"準安定コンテキスト": {
"workspace_policy_version": "workspace-44-v6"
}、
"volatile_suffix": {
"user_message": "このテストが失敗する理由を説明してください...",
"retrieval_context_ids": ["chunk_7", "chunk_19"],
"trace_id": "not_inserted_into_prompt"
}
}その後、ゲートウェイはプロバイダー固有のリクエストをレンダリングします。これにより、ゲートウェイにルールを適用する場所が与えられます。
- 安定したプレフィックス フィールドのタイムスタンプを拒否します。
- ツール スキーマを正規化する;
- 各リージョンを個別にハッシュします。
- プロバイダがサポートするキャッシュ コントロールを接続します。
- プロンプトのセマンティクスを維持しながら、揮発性のマテリアルを後で移動する
- 診断用のテンプレートとプレフィックス フィンガープリントを記録します。
生のメッセージのみを送信するレガシー アプリケーションの場合、ゲートウェイは引き続き lint モードを提供できます。つまり、最初にプロンプトを書き換えることなく、メッセージの順序を検査し、プレフィックス フィンガープリントを計算し、キャッシュ ブレーカーの可能性を報告します。
プロバイダー アダプター層: 違いを隠さずにキャッシュの使用量を正規化する
マルチモデル ゲートウェイは、無関係な 3 つのキャッシュ レポートを開発者に公開しないでください。また、請求書の説明が不可能になるほど、プロバイダー固有の経済性をあまりにも積極的に平坦化すべきではありません。
次のようなフィールドを含む正規化されたキャッシュ台帳を作成します。
{
"request_id": "req_abc",
"テナントID": "テナント_123",
"app_id": "コードエージェント",
"ルート": "コーディング-ロングコンテキスト",
"プロバイダー": "プロバイダー名",
"モデル": "モデルID",
"template_id": "コードエージェント-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、
「出力トークン」: 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 オプションを公開している場合に重要になります。顧客の請求書には、入力トークンの合計が同様の 2 つのリクエストでコストが異なる理由を説明できる必要があります。
内部チャージバックの場合、キャッシュの影響をリクエストを行ったテナントとアプリケーションに帰属させます。キャッシュ読み取りの利点をあるテナントから別のテナントに割り当てることは避けてください。共有内部プラットフォーム チームが安定したプロンプト テンプレートを所有している場合は、テナントの請求書とは別にテンプレート レベルのキャッシュ パフォーマンスを報告します。
キャッシュ lint チェックリスト
キャッシュの強制を有効にする前に、lint チェックリストを通じてプロンプト テンプレートを実行します。
- 不安定なユーザー入力の前に、安定したシステム命令が表示されます。
- ツール スキーマは安定した ID または名前で並べ替えられます。
- JSON は決定論的にシリアル化されます。
- 安定したプレフィックスには、タイムスタンプ、ランダム ID、リクエスト ID、トレース ID は表示されません。
- 共有再利用可能ブロックにはユーザー固有のシークレットは表示されません。
- 意図的な理由がない限り、RAG スニペットは再利用可能なポリシー セクションとツール セクションの後に配置されます。
- プロンプト テンプレートには明示的なバージョンがあります。
- テンプレートのリリースは、キャッシュ ヒット率の変化と関連付けることができます。
- プロバイダ キャッシュ コントロールは、散在するアプリケーション ロジックではなく、アダプター コードを通じてのみ使用されます。
- 生のプロンプト ロギングはデフォルトで無効になっているか、厳格な保持ルールとアクセス ルールによって保護されています。
展開計画
1.プロンプトを変更する前に注意してください
まず、プロバイダーの使用状況フィールドと既存のトラフィックの正規化されたキャッシュ メトリックを収集します。最初の N 個のトークンまたはゲートウェイ定義のプロンプト領域のプレフィックス フィンガープリントを計算します。目標は、プレフィックス チャーンが多い、大量のコンテキストが長いルートを見つけることです。
2.ワークロードを分類する
トラフィックをカテゴリにグループ化します: エージェント セッション、コーディング アシスタント、RAG、サポート自動化、ドキュメント分析、バッチ ジョブ、ショート チャット。プロンプト キャッシュ作業では、通常、長いコンテキストと繰り返しのプレフィックスのワークロードに最も注意が払われます。プロバイダーのしきい値を下回る短いプロンプトでは、メリットが得られない可能性があります。
3.安定したプレフィックス ビルダーの導入
1 つのワークロードを未処理のプロンプト構築からリージョンベースのアセンブリに移動します。レンダリングされたプロバイダー要求を意味的に同等に保ちます。この変更をモデルの移行、ツールの再設計、またはプロンプトの大幅な書き換えと組み合わせないでください。組み合わせないと、メトリクスの変更の原因が分からなくなります。
4.カナリア 1 ルート
1 つのテナントまたは内部アプリの小さなスライスに対してキャッシュ制御を有効にします。キャッシュ読み取り率、プレフィックス チャーン、最初のトークンまでの時間、エラー率、コスト カテゴリを比較します。プロバイダーの請求書がゲートウェイ元帳と一致するまでは、節約の請求を避けてください。
5.段階的に強制
カナリアの後は、lint 警告をポリシー チェックに変えます。たとえば、最初に不安定なツールの順序について警告し、その後、安定したプレフィックスに揮発性メタデータを含む新しいテンプレート バージョンを拒否します。
トレードオフ
- 高いキャッシュ ヒット率とプロンプトの柔軟性: 安定したプレフィックスにより再利用性が向上しますが、チームは後で動的な命令を移動したり、テンプレートを再設計したりする必要がある場合があります。
- プロバイダネイティブのキャッシュと移植性: 各プロバイダのキャッシュ制御を使用すると経済性が向上しますが、しきい値、TTL、フィールド、価格設定のセマンティクスが異なります。
- 可観測性と機密性の高いロギング: プロンプトの差分はデバッグミスの解決に役立ちますが、ハッシュと編集された診断はより安全なデフォルトです。
- テナントの分離と最大限の再利用: 広範な再利用は魅力的に見えるかもしれませんが、テナントを対象とした動作の方が安全で説明が簡単です。
- コストとポリシーの複雑さに対する保持期間の延長: TTL オプションを長くすると、エージェント セッションに役立ちますが、料金設定やデータ管理の考慮事項が異なる可能性があります。
実行可能な結論
プロンプト キャッシュをプロバイダーのチェックボックスではなく、ゲートウェイ コントロール プレーンの問題として扱います。実際のパターンは次のとおりです。安定、半安定、および揮発性のプロンプト領域を定義します。それらを決定論的にレンダリングします。プロバイダー固有のキャッシュ制御を 1 つのインターフェイスの背後に適応させます。キャッシュの使用量を台帳に正規化します。テナント、アプリ、ルート、テンプレートのバージョンごとにキャッシュ ヒットの診断を公開します。テナントを対象とした前提条件を適用します。
最初の有用なステップは書き換えではありません。最長のプロンプトにキャッシュの可観測性を追加し、プレフィックスのチャーンを特定し、最も多くのミスの原因となっているテンプレートをリントします。キャッシュの動作を説明できれば、キャッシュを安全に最適化できます。