SambaStack Prompt Caching - SambaNova ドキュメント

Prompt Caching (プロンプトキャッシング) は、繰り返し使用されるプロンプトのプレフィックス (接頭部分) に対する計算結果をキャッシュすることで、処理時間を節約する機能です。キャッシュされるのはプロンプトのテキストそのものではなく、それを処理するために行われた計算です。複数のリクエストが同じ冒頭テキスト (システムプロンプトやドキュメントなど) を共有する場合、SambaNova はそれらのトークンを最初から再処理する代わりに、キャッシュされた結果を利用します。最初の数リクエストでサービングノード上にキャッシュが作成され、同じプレフィックスが繰り返し観測されるにつれて節約効果が積み上がります。継続的なトラフィックでは、プレフィックスが数回観測された後、ヒット率は通常 90% 以上に達します。 Prompt Caching は、SambaStack の v2.0.2 リリース以降、MiniMax-M2.7 向けの安定版 (一般提供) 機能です。 v2.2.3 では、minimax-m3-acb-prefix-caching バンドルを対象として、MiniMax-M3 でも Preview (プレビュー) 機能として Prompt Caching を利用できます。このバンドルはテキスト入力のみを受け付けます。

本ページでは、Prompt Caching の使い方と usage フィールドの読み方を説明します。モデルの提供状況については、対応モデルとバンドルをご覧ください。

Prompt Caching を使用すべきケース

Prompt Caching は、入力の大部分がリクエスト間で繰り返される場合に、最も大きな節約効果を発揮します。

適しているケース	適していないケース
すべてのユーザーターンで共有される長いシステムプロンプト	リクエストごとに完全に異なる入力 (共有プレフィックスなし)
繰り返し使用される few-shot 例やツール定義	キャッシュのオーバーヘッドが節約効果を上回るごく短いプロンプト
クエリごとに再送信される RAG コンテキスト	プレフィックスが繰り返されない単発利用のドキュメント
固定の前置き部分を持つマルチターン会話

cached_tokens がリクエストをまたいで 0 のままの場合、入力がキャッシュ可能なプレフィックスを共有していません。システムプロンプトやコンテキストブロックが呼び出し間で安定しているかどうかを見直してください。

Prompt Caching の仕組み

Automatic Prefix Caching (APC: 自動プレフィックスキャッシング) は MiniMax-M2.7 で利用できますが、SambaStack 管理者が次の手順で有効化する必要があります。

プロンプトキャッシング用バンドル——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 を直接デプロイします。

ModelDeployment リソースに次の環境変数を設定します。

engineConfig:
  env_vars:
    ENABLE_KV_CACHE_MANAGER: "true"
    KV_CACHE_INCLUDE_STATS_IN_RESPONSE: "true"

プロファイル名 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 です。

MiniMax-M3 での Prompt Caching の有効化

連続バッチングを aggregate に設定して、minimax-m3-acb-prefix-caching バンドルをデプロイします。構成のデプロイをご参照ください。

ModelDeployment リソースに次の環境変数を設定します。

engineConfig:
  env_vars:
    ENABLE_KV_CACHE_MANAGER: "true"
    KV_CACHE_NUM_DDR_BLOCKS: "1536"
    KV_CACHE_INCLUDE_STATS_IN_RESPONSE: "true"

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

キャッシュが有効なモデルからのすべての /v1/chat/completions レスポンスには、usage フィールドにキャッシュトークン数が含まれます。以下は、前のリクエストと同じ長いシステムプロンプトを共有する 2 回目のリクエストの例です。プレフィックスは再処理されず、キャッシュから提供されます。 リクエスト (2 回目の呼び出し: キャッシュ作成済み)

# A long, repeated system prompt (1,000+ tokens) triggers APC on the second call.
curl https://<sambastack-host>/v1/chat/completions \
  -H "Authorization: Bearer $SAMBANOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M2.7",
    "messages": [
      {
        "role": "system",
        "content": "You are a technical assistant for SambaNova hardware. ..."
      },
      {
        "role": "user",
        "content": "What is the default batch size for MiniMax-M2.7?"
      }
    ],
    "max_tokens": 100
  }'

レスポンス

{
  "id": "cmpl-3ca55e7f-8fd5-470d-bac6-ee38a7a5307b",
  "object": "chat.completion",
  "created": 1779835973,
  "model": "MiniMax-M2.7",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The default batch size for MiniMax-M2.7 is 2."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5797,
    "completion_tokens": 100,
    "total_tokens": 5897,
    "prompt_tokens_details": {
      "cache_creation_tokens": 0,
      "cached_tokens": 4096
    }
  }
}

