Prompt caching (プロンプトキャッシュ)

繰り返し行う作業や、共通の要素を含むプロンプトについて、処理時間とコストを大幅に減らします。ツール定義やシステムの指示など、毎回同じ内容を送るアプリケーションに関わる機能です。

キャッシュの有効期間は、既定で 5 分です。キャッシュの照合では、ブレークポイントごとに 20 ブロックをさかのぼって確認します (lookback window)。

キャッシュがヒットするには、cache_control を付けたブロックまでのテキストと画像を含め、プロンプトの該当部分が 100% 同一である必要があります。

Prompt caching は出力トークンの生成には影響しません。受け取る応答は、Prompt caching を使わない場合と同じです。また、異なる組織同士がキャッシュを共有することはありません。同一のプロンプトを使っていても同じです。

キャッシュの効果は、応答の usage 内 (ストリーミングの場合は message_start イベント) にある cache_creation_input_tokens、cache_read_input_tokens、input_tokens の各フィールドで確認できます。

次の要素は、自動で、または cache_control を付けることでキャッシュできます。

• ツール (tools)
• システムメッセージ
• テキストメッセージ
• 画像と文書
• ツールの使用 (tool use) とツールの結果 (tool results)

Thinking ブロックは、cache_control で直接キャッシュすることはできません。ただし、過去のアシスタントのターンに含まれる場合は、他のコンテンツと一緒にキャッシュされます。

自動キャッシュを使う場合は、個々のコンテンツブロックに cache_control を置く代わりに、リクエスト本文の最上位に cache_control フィールドを 1 つ追加します。システムが最後のキャッシュ可能なブロックにブレークポイントを置き、会話が伸びるにつれて前へ移動させます。

明示的なブレークポイントでは、個々のコンテンツブロックに cache_control を直接置き、キャッシュする範囲を細かく指定します。ブレークポイントは最大 4 個まで定義できます。

自動キャッシュは明示的なブレークポイントと併用できます。併用した場合、自動のブレークポイントは利用できる 4 個の枠のうち 1 個を使います。

既定の 5 分より長い 1 時間のキャッシュを使う場合は、cache_control の定義に ttl を含めます。

事前ウォームは、実際のリクエストの前にシステムプロンプトやツール定義をキャッシュに読み込んでおく使い方です。流れは次のとおりです。

1. リクエストで max_tokens: 0 を指定します。API はプロンプトを読み込み、cache_control のブレークポイントでキャッシュを書き込み、出力を生成せずにすぐ応答を返します。
2. cache_control のブレークポイントは、仮置きのユーザーメッセージではなく、後続のリクエストと共通する最後のブロック (通常はシステムプロンプトやツール定義) に置きます。
3. アプリケーションの起動時 (または定期的な間隔) に事前ウォームのリクエストを送り、それが完了した後に実際のユーザーのリクエストを送ります。

1. プロンプトの先頭に、変わらない内容 (ツール定義、システムの指示、コンテキスト、例) を置きます。
2. 再利用する内容の終わりを、cache_control パラメータで示します。