メインコンテンツへスキップ
Prompt Caching (プロンプトキャッシング) は、繰り返し使用されるプロンプトのプレフィックス (接頭部分) に対する計算結果をキャッシュすることで、処理時間を節約する機能です。キャッシュされるのはプロンプトのテキストそのものではなく、それを処理するために行われた計算です。複数のリクエストが同じ冒頭テキスト (システムプロンプトやドキュメントなど) を共有する場合、SambaNova はそれらのトークンを最初から再処理する代わりに、キャッシュされた結果を利用します。最初の数リクエストでサービングノード上にキャッシュが作成され、同じプレフィックスが繰り返し観測されるにつれて節約効果が積み上がります。継続的なトラフィックでは、プレフィックスが数回観測された後、ヒット率は通常 90% 以上に達します。 Prompt Caching は、SambaStack の v2.0.2 リリース以降、MiniMax-M2.7 向けの安定版 (一般提供) 機能です。 v2.2.3 では、MiniMax-M3 でも Preview (プレビュー) 機能として Prompt Caching を利用できます。v2.2.5 では、MiniMax-M3 の Prompt Caching バンドルが画像入力も受け付けるようになりました。v2.3 では、動画入力も受け付けるようになりました。画像または動画を含むリクエストは、それらが以前のターンに含まれる場合も、Prompt Caching なしで処理されます。 v2.2.5 では、glm-5-3-acb-prefix-caching バンドルを対象として、GLM-5.3 でも Preview 機能として Prompt Caching を利用できます。このバンドルはテキスト入力のみを受け付けます。 v2.2.5 では、gemma-4-31b-acb-prefix-caching バンドルを対象として、gemma-4-31B-it でも Prompt Caching を利用できます。v2.3 では、このバンドルが画像・動画入力も受け付けるようになったほか、最大 32K のコンテキストで Prompt Caching を利用できる gemma-4-31b-acb-prefix-caching-32k バンドルが追加されました。画像または動画を含むリクエストは、それらが以前のターンに含まれる場合も、Prompt Caching なしで処理されます。 v2.3 では、minimax-m3-1-flash-acb-prefix-caching および minimax-m3-1-flash-32k-acb-prefix-caching バンドルを対象として、MiniMax-M3.1-Flash でも Preview 機能として Prompt Caching を利用できます。これらのバンドルはテキスト・画像・動画入力を受け付けます。画像または動画を含むリクエストは、それらが以前のターンに含まれる場合も、Prompt Caching なしで処理されます。
本ページでは、Prompt Caching の使い方と usage フィールドの読み方を説明します。モデルの提供状況については、対応モデルとバンドル をご覧ください。

Prompt Caching を使用すべきケース

Prompt Caching は、入力の大部分がリクエスト間で繰り返される場合に、最も大きな節約効果を発揮します。 cached_tokens がリクエストをまたいで 0 のままの場合、入力がキャッシュ可能なプレフィックスを共有していません。システムプロンプトやコンテキストブロックが呼び出し間で安定しているかどうかを見直してください。

Prompt Caching の仕組み

Automatic Prefix Caching (APC: 自動プレフィックスキャッシング) は MiniMax-M2.7 で利用できますが、SambaStack 管理者が次の手順で有効化する必要があります。
  1. プロンプトキャッシング用バンドル——dyt-minimax-m2p7-32-64-160-192k-pc (32K–192K) または dyt-minimax-m2p7-32k-pc (最大 32K)——をデプロイするか、minimax-m2p5-dyt-pc-cd モデルプロファイルを使用して ModelDeployment リソースで MiniMax-M2.7 を直接デプロイします。
  2. ModelDeployment リソースに次の環境変数を設定します。
プロファイル名 minimax-m2p5-dyt-pc-cd は、MiniMax-M2.5 と MiniMax-M2.7 が共有する PEF を指しています。そのため、MiniMax-M2.7 をサービングする場合でも m2p5 というセグメントが含まれるのは想定どおりです。
有効化されると、APC はリクエスト間で共有されるプレフィックスを検出し、キャッシュされた計算結果を透過的に再利用します。API リクエストの変更は必要ありません。 Prompt Caching は OpenAI 標準に準拠しています。キャッシュヒットは自動的に検出され、レスポンスの usage フィールドで報告されます。cache_control マーカーやその他のリクエストボディの変更は不要です。 APC は各サービングインスタンスに対してローカルに動作します。キャッシュされた KV ステートはローカルの DDR に保存され、インスタンス間で転送されません。マルチインスタンスのデプロイメントでは、プレフィックスは各インスタンスで処理された後に、それぞれのインスタンス上で独立してキャッシュされます。MiniMax-M2.7 のシーケンスステートプールのサイズは 192K です。

