Prompt Caching ガイド - SambaNova ドキュメント

Prompt Caching (プロンプトキャッシング) は、繰り返し使用されるプロンプトのプレフィックス (先頭部分) に対する計算結果をキャッシュすることで、処理時間を削減します。キャッシュされるのはプロンプトのテキストそのものではなく、その処理に要した計算結果です。複数のリクエストがシステムプロンプトやドキュメントのような同じ冒頭テキストを共有している場合、SambaNova はそれらのトークンを一から再処理する代わりに、キャッシュされた結果を返します。最初の数リクエストで提供ノード上にキャッシュが構築され、同じプレフィックスが繰り返し観測されるにつれて削減効果が高まります。継続的なトラフィックでは、プレフィックスが数回観測された後、ヒット率は通常 90% 以上に達します。

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

Prompt Caching を使用すべき場面

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

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

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

仕組み

自動プレフィックスキャッシング (APC) は、MiniMax-M2.7 と MiniMax-M3 では常に有効です。リクエスト間で共有されるプレフィックスを検出し、キャッシュされた計算結果を透過的に再利用します。API の変更は不要です。キャッシュヒットを最大化するには、メッセージの先頭部分をリクエスト間で安定した一貫性のある内容に保ってください。プレフィックスは、messages 配列の先頭トークンシーケンスがキャッシュ済みのリクエストと同一である場合に一致と判定されます。システムプロンプトの言い換え、その前へのメッセージの挿入、コンテンツの並べ替えなど、プレフィックスへの何らかの変更があると、新しいキャッシュエントリが開始されます。システムプロンプトを同一に保ったままユーザーメッセージだけを変更した場合は、キャッシュ済みのプレフィックスが再利用されます。キャッシュの状態は、各提供インスタンスに対してローカルです。複数インスタンスのデプロイメントでは、プレフィックスは各インスタンスで提供された後に、それぞれのインスタンス上で独立してキャッシュされます。

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

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

{
  "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 料金ページで確認できます。

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 トークンはより低いキャッシュ済みレートで請求されます。出力の請求は変わりません。

サンプルコード

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

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?")

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?")

制限事項

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

はじめに

モデル

機能一覧

活用ガイド

リソース

Prompt Caching によるレイテンシと費用の削減

Prompt Caching を使用すべき場面

仕組み

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

請求

サンプルコード

制限事項

​Prompt Caching を使用すべき場面

​仕組み

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

​請求

​サンプルコード

​制限事項

Prompt Caching を使用すべき場面

仕組み

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

請求

サンプルコード

制限事項