プロンプトキャッシング

プロンプトキャッシングは、プロンプト内の特定のプレフィックスから再開することで、API使用を最適化する強力な機能です。このアプローチにより、反復的なタスクや一貫した要素を持つプロンプトの処理時間とコストが大幅に削減されます。

Messages APIでcache_controlブロックを使用してプロンプトキャッシングを実装する方法の例を以下に示します。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# キャッシュチェックポイントまで同じ入力でモデルを再度呼び出す
curl https://api.anthropic.com/v1/messages # rest of input

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
      },
      {
        "type": "text",
        "text": "<the entire contents of 'Pride and Prejudice'>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    messages=[{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}],
)
print(response.usage.model_dump_json())

# キャッシュチェックポイントまで同じ入力でモデルを再度呼び出す
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
    },
    {
      type: "text",
      text: "<the entire contents of 'Pride and Prejudice'>",
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [
    {
      role: "user",
      content: "Analyze the major themes in 'Pride and Prejudice'."
    }
  ]
});
console.log(response.usage);

// キャッシュチェックポイントまで同じ入力でモデルを再度呼び出す
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .text("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

この例では、「プライドと偏見」のテキスト全体がcache_controlパラメータを使用してキャッシュされています。これにより、複数のAPI呼び出しでこの大きなテキストを再処理することなく再利用できます。ユーザーメッセージのみを変更することで、キャッシュされたコンテンツを利用しながら本についてさまざまな質問をすることができ、より高速な応答と効率の向上につながります。

プロンプトキャッシングの仕組み

プロンプトキャッシングを有効にしてリクエストを送信すると：

1. システムは、指定されたキャッシュブレークポイントまでのプロンプトプレフィックスが最近のクエリからすでにキャッシュされているかどうかを確認します。
2. 見つかった場合は、キャッシュされたバージョンを使用し、処理時間とコストを削減します。
3. それ以外の場合は、完全なプロンプトを処理し、応答が開始されたらプレフィックスをキャッシュします。

これは特に以下の場合に役立ちます：

• 多くの例を含むプロンプト
• 大量のコンテキストまたは背景情報
• 一貫した指示を持つ反復的なタスク
• 長いマルチターン会話

デフォルトでは、キャッシュの有効期限は5分です。キャッシュされたコンテンツが使用されるたびに、キャッシュは追加コストなしで更新されます。

価格設定

プロンプトキャッシングは新しい価格設定構造を導入しています。以下の表は、サポートされている各モデルのトークンあたりの価格を示しています：

プロンプトキャッシングの実装方法

サポートされているモデル

プロンプトキャッシングは現在以下でサポートされています：

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (非推奨)

プロンプトの構造化

静的コンテンツ（ツール定義、システム指示、コンテキスト、例）をプロンプトの最初に配置します。cache_controlパラメータを使用して、キャッシング用の再利用可能なコンテンツの終了をマークします。

キャッシュプレフィックスは次の順序で作成されます：tools、system、messages。この順序は、各レベルが前のレベルに基づいて構築される階層を形成します。

自動プレフィックスチェックの仕組み

静的コンテンツの終了時に1つのキャッシュブレークポイントを使用でき、システムは自動的に最長の一致するプレフィックスを見つけます。これがどのように機能するかを理解することは、キャッシング戦略を最適化するのに役立ちます。

3つの主要な原則：

1. キャッシュキーは累積的です：cache_controlでブロックを明示的にキャッシュすると、キャッシュハッシュキーは会話内のすべての前のブロックを順序付けてハッシュすることで生成されます。これは、各ブロックのキャッシュがそれより前のすべてのコンテンツに依存することを意味します。

2. 逆順順序チェック：システムは明示的なブレークポイントから逆方向に作業して、前のブロックを逆順でチェックすることで、キャッシュヒットをチェックします。これにより、可能な限り最長のキャッシュヒットが得られます。

3. 20ブロックルックバックウィンドウ：システムは各明示的なcache_controlブレークポイントの前の最大20ブロックのみをチェックします。20ブロックをチェックしても一致がない場合、チェックを停止し、次の明示的なブレークポイント（存在する場合）に移動します。

例：ルックバックウィンドウの理解

30個のコンテンツブロックを持つ会話を考えてみてください。ブロック30にのみcache_controlを設定した場合：

• 前のブロックに変更がなくブロック31を送信する場合：システムはブロック30をチェックします（一致！）。ブロック30でキャッシュヒットが得られ、ブロック31のみが処理される必要があります。

• ブロック25を変更してブロック31を送信する場合：システムはブロック30 → 29 → 28... → 25（一致なし）→ 24（一致！）から逆方向にチェックします。ブロック24は変更されていないため、ブロック24でキャッシュヒットが得られ、ブロック25～30のみが再処理される必要があります。

• ブロック5を変更してブロック31を送信する場合：システムはブロック30 → 29 → 28... → 11（チェック#20）から逆方向にチェックします。20回のチェック後に一致が見つからないため、チェックを停止します。ブロック5は20ブロックウィンドウを超えているため、キャッシュヒットは発生せず、すべてのブロックが再処理される必要があります。ただし、ブロック5に明示的なcache_controlブレークポイントを設定していた場合、システムはそのブレークポイントからチェックを続行します：ブロック5（一致なし）→ ブロック4（一致！）。これにより、ブロック4でキャッシュヒットが可能になり、編集可能なコンテンツの前にブレークポイントを配置する理由が示されます。

重要なポイント：キャッシュヒット率を最大化するために、会話の終了時に明示的なキャッシュブレークポイントを常に設定してください。さらに、編集可能な可能性のあるコンテンツブロックの直前にブレークポイントを設定して、これらのセクションが独立してキャッシュされることを確認してください。

複数のブレークポイントを使用する場合

以下の場合は、最大4つのキャッシュブレークポイントを定義できます：

• 異なる頻度で変更される異なるセクションをキャッシュしたい場合（例：ツールはめったに変更されませんが、コンテキストは毎日更新されます）
• キャッシュされる内容をより細かく制御したい場合
• 最終ブレークポイントの前の20ブロック以上のコンテンツのキャッシングを確保したい場合
• 編集可能なコンテンツの前にブレークポイントを配置して、20ブロックウィンドウを超えた変更が発生した場合でもキャッシュヒットを保証したい場合

キャッシュの制限

最小キャッシュ可能プロンプト長は以下の通りです：

• Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4.5、Claude Sonnet 4、Claude Sonnet 3.7（非推奨）、Claude Opus 3（非推奨）の場合は1024トークン
• Claude Haiku 4.5の場合は4096トークン
• Claude Haiku 3.5およびClaude Haiku 3の場合は2048トークン

より短いプロンプトは、cache_controlでマークされていても、キャッシュできません。このトークン数より少ないトークンをキャッシュするリクエストは、キャッシングなしで処理されます。プロンプトがキャッシュされたかどうかを確認するには、応答使用フィールドを参照してください。

同時リクエストの場合、キャッシュエントリは最初の応答が開始された後にのみ利用可能になることに注意してください。並列リクエストのキャッシュヒットが必要な場合は、最初の応答を待ってから後続のリクエストを送信してください。

現在、「ephemeral」は唯一サポートされているキャッシュタイプであり、デフォルトでは5分の有効期限があります。

キャッシュブレークポイントコストの理解

キャッシュブレークポイント自体はコストを追加しません。 以下の場合にのみ課金されます：

• キャッシュ書き込み：新しいコンテンツがキャッシュに書き込まれる場合（5分TTLの場合、基本入力トークンより25%多い）
• キャッシュ読み取り：キャッシュされたコンテンツが使用される場合（基本入力トークン価格の10%）
• 通常の入力トークン：キャッシュされていないコンテンツの場合

より多くのcache_controlブレークポイントを追加しても、コストは増加しません。実際にキャッシュされて読み取られるコンテンツに基づいて同じ金額を支払います。ブレークポイントは、どのセクションを独立してキャッシュできるかを制御するだけです。

キャッシュできるもの

リクエスト内のほとんどのブロックは、cache_controlでキャッシング用に指定できます。これには以下が含まれます：

• ツール：tools配列内のツール定義
• システムメッセージ：system配列内のコンテンツブロック
• テキストメッセージ：messages.content配列内のコンテンツブロック（ユーターンとアシスタントターンの両方）
• 画像とドキュメント：ユーターンのmessages.content配列内のコンテンツブロック
• ツール使用とツール結果：messages.content配列内のコンテンツブロック（ユーターンとアシスタントターンの両方）

これらの各要素は、cache_controlでマークしてそのリクエスト部分のキャッシングを有効にできます。

キャッシュできないもの

ほとんどのリクエストブロックはキャッシュできますが、いくつかの例外があります：

• 思考ブロックはcache_controlで直接キャッシュできません。ただし、思考ブロックは前のアシスタントターンに表示される場合、他のコンテンツと一緒にキャッシュできます。この方法でキャッシュされる場合、キャッシュから読み取られるときは入力トークンとしてカウントされます。

• サブコンテンツブロック（引用など）自体は直接キャッシュできません。代わりに、トップレベルブロックをキャッシュしてください。

  引用の場合、引用のソース資料として機能するトップレベルドキュメントコンテンツブロックはキャッシュできます。これにより、引用がキャッシュされるドキュメントをキャッシュすることで、プロンプトキャッシングを引用と共に効果的に使用できます。

• 空のテキストブロックはキャッシュできません。

キャッシュを無効にするもの

キャッシュされたコンテンツへの変更は、キャッシュの一部またはすべてを無効にする可能性があります。

プロンプトの構造化で説明されているように、キャッシュは階層に従います：tools → system → messages。各レベルでの変更は、そのレベルとすべての後続レベルを無効にします。

以下の表は、異なるタイプの変更によってキャッシュのどの部分が無効になるかを示しています。✘はキャッシュが無効になることを示し、✓はキャッシュが有効なままであることを示します。

キャッシュパフォーマンスの追跡

これらのAPIレスポンスフィールドを使用してキャッシュパフォーマンスを監視します。レスポンス内のusage内（またはストリーミングの場合はmessage_startイベント）：

• cache_creation_input_tokens：新しいエントリを作成するときにキャッシュに書き込まれたトークン数。
• cache_read_input_tokens：このリクエストのためにキャッシュから取得されたトークン数。
• input_tokens：キャッシュから読み取られたり、キャッシュを作成するために使用されなかった入力トークン数。

効果的なキャッシングのベストプラクティス

プロンプトキャッシングパフォーマンスを最適化するには：

• システム指示、背景情報、大規模なコンテキスト、または頻繁なツール定義などの安定した再利用可能なコンテンツをキャッシュします。
• キャッシュされたコンテンツをプロンプトの最初に配置して、最高のパフォーマンスを実現します。
• キャッシュブレークポイントを戦略的に使用して、異なるキャッシュ可能なプレフィックスセクションを分離します。
• キャッシュヒット率を最大化するために、会話の終了時と編集可能なコンテンツの直前にキャッシュブレークポイントを設定します。特に20個以上のコンテンツブロックを持つプロンプトを操作する場合に重要です。
• キャッシュヒット率を定期的に分析し、必要に応じて戦略を調整します。

異なるユースケースに対する最適化

シナリオに合わせてプロンプトキャッシング戦略をカスタマイズします：

• 会話エージェント：長い指示またはアップロードされたドキュメントを含む拡張会話のコストと遅延を削減します。
• コーディングアシスタント：関連するセクションまたはコードベースの要約版をプロンプトに保持することで、オートコンプリートとコードベースQ&Aを改善します。
• 大規模ドキュメント処理：画像を含む完全な長編資料をプロンプトに組み込み、応答遅延を増加させません。
• 詳細な指示セット：広範な指示、手順、例のリストを共有して、Claudeの応答を微調整します。開発者はプロンプトに1～2つの例を含めることが多いですが、プロンプトキャッシングを使用すると、高品質な回答の20以上の多様な例を含めることでさらに優れたパフォーマンスを得られます。
• エージェンティックツール使用：複数のツール呼び出しと反復的なコード変更を含むシナリオのパフォーマンスを向上させます。各ステップは通常、新しいAPI呼び出しが必要です。
• 本、論文、ドキュメント、ポッドキャストトランスクリプト、その他の長編コンテンツと対話する：プロンプトにドキュメント全体を埋め込み、ユーザーに質問させることで、任意のナレッジベースを活性化させます。

一般的な問題のトラブルシューティング

予期しない動作が発生している場合：

• キャッシュされたセクションが同一であり、呼び出し全体で同じ場所にcache_controlでマークされていることを確認します
• 呼び出しがキャッシュ有効期限内（デフォルトでは5分）に行われていることを確認します
• tool_choiceと画像の使用が呼び出し間で一貫していることを確認します
• 最小トークン数をキャッシュしていることを確認します
• システムは自動的に前のコンテンツブロック境界でキャッシュヒットをチェックします（ブレークポイントの前の約20ブロック）。20個以上のコンテンツブロックを持つプロンプトの場合、すべてのコンテンツをキャッシュできるようにするために、プロンプトの前の方に追加のcache_controlパラメータが必要な場合があります
• tool_useコンテンツブロック内のキーが安定した順序を持つことを確認します。一部の言語（例：Swift、Go）はJSON変換中にキー順序をランダム化し、キャッシュを破壊します

思考ブロックを使用したキャッシング

拡張思考をプロンプトキャッシングと共に使用する場合、思考ブロックには特別な動作があります：

他のコンテンツと一緒に自動キャッシング：思考ブロックはcache_controlで明示的にマークできませんが、ツール結果を含む後続のAPI呼び出しを行うときにリクエストコンテンツの一部としてキャッシュされます。これは通常、思考ブロックを会話を続行するために戻すツール使用中に発生します。

入力トークンカウント：思考ブロックがキャッシュから読み取られる場合、使用メトリクスで入力トークンとしてカウントされます。これはコスト計算とトークン予算に重要です。

キャッシュ無効化パターン：

• ツール結果のみがユーザーメッセージとして提供される場合、キャッシュは有効なままです
• 非ツール結果ユーザーコンテンツが追加される場合、キャッシュが無効になり、すべての前の思考ブロックが削除されます
• このキャッシング動作は、明示的なcache_controlマーカーがなくても発生します

キャッシュ無効化の詳細については、キャッシュを無効にするものを参照してください。

ツール使用の例：

リクエスト1：ユーザー：「パリの天気は？」
応答：[thinking_block_1] + [tool_use block 1]

リクエスト2：
ユーザー：[「パリの天気は？」]、
アシスタント：[thinking_block_1] + [tool_use block 1]、
ユーザー：[tool_result_1、cache=True]
応答：[thinking_block_2] + [text block 2]
# リクエスト2はそのリクエストコンテンツをキャッシュします（応答ではなく）
# キャッシュには以下が含まれます：ユーザーメッセージ、thinking_block_1、tool_use block 1、tool_result_1

リクエスト3：
ユーザー：[「パリの天気は？」]、
アシスタント：[thinking_block_1] + [tool_use block 1]、
ユーザー：[tool_result_1、cache=True]、
アシスタント：[thinking_block_2] + [text block 2]、
ユーザー：[テキスト応答、cache=True]
# 非ツール結果ユーザーブロックは新しいアシスタントループを指定します
# このリクエストは思考ブロックが存在しなかったかのように処理されます

非ツール結果ユーザーブロックが含まれる場合、新しいアシスタントループが指定され、すべての前の思考ブロックはコンテキストから削除されます。

詳細については、拡張思考ドキュメントを参照してください。

キャッシュストレージと共有

• 組織の分離：キャッシュは組織間で分離されます。異なる組織は、同一のプロンプトを使用していても、キャッシュを共有することはありません。

• 完全一致：キャッシュヒットには、キャッシュコントロールでマークされたブロックまでを含む、すべてのテキストと画像を含む100%同一のプロンプトセグメントが必要です。

• 出力トークン生成：プロンプトキャッシングは出力トークン生成に影響しません。受け取る応答は、プロンプトキャッシングが使用されていない場合に得られるものと同一です。

1時間キャッシュ期間

5分が短すぎる場合、Anthropicは追加コストで1時間のキャッシュ期間も提供しています。

拡張キャッシュを使用するには、cache_control定義にttlを含めます：

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

レスポンスには、以下のような詳細なキャッシュ情報が含まれます：

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

現在のcache_creation_input_tokensフィールドはcache_creationオブジェクト内の値の合計に等しいことに注意してください。

1時間キャッシュを使用する場合

定期的なペースで使用されるプロンプト（つまり、5分ごとに1回以上の頻度で使用されるシステムプロンプト）がある場合は、5分キャッシュを引き続き使用してください。これは追加料金なしで継続的に更新されるためです。

1時間キャッシュは以下のシナリオで最適に使用されます：

• 5分より少ない頻度で使用されるが、1時間より多い頻度で使用される可能性があるプロンプトがある場合。例えば、エージェンティックサイドエージェントが5分以上かかる場合、またはユーザーとの長いチャット会話を保存し、一般的にそのユーザーが次の5分以内に応答しないと予想される場合。
• レイテンシが重要で、フォローアッププロンプトが5分を超えて送信される可能性がある場合。
• レート制限の利用を改善したい場合。キャッシュヒットはレート制限に対して差し引かれません。

異なるTTLの混合

同じリクエストで1時間キャッシュと5分キャッシュコントロールの両方を使用できますが、重要な制約があります：より長いTTLを持つキャッシュエントリは、より短いTTLの前に表示される必要があります（つまり、1時間キャッシュエントリは5分キャッシュエントリの前に表示される必要があります）。

TTLを混合する場合、プロンプト内の3つの請求位置を決定します：

1. 位置A：最高のキャッシュヒットでのトークンカウント（ヒットがない場合は0）。
2. 位置B：Aの後の最高の1時間cache_controlブロックでのトークンカウント（存在しない場合はAに等しい）。
3. 位置C：最後のcache_controlブロックでのトークンカウント。

以下の場合に課金されます：

1. 位置Aのキャッシュ読み取りトークン。
2. 位置(B - A)の1時間キャッシュ書き込みトークン。
3. 位置(C - B)の5分キャッシュ書き込みトークン。

以下は3つの例です。これは3つのリクエストの入力トークンを示し、それぞれが異なるキャッシュヒットとキャッシュミスを持っています。各結果の計算された価格は、色付きボックスに示されています。

プロンプトキャッシングの例

プロンプトキャッシングを開始するのに役立つように、詳細な例とベストプラクティスを含むプロンプトキャッシングクックブックを準備しました。

以下に、さまざまなプロンプトキャッシングパターンを紹介するいくつかのコードスニペットを含めました。これらの例は、異なるシナリオでキャッシングを実装する方法を示し、この機能の実用的なアプリケーションを理解するのに役立ちます：

FAQ