プロンプトキャッシュ
固定プレフィックスを通常の入力料金の一部で再読み込みする方法：キャッシュするもの、しないもの、機能したかを確認する方法。
プロンプトキャッシュはリクエストのプレフィックスを保存し、同じプレフィックスを共有する後続の呼び出しに、低い入力料金を適用します。システムプロンプト、ツールスキーマ、質問の対象となる文書など、長く安定した前置きがある場合、最も費用対効果の高い変更です。
キャッシュ対象に適したもの
| 適しているもの | 理由 |
|---|---|
| システムプロンプト | セッション内のすべての呼び出しでバイト単位で同一 |
| ツール／関数の定義 | エージェントの実行全体で変わらず、サイズも大きいことが多い |
| 繰り返し質問される文書 | 一度のアップロードで多くの質問に対応 |
| Few-shotの例 | 固定されており、長いことが多い |
| 適していないもの | 理由 |
|---|---|
| ユーザーの最新メッセージ | 毎回異なるため、キャッシュヒットしない |
| 先頭付近にタイムスタンプやリクエストIDがあるもの | プレフィックスの前方でひとつのバイトが変わると、それ以降のすべてが無効になる |
| 短いプロンプト | キャッシュ可能な最小長に満たないため、効果がない |
プレフィックスをマークする
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [{
"type": "text",
"text": "<long stable instructions...>",
"cache_control": {"type": "ephemeral"}
}],
"messages": [{"role": "user", "content": "Question that changes every call"}]
}マークしたブロックまでのすべての内容が、そのブロックも含めてキャッシュされるプレフィックスになります。順序が重要です。変わらない内容を先に、変わりやすい内容を後に配置してください。
動作を確認する
次の項目を確認してください： usage オブジェクト。キャッシュヒット時のトークン数は、通常の入力ではなくキャッシュ読み取りとして報告されます。呼び出しを繰り返してもキャッシュ読み取りがゼロのままであれば、プレフィックスは実際には同一ではありません。よくある原因は、前置きに含まれるタイムスタンプ、セッションID、またはJSONのキー順序が非決定的であることです。
キャッシュする内容は、常に同じ結果になるようにシリアライズしてください。
json.dumps(obj) なしで sort_keys=True は実行ごとにキーの順序を変えることがあり、その結果バイト列が変わり、気づかないうちにキャッシュヒットがすべて失われます。特に効果が大きい場面
エージェント型ツールは、ターンごとに同じシステムプロンプトと同じツールスキーマを再送信します。50ターンのセッションでは、この前置き部分の料金はキャッシュがなければ50回分、キャッシュがあればおおむね一度分だけ発生します。