フィールド	説明
`cached_tokens`	キャッシュから提供された入力トークン。キャッシュ済み入力レートで課金されます。
`cache_creation_tokens`	このリクエストでキャッシュの作成に使用された入力トークン。情報提供のみを目的とし、追加料金はありません。

残りの入力 = prompt_tokens − cached_tokens。この部分は標準の入力レートで課金されます。 cached_tokens の値が 0 の場合、そのリクエストでキャッシュヒットが発生しなかったことを意味しますが、エラーではありません。これは、特定のプレフィックスに対する最初のリクエスト (キャッシュ作成中) や、入力がキャッシュ済みのどのエントリともプレフィックスを共有していない場合に発生します。 Prompt Caching に対応していないモデルでは、cached_tokens は常に 0 であり、課金は変わりません。

コード例

from sambanova import SambaNova

client = SambaNova(
    base_url="https://<sambastack-host>",
    api_key="your-sambanova-api-key",
)

system_prompt = """You are a technical assistant for SambaNova hardware. You have access to
the following reference documentation:

[Insert your long, stable system prompt or document here – the longer and more stable this
prefix, the more tokens are eligible for caching. A prefix must be at least 4,096 tokens
to qualify.]"""

def ask(question):
    response = client.chat.completions.create(
        model="MiniMax-M2.7",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": question},
        ],
    )
    usage = response.usage
    cached = usage.prompt_tokens_details.cached_tokens
    total_prompt = usage.prompt_tokens
    print(f"Cached tokens: {cached} / {total_prompt} prompt tokens")
    print(response.choices[0].message.content)

# First request – populates the cache
ask("What is the default batch size for MiniMax-M2.7?")

# Second request – same prefix, served from cache
ask("What is the maximum sequence length for MiniMax-M2.7?")

from openai import OpenAI

client = OpenAI(
    base_url="https://<sambastack-host>/v1",
    api_key="your-sambanova-api-key",
)

system_prompt = """You are a technical assistant for SambaNova hardware. You have access to
the following reference documentation:

[Insert your long, stable system prompt or document here – the longer and more stable this
prefix, the more tokens are eligible for caching. A prefix must be at least 4,096 tokens
to qualify.]"""

def ask(question):
    response = client.chat.completions.create(
        model="MiniMax-M2.7",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": question},
        ],
    )
    usage = response.usage
    cached = usage.prompt_tokens_details.cached_tokens
    total_prompt = usage.prompt_tokens
    print(f"Cached tokens: {cached} / {total_prompt} prompt tokens")
    print(response.choices[0].message.content)

# First request – populates the cache
ask("What is the default batch size for MiniMax-M2.7?")

# Second request – same prefix, served from cache
ask("What is the maximum sequence length for MiniMax-M2.7?")

請求への影響

キャッシュされたトークンは、標準の入力トークンよりも低いレートで課金されます。キャッシュが有効なリクエストの課金計算は以下のとおりです。

トークン種別	課金
残りの入力 (`prompt_tokens` − `cached_tokens`)	標準入力レート
`cached_tokens`	キャッシュ済み入力レート (割安)
`completion_tokens`	標準出力レート (変更なし)

たとえば、入力トークン合計 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 でも Preview として利用できます (テキスト入力のみ)。
Minimax-M2.7 向けに Prompt Caching を有効化したカスタムバンドルには、他のモデルを含めることはできません。
キャッシュの状態は各サービングインスタンスに対してローカルです。マルチインスタンスのデプロイメントでは、プレフィックスは各インスタンスで処理された後に、それぞれのインスタンス上で独立してキャッシュされます。
APC は共有プレフィックスに対して動作します。キャッシュ境界より前で分岐するリクエストは、キャッシュヒットになりません。
MiniMax-M2.7 では、キャッシュ可能なプレフィックス (シーケンスステート) の最大長は 192K トークンです。
キャッシュの追い出しには LRU (least recently used) 方式が使用されます。キャッシュの保持期間はシステム負荷によって変動し、保証されません。
キャッシュの対象となるには、プレフィックスに 4,096 トークン以上が含まれている必要があります。
MiniMax-M3 では、1.0 以外の repetition_penalty はサポートされていません。

Get started

Models

Features

Build

Resources

Prompt Caching の利用

Prompt Caching を使用すべきケース

Prompt Caching の仕組み

MiniMax-M3 での Prompt Caching の有効化

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

コード例

請求への影響

制限事項

​Prompt Caching を使用すべきケース

​Prompt Caching の仕組み

​MiniMax-M3 での Prompt Caching の有効化

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

​コード例

​請求への影響

​制限事項

Prompt Caching を使用すべきケース

Prompt Caching の仕組み

MiniMax-M3 での Prompt Caching の有効化

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

コード例

請求への影響

制限事項