Claude API Prompt Cacheが効かないときの確認ポイント — 最小1024トークン要件と設計パターン

はじめに

Claude API の Prompt Cache は、API 呼び出しコストを最大 90% 削減できる強力な機能です。しかし最小 1024 トークン以上という要件を満たさないと、キャッシュが機能しません。

特にシステムプロンプト単体ではキャッシュされないという点を見落としがちです。その落とし穴と解決方法を解説します。

Prompt Cache の仕組み

Prompt Cache は、API リクエストの先頭から連続した部分（system や初期 messages）を 5 分間キャッシュします。同じ内容で 2 回目以降のリクエストが来れば、キャッシュからヒットして:

• 入力トークンの単価が 90% 削減
• 処理速度も高速化

なぜ 1024 トークン要件があるのか

キャッシュシステム自体のオーバーヘッドがあるため、小さすぎるブロックはコスト効率が悪くなります。そのため 1024 トークン以上という最小要件が設定されました。

❌ よくある実装ミス

import anthropic

client = anthropic.AsyncAnthropic()

# ❌ NG: システムプロンプトだけをキャッシュしようとする
response = await client.messages.create(
    model="claude-sonnet-4-20250514",
    system=[{
        "type": "text",
        "text": "あなたは介護施設のアシスタントです。",  # 約200トークン → キャッシュされない！
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": query}],
    max_tokens=1024,
)

このコードではシステムプロンプトが 200 トークン程度で、最小要件の 1024 トークンに達しないため、キャッシュは機能しません。

✅ 正しい実装パターン

パターン1：システムプロンプト + RAG コンテキストを統合

import anthropic

client = anthropic.AsyncAnthropic()

# システムプロンプト
SYSTEM_PROMPT = """あなたは介護施設のスタッフを支援するAIアシスタントです。
介護マニュアルの内容に基づいて、現場スタッフの質問に正確に答えてください。
- 回答は音声読み上げ専用です。マークダウン記号は使用しないでください
- 手順がある場合はすべてのステップを含めて完全に回答してください
- 接続詞として「まず」「次に」「それから」「最後に」を使ってください
"""

# RAG で取得したコンテキスト（約1800トークン）
rag_context = "【参照マニュアル】\n" + "\n".join(retrieved_chunks)

# ✅ OK: 合計2000トークン以上 → キャッシュが有効になる
response = await client.messages.create(
    model="claude-sonnet-4-20250514",
    system=[{
        "type": "text",
        "text": SYSTEM_PROMPT + "\n\n" + rag_context,
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": query}],
    max_tokens=1024,
)

このパターンではシステムプロンプト（200 トークン）+ RAG コンテキスト（1800 トークン）= 合計 2000 トークン以上となり、キャッシュが有効です。

キャッシュが効いているか確認する

# レスポンスから usage 情報を取得
usage = response.usage

# キャッシュが効いているかチェック
if usage.cache_read_input_tokens > 0:
    print("✅ キャッシュヒット: 入力トークン単価90%削減")
    print(f"   キャッシュ読み込み: {usage.cache_read_input_tokens} トークン")
elif usage.cache_creation_input_tokens > 0:
    print("🆕 キャッシュ作成: 次回から削減される")
    print(f"   キャッシュ作成: {usage.cache_creation_input_tokens} トークン")
else:
    print("❌ キャッシュなし: 1024トークン要件を確認")

print(f"入力トークン: {usage.input_tokens}")

• 初回呼び出し → cache_creation_input_tokens がゼロ以上
• 2回目以降（同じプロンプト） → cache_read_input_tokens がゼロ以上

実装時の注意点

1. キャッシュ対象ブロックは入力の先頭 — システムプロンプトは必ず先頭に配置
2. ephemeral キャッシュの有効期限は 5 分 — claude-sonnet-4 の場合
3. RAG コンテキストが毎回変わると効率低下 — 検索結果が異なる度にキャッシュ作成
4. 複数ユーザー環境ではキャッシュが共有されない — ユーザー毎の API キーで分離

環境

• Python 3.10+
• anthropic 0.40+（AsyncAnthropic 使用推奨）
• Claude Sonnet 4.0 以降

参考資料

• Anthropic - Prompt Caching

---

1024 トークンは一見高そうに見えますが、RAG コンテキストと組み合わせれば簡単にクリアできます。Prompt Cache で大幅なコスト削減を実現しましょう！