prompt-caching

プロンプトキャッシュスキル

Anthropic のプロンプトキャッシュを活用して、繰り返し使用するプロンプトのレイテンシとコストを大幅に削減します。

このスキルを使用する場面

• 大量の静的ドキュメントを扱う RAG システム
• 長い指示を含む複数ターンの会話
• 大規模なコードベースのコンテキストを使ったコード分析
• 共通のプレフィックスを使ったバッチ処理
• ドキュメントの分析と要約

主な概念

キャッシュ制御の配置

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are a helpful assistant with access to a large knowledge base...",
            "cache_control": {"type": "ephemeral"}  # Cache this content
        }
    ],
    messages=[{"role": "user", "content": "What is...?"}]
)

キャッシュ階層

キャッシュのブレークポイントは、次の順序で確認されます。

1. ツール - ツール定義が最初にキャッシュされます
2. システム - システムプロンプトが次にキャッシュされます
3. メッセージ - 会話履歴が最後にキャッシュされます

TTL のオプション

TTL	書き込みコスト	読み取りコスト	用途
5 分（デフォルト）	基本料金の 1.25 倍	基本料金の 0.1 倍	対話型セッション
1 時間	基本料金の 2.0 倍	基本料金の 0.1 倍	バッチ処理、安定したドキュメント

キャッシュの要件

• 最小トークン数： 1024～4096（モデルによって異なります）
• 最大ブレークポイント数： リクエストあたり 4
• 対応モデル： 現行のすべてのモデル（Fable 5、Opus 4.8、Sonnet 5、Haiku 4.5）

実装パターン

パターン 1：単一のブレークポイント（推奨）

# Best for: Document analysis, Q&A with static context
system = [
    {
        "type": "text",
        "text": large_document_content,
        "cache_control": {"type": "ephemeral"}  # Single breakpoint at end
    }
]

パターン 2：複数ターンの会話

# Cache grows with conversation
messages = [
    {"role": "user", "content": "First question"},
    {"role": "assistant", "content": "First answer"},
    {
        "role": "user",
        "content": "Follow-up question",
        "cache_control": {"type": "ephemeral"}  # Cache entire conversation
    }
]

パターン 3：複数のブレークポイントを使った RAG

system = [
    {
        "type": "text",
        "text": "Tool definitions and instructions",
        "cache_control": {"type": "ephemeral"}  # Breakpoint 1: Tools
    },
    {
        "type": "text",
        "text": retrieved_documents,
        "cache_control": {"type": "ephemeral"}  # Breakpoint 2: Documents
    }
]

パターン 4：1 時間の TTL を使ったバッチ処理

# Warm the cache before batch
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    system=[{
        "type": "text",
        "text": shared_context,
        "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }],
    messages=[{"role": "user", "content": "Initialize cache"}]
)

# Now run batch - all requests hit the cache
for item in batch_items:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        system=[{
            "type": "text",
            "text": shared_context,
            "cache_control": {"type": "ephemeral", "ttl": "1h"}
        }],
        messages=[{"role": "user", "content": item}]
    )

パフォーマンスの監視

キャッシュ使用状況の確認

response = client.messages.create(...)

# Monitor these fields
cache_write = response.usage.cache_creation_input_tokens  # New cache written
cache_read = response.usage.cache_read_input_tokens       # Cache hit!
uncached = response.usage.input_tokens                    # After breakpoint

print(f"Cache hit rate: {cache_read / (cache_read + cache_write + uncached) * 100:.1f}%")

コストの計算

def calculate_cost(usage, model="claude-sonnet-5"):
    # Example rates (check current pricing)
    base_input_rate = 0.003  # per 1K tokens

    write_cost = (usage.cache_creation_input_tokens / 1000) * base_input_rate * 1.25
    read_cost = (usage.cache_read_input_tokens / 1000) * base_input_rate * 0.1
    uncached_cost = (usage.input_tokens / 1000) * base_input_rate

    return write_cost + read_cost + uncached_cost

キャッシュの無効化

キャッシュを無効にする変更：

変更	影響
ツール定義	キャッシュ全体が無効になります
システムプロンプト	システムとメッセージのキャッシュが無効になります
ブレークポイントより前のコンテンツ	そのブレークポイント以降のキャッシュが無効になります

ベストプラクティス

推奨事項：

• 静的コンテンツの末尾にブレークポイントを配置します
• リクエスト間でツールと指示を一定に保ちます
• バッチ処理には 1 時間の TTL を使用します
• cache_read_input_tokens を監視して節約効果を確認します

非推奨事項：

• 動的コンテンツの途中にブレークポイントを配置しないでください
• ツール定義を頻繁に変更しないでください
• 1024 未満のトークン数でキャッシュが機能することを期待しないでください
• 20 ブロックのルックバック制限を無視しないでください

拡張思考との統合

# Cache + Extended Thinking
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    system=[{
        "type": "text",
        "text": large_context,
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "Analyze this..."}]
)

関連項目

• [[llm-integration]] - Claude API の基本
• [[extended-thinking]] - 深い推論
• [[batch-processing]] - 一括処理