PEF から取得される設定

v2.3 では、MiniMax-M3、MiniMax-M3.1-Flash、GLM-5.3、gemma-4-31B-it の各 Prompt Caching バンドルは、キャッシュ設定をコンパイル済みモデル (PEF) から取得します。
  • PEF が Prompt Caching をサポートしている場合、エンジンは ENABLE_KV_CACHE_MANAGER と KV_CACHE_INCLUDE_STATS_IN_RESPONSE を有効にします。
  • エンジンは、キャッシュページサイズと DDR ページプールを PEF から読み取ります。
  • ルーターは、smart_routing.block_hash_size を PEF のページサイズに設定します。
これらの値は引き続きオーバーライドとして設定できますが、PEF と一致している必要があります。
  • KV_CACHE_BLOCK_SIZE は、PEF のページサイズと一致している必要があります。それ以外の値を設定すると、エンジンは起動時に停止します。
  • KV_CACHE_NUM_DDR_BLOCKS では DDR ページプールを縮小できますが、プールを超える値は設定できません。GLM-5.3 では、PEF のプールと一致している必要があります。
  • modelSpecs に設定した smart_routing.block_hash_size は、PEF から取得した値を置き換えます。ルーターはキャッシュページ単位でプロンプトをハッシュ化するため、この値はページサイズと一致している必要があります。

MiniMax-M3 での Prompt Caching の有効化

  1. 連続バッチングを aggregate に設定して、minimax-m3-acb-prefix-caching (最大 1M のコンテキスト)、またはコンテキスト上限を制限したバンドル (minimax-m3-32k-acb-prefix-caching、minimax-m3-256k-acb-prefix-caching、minimax-m3-512k-acb-prefix-caching、minimax-m3-1m-acb-prefix-caching) をデプロイします。構成のデプロイ をご参照ください。
  2. ModelDeployment リソースに KV_CACHE_NUM_DDR_BLOCKS を設定します。
MiniMax-M3 は、4,096 トークンのページ単位でプロンプトをキャッシュします。再利用されるのは、過去のリクエストと一致するページ全体のみです。

MiniMax-M3.1-Flash での Prompt Caching の有効化

連続バッチングを aggregate に設定して、minimax-m3-1-flash-acb-prefix-caching (最大 1M のコンテキスト) または minimax-m3-1-flash-32k-acb-prefix-caching (最大 32K のコンテキスト) をデプロイします。構成のデプロイ をご参照ください。 これらのバンドルには、Prompt Caching 用の環境変数や smart_routing.block_hash_size の設定は不要です。MiniMax-M3.1-Flash は、4,096 トークンのページ単位でプロンプトをキャッシュします。再利用されるのは、過去のリクエストと一致するページ全体のみです。

GLM-5.3 での Prompt Caching の有効化

連続バッチングを aggregate に設定して、glm-5-3-acb-prefix-caching バンドルをデプロイします。構成のデプロイ をご参照ください。このバンドルには、Prompt Caching 用の環境変数や smart_routing.block_hash_size の設定は不要です。 v2.3 では、GLM-5.3 は 4,096 トークンのページ単位でプロンプトをキャッシュします (従来の 32,768 トークンから縮小)。再利用されるのは、過去のリクエストと一致するページ全体のみです。お使いのデプロイメントに v2.2.5 時点の設定である KV_CACHE_BLOCK_SIZE: "32768"、KV_CACHE_NUM_DDR_BLOCKS: "64"、block_hash_size: 32768 が残っている場合は、これらを削除してください。32,768 のブロックサイズは v2.3 の PEF と一致しないため、エンジンが起動時に停止します。

gemma-4-31B-it での Prompt Caching の有効化

連続バッチングを aggregate に設定して、次のいずれかのバンドルをデプロイします。構成のデプロイ をご参照ください。
  • gemma-4-31b-acb-prefix-caching: 最大 256K のコンテキスト。
  • gemma-4-31b-acb-prefix-caching-32k: 最大 32K のコンテキスト、同時リクエストは最大 64 件。
