読み込み中

プロンプトキャッシュのルール

レッスン 477 分
読み込み中

Claudeにおけるプロンプトキャッシュは、メッセージに対して行われた計算処理を保存し、後続のリクエストで再利用できるようにする仕組みです。これにより、キャッシュされたコンテンツを使用するリクエストは、より安価かつ高速に実行できるようになります。

Claudeは、プロンプト「これを要約してください」に対して行った作業をキャッシュに書き込み、その後、後続のリクエストでそれを読み取ります。

このプロセスはシンプルなパターンに従います。最初のリクエストはキャッシュに書き込みを行い、後続のリクエストはキャッシュから読み取ることができます。キャッシュは5分間保持されるため、この機能は同じコンテンツを繰り返し送信する場合にのみ有用ですが、実際のアプリケーションではこれが非常に頻繁に発生します。

キャッシュブレークポイント

メッセージに対して行われた作業は自動的にキャッシュされるわけではありません。ブロックに手動で「キャッシュブレークポイント」を追加する必要があります。ブレークポイントより前のすべての作業がキャッシュされ、そのキャッシュは、ブレークポイントを含むそれまでのコンテンツが同一である場合にのみ、後続のリクエストで使用されます。

長いプロンプトを保持するユーザーメッセージのテキストブロック。その「cache_control」タイプ「ephemeral」がキャッシュブレークポイントとラベル付けされています。

キャッシュブレークポイントを追加する必要がある場合は、省略形ではなく、テキストブロックを記述するための完全形を使用する必要があります。以下がその違いです。

python
# 省略形 - キャッシュブレークポイントを追加できない
user_message = {
  "role": "user",
  "content": "Hi there!"
}

# 完全形 - キャッシュブレークポイントに必要
user_message = {
  "role": "user", 
  "content": [
    {
      "type": "text",
      "text": "Hi there!",
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

キャッシュブレークポイントの仕組み

キャッシュブレークポイントは複数のメッセージにまたがり、アシスタントメッセージもキャッシュできます。ブレークポイントを配置すると、その時点までのすべてがキャッシュされます。キャッシュを使用するには、コンテンツが同一である必要があることを忘れないでください。

4つのテキストブロックそれぞれに対してClaudeが行った作業。最初のブロックの後に点線のブレークポイントラインがあり、キャッシュボックスは空です。

後続のリクエストでは、Claudeは以前に処理された作業を再処理する代わりに、キャッシュから読み取ります。

Claudeは、後続のリクエストの3つのブロックに対してキャッシュされた作業を読み取ります。最後のブロック「要約の焦点を」にブレークポイントがあります。

ブレークポイントの配置場所

テキストブロックだけに制限されるわけではありません。システムプロンプトやツール定義にもキャッシュブレークポイントを追加できます。これらはリクエスト間でほとんど変化しないため、実際には最も一般的なキャッシュの機会となります。

python
# キャッシュ ブレークポイント付きのツール定義
tools = [
  add_duration_to_datetime_schema,
  get_current_datetime_schema,
  {
    "name": "set_reminder",
    "description": "Sets a reminder...",
    "input_schema": { ... },
    "cache_control": {"type": "ephemeral"}
  }
]

# キャッシュ ブレークポイント付きのシステムプロンプト  
system = [
  {
    "type": "text",
    "text": "You are a senior software...",
    "cache_control": {"type": "ephemeral"}
  }
]

キャッシュの順序

内部的には、ツール、システムプロンプト、メッセージがその特定の順序で結合され、Claudeに渡されます。これは、キャッシュブレークポイントの動作に影響を与えます。

どちらのリクエストでも、キャッシュブレークポイントはシステムプロンプトとメッセージの前にあるTool 3に設定されています。リクエスト2ではアシスタントメッセージが変更されています。

キャッシュブレークポイントは合計で最大4つまで追加できます。最後のツールにブレークポイントを配置すると、そのツールまでのすべてがキャッシュされますが、システムプロンプトとメッセージはキャッシュされません。これにより、アプリケーションで何が変化するかに基づいて、何をキャッシュするかをきめ細かく制御できます。

最小コンテンツ長

キャッシュには最小の長さがあり、それはモデルによって異なります。このコースで使用するモデルであるClaude Haiku 4.5の場合、キャッシュされるにはコンテンツが少なくとも4,096トークンの長さである必要があります。これは、個々のブロックではなく、キャッシュしようとするすべてのメッセージとブロックの合計です。

「やあ!」のようなメッセージはキャッシュするにはあまりにも短すぎますが、本当に長いプロンプトであれば最小値に達します。最小値を下回るコンテンツは、キャッシュされることなく単純に処理され、エラーは返されません。これを確認するには、レスポンスのusageを確認してください。cache_creation_input_tokensとcache_read_input_tokensの両方が0になります。

効果的なプロンプトキャッシュの鍵は、リクエストの中で一貫している部分(通常はシステムプロンプトとツール定義)を特定し、キャッシュヒットを最大化しつつ再処理を最小化するように戦略的にブレークポイントを配置することです。