> ## 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% 以上に達します。

<Note>
  Prompt Caching は、SambaCloud の **MiniMax-M2.7** と **MiniMax-M3** で利用できます。自動プレフィックスキャッシング (Automatic Prefix Caching; APC) はデフォルトで有効であり、リクエストの変更は不要です。
</Note>

## Prompt Caching を使用すべき場面

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

| 適したケース | 適さないケース |
| :- | :- |
| すべてのユーザーターンで共有される長いシステムプロンプト | リクエストごとに完全に固有の入力 (共有プレフィックスなし) |
| 繰り返し使用される Few-shot の例やツール定義 | 削減効果がごくわずかな、非常に短いプロンプト |
| クエリごとに再送信される RAG コンテキスト | プレフィックスが二度と繰り返されない、使い捨てのドキュメント |
| 固定の前置きを持つマルチターン会話 | |

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

## 仕組み

自動プレフィックスキャッシング (APC) は、MiniMax-M2.7 と MiniMax-M3 では常に有効です。リクエスト間で共有されるプレフィックスを検出し、キャッシュされた計算結果を透過的に再利用します。API の変更は不要です。キャッシュヒットを最大化するには、メッセージの先頭部分をリクエスト間で安定した一貫性のある内容に保ってください。

プレフィックスは、messages 配列の先頭トークンシーケンスがキャッシュ済みのリクエストと同一である場合に一致と判定されます。システムプロンプトの言い換え、その前へのメッセージの挿入、コンテンツの並べ替えなど、プレフィックスへの何らかの変更があると、新しいキャッシュエントリが開始されます。システムプロンプトを同一に保ったままユーザーメッセージだけを変更した場合は、キャッシュ済みのプレフィックスが再利用されます。

キャッシュの状態は、各提供インスタンスに対してローカルです。複数インスタンスのデプロイメントでは、プレフィックスは各インスタンスで提供された後に、それぞれのインスタンス上で独立してキャッシュされます。

## レスポンスからのキャッシュ使用状況の確認

すべてのレスポンスには、キャッシュから提供されたトークン数を示す `prompt_tokens_details` オブジェクトが含まれます。

```json theme={}
{
  "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` | このリクエストでキャッシュに書き込まれたトークン。情報提供のみであり、追加料金は発生しません。 |

`cache_creation_tokens` は、キャッシュエントリを構築する最初のリクエストでは 0 以外の値になり、以降のキャッシュヒット時には `0` になります。キャッシュされていない入力トークン数は `prompt_tokens - cached_tokens` です。

## 請求

キャッシュされたトークンは、標準の入力トークンよりも低いレートで請求されます。キャッシュ済み入力レートとキャッシュ書き込みレートを含む、お使いのモデルの全料金は、`/v1/models` エンドポイントおよび [SambaCloud 料金ページ](https://cloud.sambanova.ai/pricing) で確認できます。

```bash theme={}
curl https://cloud.sambanova.ai/v1/models \
  -H "Authorization: Bearer $SAMBANOVA_API_KEY" \
  | jq '.data[] | select(.id == "MiniMax-M2.7") | .pricing'
```

キャッシュが有効なリクエストの請求計算式は以下のとおりです。

```
cost = (prompt_tokens − cached_tokens) × standard_input_rate
     + cached_tokens × cached_input_rate
     + completion_tokens × output_rate
```

たとえば、入力トークンの合計が 5797 で、そのうち 4096 がキャッシュから提供されたリクエストでは、標準入力レートで請求されるのは 1701 トークンのみであり、4096 トークンはより低いキャッシュ済みレートで請求されます。出力の請求は変わりません。

## サンプルコード

<Note>
  キャッシングは、共有プレフィックスが 4096 トークンに達した場合にのみ有効になります。以下のシステムプロンプトは読みやすさのために短くしています。実際にキャッシュヒットを観測するには、実際のドキュメントに置き換えてください。
</Note>

<CodeGroup>
  ```python Python (SambaNova) theme={}
  from sambanova import SambaNova

  client = SambaNova(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key",
  )

  system_prompt = """You are a financial analyst assistant. You have access to the following
  quarterly earnings report:

  Fiscal Q3 2024 Earnings Report – Your Company

  Revenue: Total revenue for Q3 2024 was $4.2 billion, up 12% year-over-year. Product revenue
  was $3.1 billion (+9% YoY) and services revenue was $1.1 billion (+21% YoY).

  Gross Margin: GAAP gross margin was 68.4%, up from 65.2% in Q3 2023. Non-GAAP gross margin
  was 71.1%.

  Operating Income: GAAP operating income was $820 million (19.5% margin). Non-GAAP operating
  income was $1.05 billion (25.0% margin).

  Net Income: GAAP net income was $710 million, or $1.42 per diluted share. Non-GAAP net income
  was $910 million, or $1.82 per diluted share.

  Cash: Cash, cash equivalents, and short-term investments totaled $12.3 billion at quarter end.
  Free cash flow was $980 million.

  Outlook: Q4 2024 revenue guidance is $4.4–$4.6 billion.

  Replace this content with your actual document. The longer and more stable your system prompt,
  the more tokens are eligible for caching."""

  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 was the revenue in Q3?")

  # Second request – same prefix, served from cache
  ask("What was the gross margin in Q3?")
  ```

  ```python Python (OpenAI) theme={}
  from openai import OpenAI

  client = OpenAI(
      base_url="your-sambanova-base-url",
      api_key="your-sambanova-api-key",
  )

  system_prompt = """You are a financial analyst assistant. You have access to the following
  quarterly earnings report:

  Fiscal Q3 2024 Earnings Report – Your Company

  Revenue: Total revenue for Q3 2024 was $4.2 billion, up 12% year-over-year. Product revenue
  was $3.1 billion (+9% YoY) and services revenue was $1.1 billion (+21% YoY).

  Gross Margin: GAAP gross margin was 68.4%, up from 65.2% in Q3 2023. Non-GAAP gross margin
  was 71.1%.

  Operating Income: GAAP operating income was $820 million (19.5% margin). Non-GAAP operating
  income was $1.05 billion (25.0% margin).

  Net Income: GAAP net income was $710 million, or $1.42 per diluted share. Non-GAAP net income
  was $910 million, or $1.82 per diluted share.

  Cash: Cash, cash equivalents, and short-term investments totaled $12.3 billion at quarter end.
  Free cash flow was $980 million.

  Outlook: Q4 2024 revenue guidance is $4.4–$4.6 billion.

  Replace this content with your actual document. The longer and more stable your system prompt,
  the more tokens are eligible for caching."""

  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 was the revenue in Q3?")

  # Second request – same prefix, served from cache
  ask("What was the gross margin in Q3?")
  ```
</CodeGroup>

## 制限事項

* Prompt Caching は **MiniMax-M2.7** と **MiniMax-M3** のみで利用できます。他のモデルでは、`usage` オブジェクトにキャッシュ済みトークンのフィールド自体が含まれません。
* キャッシュの状態は単一ノードに対してローカルであり、ノード間で共有されません。
* キャッシュ可能なプレフィックスの最大長: **192000 トークン**。
* キャッシングの対象となるには、プレフィックスに最低 **4096 トークン** が含まれている必要があります。
* キャッシュの削除 (eviction) には **LRU (least recently used)** ポリシーが使用されます。キャッシュの保持はシステム負荷によって変動し、保証されません。