これらのバンドルには、Prompt Caching 用の環境変数や smart_routing.block_hash_size の設定は不要です。 gemma-4-31B-it は、2,048 トークンのページ単位でプロンプトをキャッシュします。再利用されるのは、過去のリクエストと一致するページ全体のみです。

レスポンスでのキャッシュ利用状況の確認

キャッシュが有効なモデルからのすべての /v1/chat/completions レスポンスには、usage フィールドにキャッシュトークン数が含まれます。以下は、前のリクエストと同じ長いシステムプロンプトを共有する 2 回目のリクエストの例です。プレフィックスは再処理されず、キャッシュから提供されます。 リクエスト (2 回目の呼び出し: キャッシュ作成済み)
レスポンス
残りの入力 = prompt_tokens − cached_tokens。この部分は標準の入力レートで課金されます。 cached_tokens の値が 0 の場合、そのリクエストでキャッシュヒットが発生しなかったことを意味しますが、エラーではありません。これは、特定のプレフィックスに対する最初のリクエスト (キャッシュ作成中) や、入力がキャッシュ済みのどのエントリともプレフィックスを共有していない場合に発生します。 Prompt Caching に対応していないモデルでは、cached_tokens は常に 0 であり、課金は変わりません。

コード例

請求への影響

キャッシュされたトークンは、標準の入力トークンよりも低いレートで課金されます。キャッシュが有効なリクエストの課金計算は以下のとおりです。 たとえば、入力トークン合計 5,797 のうち 4,096 がキャッシュから提供されたリクエストの場合、1,701 トークンに標準入力レート、4,096 トークンにキャッシュ済み入力レートが適用されます。出力の課金は変わりません。 cache_creation_tokens はレスポンスに表示されますが、情報提供のみを目的としています。このリクエストでキャッシュの作成に使用されたトークンを表し、現時点では追加料金は発生しません。 Prompt Caching のないモデルでは cached_tokens は常に 0 であるため、計算式は標準の計算と同じになり、課金に変更はありません。
MiniMax-M2.7 のキャッシュ済み入力レートを含む最新の料金については、SambaNova の担当者にお問い合わせください。

制限事項

  • Prompt Caching は MiniMax-M2.7 と MiniMax-M3 で利用できるほか、MiniMax-M3.1-Flash と GLM-5.3 では Preview として利用できます。gemma-4-31B-it では、gemma-4-31b-acb-prefix-caching と gemma-4-31b-acb-prefix-caching-32k で利用できます。
  • GLM-5.3 の Prompt Caching バンドルは、テキスト入力のみを受け付けます。MiniMax-M3、MiniMax-M3.1-Flash、gemma-4-31B-it の Prompt Caching バンドルは画像・動画入力も受け付けますが、画像または動画を含むリクエストは、それらが以前のターンに含まれる場合もキャッシュされません。動画は base64 の data: URL として送信してください。
  • Minimax-M2.7 向けに Prompt Caching を有効化したカスタムバンドルには、他のモデルを含めることはできません。
  • キャッシュの状態は各サービングインスタンスに対してローカルです。マルチインスタンスのデプロイメントでは、プレフィックスは各インスタンスで処理された後に、それぞれのインスタンス上で独立してキャッシュされます。
  • APC は共有プレフィックスに対して動作します。キャッシュ境界より前で分岐するリクエストは、キャッシュヒットになりません。
  • MiniMax-M2.7 では、キャッシュ可能なプレフィックス (シーケンスステート) の最大長は 192K トークンです。
  • キャッシュの追い出しには LRU (least recently used) 方式が使用されます。キャッシュの保持期間はシステム負荷によって変動し、保証されません。
  • キャッシュの対象となるには、プレフィックスがキャッシュページの少なくとも 1 ページ分を満たしている必要があります。必要なトークン数は、MiniMax-M2.7、MiniMax-M3、MiniMax-M3.1-Flash、GLM-5.3 では 4,096 トークン、gemma-4-31B-it では 2,048 トークンです。
  • MiniMax-M3、GLM-5.3、gemma-4-31B-it では、1.0 以外の repetition_penalty はサポートされていません。