> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Caching の利用

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 を利用できます。このバンドルはテキスト入力のみを受け付けます。

<Info>
  本ページでは、Prompt Caching の使い方と usage フィールドの読み方を説明します。モデルの提供状況については、[対応モデルとバンドル](/docs/ja/sambastack/service-administration/model-deployment/supported-models-and-bundles) をご覧ください。
</Info>

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

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

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

`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` リソースに次の環境変数を設定します。

   ```yaml theme={}
   engineConfig:
     env_vars:
       ENABLE_KV_CACHE_MANAGER: "true"
       KV_CACHE_INCLUDE_STATS_IN_RESPONSE: "true"
   ```

<Note>
  プロファイル名 `minimax-m2p5-dyt-pc-cd` は、MiniMax-M2.5 と MiniMax-M2.7 が共有する PEF を指しています。そのため、MiniMax-M2.7 をサービングする場合でも `m2p5` というセグメントが含まれるのは想定どおりです。
</Note>

有効化されると、APC はリクエスト間で共有されるプレフィックスを検出し、キャッシュされた計算結果を透過的に再利用します。API リクエストの変更は必要ありません。

Prompt Caching は OpenAI 標準に準拠しています。キャッシュヒットは自動的に検出され、レスポンスの `usage` フィールドで報告されます。`cache_control` マーカーやその他のリクエストボディの変更は不要です。

APC は各サービングインスタンスに対してローカルに動作します。キャッシュされた KV ステートはローカルの DDR に保存され、インスタンス間で転送されません。マルチインスタンスのデプロイメントでは、プレフィックスは各インスタンスで処理された後に、それぞれのインスタンス上で独立してキャッシュされます。MiniMax-M2.7 のシーケンスステートプールのサイズは 192K です。

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

1. 連続バッチングを `aggregate` に設定して、`minimax-m3-acb-prefix-caching` バンドルをデプロイします。[構成のデプロイ](/docs/ja/sambastack/service-administration/model-deployment/deploying-models-and-bundles/deployment-configurations#構成のデプロイ) をご参照ください。
2. `ModelDeployment` リソースに次の環境変数を設定します。

   ```yaml theme={}
   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 回目の呼び出し: キャッシュ作成済み)**

```bash theme={}
# 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
  }'
```

**レスポンス**

```json theme={}
{
  "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` であり、課金は変わりません。

## コード例

<CodeGroup>
  ```python Python (SambaNova) theme={}
  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?")
  ```

  ```python Python (OpenAI) theme={}
  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?")
  ```
</CodeGroup>

## 請求への影響

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

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

たとえば、入力トークン合計 5,797 のうち 4,096 がキャッシュから提供されたリクエストの場合、1,701 トークンに標準入力レート、4,096 トークンにキャッシュ済み入力レートが適用されます。出力の課金は変わりません。

`cache_creation_tokens` はレスポンスに表示されますが、情報提供のみを目的としています。このリクエストでキャッシュの作成に使用されたトークンを表し、現時点では追加料金は発生しません。

Prompt Caching のないモデルでは `cached_tokens` は常に `0` であるため、計算式は標準の計算と同じになり、課金に変更はありません。

<Note>
  MiniMax-M2.7 のキャッシュ済み入力レートを含む最新の料金については、SambaNova の担当者にお問い合わせください。
</Note>

## 制限事項

* 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` はサポートされていません。