プロンプトキャッシュは、同じコンテンツをClaudeに繰り返し送信する場合に、APIリクエストを高速化しつつコストを削減できる強力な最適化機能です。アプリケーションでこれを効果的に実装する方法を見ていきましょう。
プロンプトキャッシュの仕組み
プロンプトキャッシュを有効にすると、最初のリクエストでコンテンツがキャッシュに書き込まれ、デフォルトで5分間のライフタイムが設定されます。キャッシュされたコンテンツが使用されるたびに、このウィンドウは追加コストなしでリフレッシュされます。より長いウィンドウが必要な場合は、追加コストで1時間のキャッシュ期間を選択できます。後続のリクエストは、同じコンテンツを再処理する代わりに、このキャッシュから読み込みます。これは、次のようなものを送信する場合に特に有用です。
- 大きなシステムプロンプト(6Kトークンのコーディングアシスタント用プロンプトなど)
- 複雑なツールスキーマ(複数のツールの詳細な定義など)
- 繰り返されるメッセージコンテンツ
重要なポイントは、キャッシュが役立つのは同一のコンテンツを繰り返し送信している場合だけだということです。ただし、多くのアプリケーションではこれが非常に頻繁に発生します。
ツールスキーマのキャッシュ設定
ツールスキーマをキャッシュするには、ツールリストの最後のツールにキャッシュ制御フィールドを追加する必要があります。元のツール定義を変更せずに正しく行う方法は次のとおりです。
if tools:
tools_clone = tools.copy()
last_tool = tools_clone[-1].copy()
last_tool["cache_control"] = {"type": "ephemeral"}
tools_clone[-1] = last_tool
params["tools"] = tools_cloneこのアプローチでは、キャッシュ制御フィールドを追加する前に、ツールリストと最後のツールスキーマの両方のコピーを作成します。tools[-1]["cache_control"]を直接変更することもできますが、コピーを作成するアプローチにより、後でツールを並べ替えた場合の問題を防ぐことができます。
システムプロンプトのキャッシュ
システムプロンプトについては、キャッシュ制御を伴うテキストブロックとして構造化する必要があります。
if system:
params["system"] = [
{
"type": "text",
"text": system,
"cache_control": {"type": "ephemeral"}
}
]これにより、システムプロンプトが単純な文字列から、キャッシュをサポートする構造化フォーマットに変換されます。
キャッシュの動作を理解する
キャッシュを有効にしてリクエストを実行すると、レスポンスに異なる使用状況のパターンが表示されます。
- 最初のリクエスト:
cache_creation_input_tokensには書き込まれたトークン数が表示される — Claudeがキャッシュに書き込む - 後続のリクエスト:
cache_read_input_tokensには読み戻された同じトークン数が表示される — Claudeがキャッシュから読み込む - 変更されたコンテンツ: 新しいキャッシュ作成トークンが表示される
キャッシュは非常に敏感で、ツールやシステムプロンプト内の1文字でも変更すると、そのコンポーネントのキャッシュ全体が無効になります。
キャッシュの順序とブレークポイント
1つのリクエストに複数のキャッシュブレークポイントを設定できます。順序が重要です。
- ツール(提供されている場合)
- システムプロンプト(提供されている場合)
- メッセージ
システムプロンプトを変更してもツールを同じに保てば、(ツールに関する)部分的なキャッシュ読み込みと、(新しいシステムプロンプトに関する)キャッシュ書き込みが発生します。この部分的な読み込みが得られるのは、ツールだけで最小長に達する場合のみです。なぜなら、その時点までのコンテンツが最小長に満たないキャッシュブレークポイントは何も書き込まないからです。このきめ細かなキャッシュにより、実際に変更された部分の処理にのみコストが発生します。
実用上の考慮事項
プロンプトキャッシュは、以下のような場合に最も効果的です。
- リクエスト間で一貫したツールスキーマ
- 安定したシステムプロンプト
- 類似したコンテキストで複数のリクエストを行うアプリケーション
デフォルトのキャッシュは5分間持続し(使用のたびにリフレッシュされます)、追加コストで1時間のオプションも利用できることを覚えておいてください。そのため、長期的な保存ではなく、比較的頻繁にAPIを使用するアプリケーション向けに設計されています。