Anthropic Claudeのプロンプトキャッシュ入門

はじめに

この記事では、Anthropic Claudeのプロンプトキャッシュについてまとめました。

Anthropoc Caludeとは

Anthropic Claudeは、Anthropic社が開発した高度なAI言語モデルです。
このモデルは、自然言語処理タスクにおいて高い性能を発揮し、特に会話型AIやテキスト生成、分析などの用途に適しています。

Anthropic Claudeは、AWSやGoogle Cloudなどのクラウドプラットフォームを通じて利用可能であり、さまざまな業界で活用されています。

Anthropic公式サイト

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

プロンプトキャッシングを導入すると、指定したプロンプトをキャッシュすることができます。

キャッシュするとキャッシュブレークポイント(cache_control)が設定されているプロンプトのプレフィックス(先頭部分)が、キャッシュされているかを確認します。

キャッシュされている場合、プレフィックス部分のプロンプトを再利用することで、LLM側での内部処理が不要になり、処理時間とコストを削減することができます。
キャッシュされていない場合は、プロンプト全体を新規に処理した後に、プロンプトのプレフィックスを保存します。
この仕組みにより、繰り返し使用されるプロンプトの再処理を避け、システム全体の効率を向上させています。

OpenAIにも同様にプロンプトキャッシュが導入されています。
GoogleのGeminiシリーズにもコンテキストキャッシュという名称は異なりますが、同様の機能があります。

プロンプトキャッシュの料金

料金

キャッシュの料金は以下の通りです。

キャッシュ書き込み: 入力トークンよりも25%高価格
キャッシュ読み取り: 入力トークンよりも90%低価格

初回に発生するキャッシュの書き込みでは、料金が上がってしまいますが、複数回LLMとの会話が行われると、キャッシュが活用されるので、その分料金が安くなります。

サポートモデル

プロンプトキャッシュをサポートしているモデルは以下になります。

Claude 3.7 Sonnet（claude-3-7-sonnet@20250219）
Claude 3.5 Sonnet v2（claude-3-5-sonnet-v2@20241022）
Claude 3.5 Sonnet（claude-3-5-sonnet@20240620）
Claude 3.5 Haiku（claude-3-5-haiku@20241022）
Claude 3 Haiku（claude-3-haiku@20240307）
Claude 3 Opus（claude-3-opus@20240229）

プロンプトキャッシュの利用方法

プロンプトキャッシュを利用するにはClaudeのAPIをコールする際にcache_controlパラメータを指定します。

cache_controlのtypeで指定できるタイプは現状はephemeraのみなので、実質固定値

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-3-7-sonnet-20250219",
    "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."
      }
    ]
  }'

プロンプトキャッシュが設定されたいリクエストを送信すると、初回はキャッシュにプロンプトを書き込み、2回目にリクエストしたときに、プロンプトキャッシュ内にキャッシュがあるかどうかを判定し、キャッシュがヒットした場合は、キャッシュされたプロンプトを再利用します。これにより、処理時間を短縮し、コストを削減することができます。

プロンプトキャッシュを有効にした場合、APIレスポンス内の以下のフィールドにキャッシュ書き込みしたトークン数とキャッシュ読み取りしたトークン数が表示されます。
（ストリーミング時は message_start イベント内）

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

{"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でマークされていてもキャッシュされません。

Claude 3.7 Sonnet、Claude 3.5 SonnetおよびClaude 3 Opusでは1024トークン
Claude 3.5 HaikuおよびClaude 3 Haikuでは2048トークン

設定可能なキャッシュブレークポイント

cache_controlが設定されているメッセージの位置をキャッシュブレークポイントといいます。
Claudeではメッセージの開始からキャッシュブレークポイントが設定されているところまでをキャッシュします。
1リクエストで設定可能なキャッシュブレークポイント(cache_control)の数は最大4つまです。

messages=[
    {
        "role": "user",
        "content": "1. こんにちは",
    },
    {
        "role": "assistant",
        "content": "2. こんにちは",
    },
    {
        "role": "user",
        "content": "3. 今日の天気はなんですか？",
        "cache_control": {"type": "ephemeral"} # ここより上にあるものがキャッシュ判定されるので、1～3までをキャッシュ
    }
]

キャッシュの有効期間

キャッシュの有効期間(TTL)は最低5分間です。
ただし、キャッシュの有効期間は、キャッシュされたプロンプトが使用されると、更新され、期間を延長することができます。

キャッシュ可能な要素

ツール: tools配列内で定義したツール要素ブロック
システムメッセージ: system配列内のコンテンツブロック
メッセージ: messages.content配列内のコンテンツブロック（ユーザーの入力とアシスタントの出力の両方）
画像とドキュメント: ユーザーが入力したmessages.content配列内のコンテンツブロック
ツールの使用とツールの結果: messages.content配列内のコンテンツブロック（ユーザーの入力とアシスタントの出力の両方）

キャッシュの共有

キャッシュは組織間で共有されておらず、分離されています。
そのため、同一のプロンプトであっても、他の組織が使用しているプロンプトキャッシュを使用することはできません。

完全一致

キャッシュヒットには、cache controlでマークされたブロックまでのすべてのテキストと画像を含むプロンプトセグメントが100%同一である必要があります。
同じブロックがキャッシュの読み取りと作成時にcache controlでマークされている必要があります。

プロンプトキャッシュのユースケース

1回当たりの入力トークン数が多いプロンプトを処理する必要があるケース
ユーザーとLLMの会話がマルチターン(複数回行われる)のケース

おわりに

この記事では、プロンプトキャッシュについて紹介しました。
プロンプトキャッシュを活用することで、処理時間と料金を削減することができるので、有効活用しましょう。