Claude APIのコストをキャッシュで削減する設定手順

Claude APIを使ったシステムで、長いシステムプロンプトや参考文書を毎リクエスト送ると、トークンコストが想像以上に積み上がります。Anthropicが提供するプロンプトキャッシュ機能を正しく設定すれば、繰り返し送信するトークンのコストを大幅に削減できます。この記事では、公式ドキュメントをベースに cache_control パラメータの設定手順と、効果を引き出すためのパターンをコードつきで解説します。

プロンプトキャッシュのしくみ

プロンプトキャッシュは、指定したプロンプト部分をAnthropicのサーバー側に一時保存し、次のリクエストで同じ内容を再処理しなくて済む仕組みです。

公式ドキュメント（執筆時点）によるコスト構造は次のとおりです。

キャッシュ読み出しは通常の10%なので、同じプロンプトを繰り返し送るほどコストが下がります。ただし書き込み時は25%増しになるため、1回しか使わない場合はむしろ割高です。

制約事項（公式ドキュメントより）

• キャッシュ可能な最小トークン数：Claude 3系以降は 1,024トークン
• キャッシュの有効期間：デフォルト5分（執筆時点）
• キャッシュはプレフィックスマッチ方式：プロンプトの先頭から一致する部分だけがヒットする

キャッシュが効くシナリオ

キャッシュが費用対効果を発揮するのは、同じ長いコンテキストを5分以内に複数回送るケースです。

効果が高い使い方：

• 固定の長いシステムプロンプト（役割定義・出力ルール・例示集）
• RAGで参考文書をプロンプトに含めて繰り返す場合
• 同一会話内での会話履歴の再送（マルチターン）
• バッチ処理で同じ指示文を大量リクエストに使う場合

逆に効果が薄いケース：

• ユーザー入力が毎回大きく変わり、固定部分が少ない
• プロンプト全体が1,024トークン未満
• リクエスト間隔が常に5分を超える（TTL切れで毎回書き込みになる）

cache_control の設定手順

1. システムプロンプトをキャッシュする

cache_control パラメータを、キャッシュしたいブロックの末尾に付けます。

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",  # 利用するモデルIDに合わせて変更してください
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": """
あなたは商品説明文のライターです。
以下のルールを必ず守ってください。
（ここに長い指示文が続く — 1,024トークン以上必要）
""",
            "cache_control": {"type": "ephemeral"}  # ← キャッシュ指定
        }
    ],
    messages=[
        {"role": "user", "content": "商品名：レザーブリーフケース の説明文を書いてください"}
    ]
)

# キャッシュの使用状況を確認
usage = response.usage
print(f"キャッシュ書き込み: {usage.cache_creation_input_tokens}")
print(f"キャッシュ読み出し: {usage.cache_read_input_tokens}")
print(f"通常入力: {usage.input_tokens}")

cache_control に指定できる type は、執筆時点では "ephemeral" のみです（公式ドキュメント）。cache_creation_input_tokens が0のままであれば、キャッシュが有効になっていないサインです。

2. ツール定義をキャッシュする

多数のツール定義を持つエージェントでは、ツール定義リスト自体をキャッシュできます。cache_control はリスト末尾の要素に付けます。

response = client.messages.create(
    model="claude-sonnet-4-6",  # 利用するモデルIDに合わせて変更してください
    max_tokens=1024,
    tools=[
        {
            "name": "search_products",
            "description": "商品データベースを検索する",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"}
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_inventory",
            "description": "在庫数を確認する",
            "input_schema": {
                "type": "object",
                "properties": {
                    "product_id": {"type": "string"}
                }
            },
            "cache_control": {"type": "ephemeral"}  # ← 末尾のツールに付ける
        }
    ],
    messages=[{"role": "user", "content": "在庫を確認してください"}]
)

cache_control は「先頭からここまでをキャッシュする」という意味です。途中の要素に付けた場合、そこまでの内容がキャッシュ対象になります。

3. プロンプトの順序設計

キャッシュはプレフィックスマッチです。変化しない部分を先頭に、変化する部分を末尾に置くことがヒット率を上げる基本です。

ユーザーの質問を先頭に置くと、毎回プレフィックスが変わってキャッシュが全くヒットしません。プロンプトエンジニアリングの実務コツ｜出力が安定する設計パターンでも触れているように、固定の指示とユーザー入力を分離した構造にしておくと、キャッシュ設計も自然と整います。

コストの試算

3,000トークンのシステムプロンプトを1,000回送るケースを例にします。Claude 3.5 Sonnetの執筆時点の公式価格（$3.00/MTok）を使用しています。価格は変動するため、最新値はAnthropic公式の料金ページで確認してください。

キャッシュなし：
- 3,000トークン × 1,000回 = 3,000,000トークン
- 費用：$3.00/MTok × 3 = $9.00

キャッシュあり（初回書き込み＋999回ヒット）：
- 書き込み：3,000トークン × $3.75/MTok = $0.011
- 読み出し：3,000トークン × 999回 × $0.30/MTok = $0.899
- 合計：約$0.91

この条件では約90%のコスト削減になります。ただしこれはキャッシュが5分以内に使い切られる理想的なケースです。リクエスト頻度が低い場合は、ヒット率が下がり削減幅も小さくなります。

注意点とよくある失敗

キャッシュが切れてコストが増える

デフォルトのTTLは5分（執筆時点）です。リクエストが5分以上空くとキャッシュが消え、次のリクエストで書き込みが再発生します。低頻度なバッチ処理より、継続的にリクエストを送るサービス向きです。夜間バッチなど間隔が空くケースでは、恩恵が得にくい可能性があります。

1,024トークン未満はキャッシュされない

短いシステムプロンプトに cache_control を付けてもエラーにはならず、静かに無視されます（公式ドキュメント）。cache_creation_input_tokens が0のままなら効いていません。システムプロンプトが短い場合は、具体的な出力例や参考情報を追加してトークン数を増やすか、キャッシュ対象を変える必要があります。

レスポンスはキャッシュされない

プロンプトキャッシュはあくまで入力（プロンプト）側の最適化です。出力トークンは毎回生成されるため、出力が長いケースでは出力コスト自体は変わりません。

モデルによって最小トークン数が異なる可能性がある

使用するモデルの公式ドキュメントで、キャッシュの最小トークン要件を確認してください。環境によって動作が異なる場合があります。

まとめ

Claude APIのプロンプトキャッシュは、cache_control: {"type": "ephemeral"} を対象ブロックの末尾に追加するだけで有効になります。効果が出る条件は「1,024トークン以上の固定コンテキストがある」「5分以内にリクエストが連続する」の2つです。

次のアクション： まずレスポンスの usage.cache_creation_input_tokens と usage.cache_read_input_tokens をログに出力して、現在のシステムプロンプトがキャッシュされているか確認してみてください。書き込みが発生しているのに読み出しが0であれば、リクエスト間隔かプロンプトの順序を見直すヒントになります。