プロンプトキャッシュ

同じ長い前提を繰り返し送る場合、プロンプトキャッシュを利用すると、対応するモデルが入力の共通部分を再利用できます。キャッシュの方式と指定できるフィールドはモデルごとに異なります。

キャッシュする内容を決める

キャッシュの対象には、複数のリクエストで変わらない長い接頭辞を置きます。システムメッセージ、共通の資料、固定したツール定義を先に置き、リクエストごとに変わる質問を末尾に置きます。

入力の順序や内容が変わると共通部分として扱われない場合があります。短い入力や毎回内容が変わる入力では、キャッシュの作成分だけが増え、再利用されないことがあります。

明示的なキャッシュ

明示的なキャッシュに対応するモデルでは、キャッシュしたい範囲の末尾へ cache_control を付けます。次の例では、共通のシステムメッセージをキャッシュ対象にします。

JSON


{
  "model": "<GET /v1/modelsが返したモデルID>",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "複数のリクエストで共有する長い前提...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "user",
      "content": "この前提に基づいて説明してください。"
    }
  ]
}

モデルがTTLの選択に対応している場合は、cache_control に ttl を加えられます。現在、選択できる値は 5m と 1h です。

暗黙的なキャッシュ

暗黙的なキャッシュに対応するモデルでは、モデル側が入力の共通部分を判定します。対応するGPTモデルでは、同じ前提を使うリクエストの prompt_cache_key に同じ文字列を指定できます。 Nova系のモデルではキャッシュ用のフィールドを指定せず、安定した接頭辞を送ります。

モデルを切り替える場合

auto またはフォールバックを使うリクエストでは、実行される可能性があるすべてのモデルが、指定したキャッシュ方式に対応している必要があります。対応していないモデルを候補に含めると、モデルへ送る前に 400 が返ります。

まずモデルを明示したリクエストでキャッシュ設定を確認し、その後で同じ方式に対応するモデルだけを自動選択やフォールバックの候補にしてください。

使用状況を確認する

使用状況では、通常入力、キャッシュ読み取り、キャッシュ作成のトークン数を分けて確認できます。キャッシュの有無だけで請求額を見積もらず、実際に応答したモデルと各トークン数を確認してください。

APIごとに cache_control を置ける位置と、利用できないフィールドはプロンプトキャッシュのAPI仕様に記載しています。