プロンプトキャッシング — TokSpan ドキュメント

仕組み

同じプロンプトプレフィックスを複数のAPI呼び出しにわたって送信すると、上流プロバイダーが重複を認識し、再処理をスキップして、キャッシュされた部分に対して 割引料金 を課金します。典型的な節約効果：

指標	キャッシュなし	キャッシュヒット時
最初のトークンまでの時間	基準	最大80%高速化
プロンプトトークンコスト	通常料金	50～90%安価

キャッシングはサポートされているすべてのモデルで デフォルトで有効 です — 設定は不要です。キャッシュのライフサイクルはプロバイダーが自動管理します（キャッシュは通常5～30分間持続し、プロバイダーと負荷によって異なります）。

キャッシュに適したプロンプト設計

キャッシュは プレフィックス（メッセージ配列の先頭からのトークン）にマッチします。静的な要素をすべて先頭に配置するようにプロンプトを設計してください：

python
# ✅ GOOD: Static content first = high cache hit rate
messages = [
    {"role": "system", "content": "You are a legal assistant. Reference case law when answering..."},
    {"role": "user", "content": "What are the elements of negligence?"},
]

# ❌ BAD: Dynamic prefix kills cache
messages = [
    {"role": "user", "content": "What are the elements of negligence?"},  # Cache miss
    {"role": "system", "content": "You are a legal assistant..."},  # Too late
]

設計チェックリスト

システムメッセージを最初に — 常に messages の最初の要素として配置してください
動的クエリの前に静的なコンテキストを — 少数ショット例、取得したRAGコンテキスト、ツール定義はユーザーの現在の質問より前に配置します
プレフィックスにタイムスタンプ/IDを含めない — キャッシュ可能なコンテンツの前にリクエスト固有のデータを付加しないでください
システムプロンプトを同一に保つ — キャッシュヒットにはプレフィックス全体がバイト単位で一致する必要があります
プレフィックスが長いほど節約効果が大きい — 10Kトークンのシステムプロンプトをキャッシュすると、200トークンのものよりはるかに大きな節約になります

キャッシュヒットの監視

レスポンスの usage オブジェクトで、プロンプトがキャッシュにヒットしたかどうかがわかります：

Claude (Anthropic): cache_read_input_tokens と cache_creation_input_tokens を確認してください
GPT-4o (OpenAI): キャッシュされたトークンは prompt_tokens の低い課金額に反映されます
Gemini (Google): コンテキストキャッシングは使用量メタデータに表示されます

import requests

response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-your-key"},
    json={"model": "claude-opus-4-8", "messages": [...]},
)

# Check for cache hits in the usage object
usage = response.json()["usage"]
if "cache_read_input_tokens" in usage:
    print(f"Cache hit! {usage['cache_read_input_tokens']} tokens served from cache")
    print(f"Cache creation: {usage.get('cache_creation_input_tokens', 0)} tokens written")
else:
    print("Cache miss — all prompt tokens billed at full price")

サポートモデル

モデル	プロバイダー	最小キャッシュ可能トークン数	キャッシュTTL（標準）
Claude Opus 4.8	Anthropic	1024	~5 min
Claude Sonnet 4.6	Anthropic	1024	~5 min
GPT-4o	OpenAI	1024	~5–10 min
Gemini 2.5 Pro	Google	32768	設定可能（コンテキストキャッシュAPI）

最小トークン閾値: 各プロバイダーは最小トークン数（ClaudeとGPT-4oでは通常1024トークン）を超えるプロンプトのみをキャッシュします。短いプロンプトは対象外です。そのため、大規模なシステムプロンプト、RAGパイプライン、長い履歴を持つマルチターン会話を使用するアプリケーションでキャッシングの効果が最も大きくなります。

Prompt Caching

仕組み

キャッシュに適したプロンプト設計

設計チェックリスト

キャッシュヒットの監視

サポートモデル