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

このプロセスはシンプルなパターンに従います。最初のリクエストはキャッシュに書き込みを行い、後続のリクエストはキャッシュから読み取ることができます。キャッシュは5分間保持されるため、この機能は同じコンテンツを繰り返し送信する場合にのみ有用ですが、実際のアプリケーションではこれが非常に頻繁に発生します。
キャッシュブレークポイント
メッセージに対して行われた作業は自動的にキャッシュされるわけではありません。ブロックに手動で「キャッシュブレークポイント」を追加する必要があります。ブレークポイントより前のすべての作業がキャッシュされ、そのキャッシュは、ブレークポイントを含むそれまでのコンテンツが同一である場合にのみ、後続のリクエストで使用されます。

キャッシュブレークポイントを追加する必要がある場合は、省略形ではなく、テキストブロックを記述するための完全形を使用する必要があります。以下がその違いです。
# 省略形 - キャッシュブレークポイントを追加できない
user_message = {
"role": "user",
"content": "Hi there!"
}
# 完全形 - キャッシュブレークポイントに必要
user_message = {
"role": "user",
"content": [
{
"type": "text",
"text": "Hi there!",
"cache_control": {
"type": "ephemeral"
}
}
]
}キャッシュブレークポイントの仕組み
キャッシュブレークポイントは複数のメッセージにまたがり、アシスタントメッセージもキャッシュできます。ブレークポイントを配置すると、その時点までのすべてがキャッシュされます。キャッシュを使用するには、コンテンツが同一である必要があることを忘れないでください。

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

ブレークポイントの配置場所
テキストブロックだけに制限されるわけではありません。システムプロンプトやツール定義にもキャッシュブレークポイントを追加できます。これらはリクエスト間でほとんど変化しないため、実際には最も一般的なキャッシュの機会となります。
# キャッシュ ブレークポイント付きのツール定義
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に渡されます。これは、キャッシュブレークポイントの動作に影響を与えます。

キャッシュブレークポイントは合計で最大4つまで追加できます。最後のツールにブレークポイントを配置すると、そのツールまでのすべてがキャッシュされますが、システムプロンプトとメッセージはキャッシュされません。これにより、アプリケーションで何が変化するかに基づいて、何をキャッシュするかをきめ細かく制御できます。
最小コンテンツ長
キャッシュには最小の長さがあり、それはモデルによって異なります。このコースで使用するモデルであるClaude Haiku 4.5の場合、キャッシュされるにはコンテンツが少なくとも4,096トークンの長さである必要があります。これは、個々のブロックではなく、キャッシュしようとするすべてのメッセージとブロックの合計です。
「やあ!」のようなメッセージはキャッシュするにはあまりにも短すぎますが、本当に長いプロンプトであれば最小値に達します。最小値を下回るコンテンツは、キャッシュされることなく単純に処理され、エラーは返されません。これを確認するには、レスポンスのusageを確認してください。cache_creation_input_tokensとcache_read_input_tokensの両方が0になります。
効果的なプロンプトキャッシュの鍵は、リクエストの中で一貫している部分(通常はシステムプロンプトとツール定義)を特定し、キャッシュヒットを最大化しつつ再処理を最小化するように戦略的にブレークポイントを配置することです。