プロンプトキャッシュ

リクエストを変更しても、既存のキャッシュエントリが破棄されるとは限りません。重要なのは、後続のリクエストが同じプレフィックスを持ち、検索対象のブレークポイントで一致するものが見つかるかどうかです。主に次の設定を確認してください。

GPT-5.6 以降では、デフォルトの有効期間である 30 分の場合、キャッシュ書き込みの単価は通常の未キャッシュ入力トークン単価の 1.25 倍です。Responses API では、最小有効期間を 12 時間に設定でき、書き込み単価は通常の入力単価の 2.5 倍になります。その後の読み取り単価は、選択した有効期間にかかわらず、これらのモデルの多くで通常の入力単価の 0.1 倍、GPT-6.1 Sol と GPT-6.1 Terra では 0.05 倍です。

読み取り単価が 0.1 倍で書き込みの有効期間が 30 分の場合、プレフィックスを 1 回書き込み、その全体を 1 回再利用すると、合計コストは通常の入力 1 回分の 1.35 倍です。キャッシュを使わずに 2 回処理すると 2 倍になります。同じ単価で 10 回リクエストした場合、書き込み 1 回と全体の読み取り 9 回の合計は 2.15 倍で、キャッシュを使わなければ 10 倍です。

暗黙的キャッシュと明示的キャッシュの両方を利用できます。明示的キャッシュでは、コンテキストのどの部分をキャッシュに書き込むかをより細かく制御できます。

明示モード：コンテキストの管理方法に応じて、キャッシュブレークポイントの位置を自分で選択します。

• 開発者が選択したブレークポイントのみを使うには、prompt_cache_options.mode を explicit に設定します。各ブレークポイントは、入力メッセージ内の対応するコンテンツブロックに prompt_cache_breakpoint: { "mode": "explicit" } を追加して指定します。
• 明示的なブレークポイントを指定しない場合、そのリクエストはプロンプトキャッシュを使用せず、キャッシュへの書き込みも行いません。
• 明示モードでは、キャッシュに書き込む範囲の終端を選択できます。最後に選択したブレークポイントより後の内容には未キャッシュ入力トークン単価が適用され、キャッシュ書き込み料金は発生しません。頻繁に変わり、再利用の見込みが低い内容を書き込まずに済みます。
• 明示的なブレークポイントを複数指定すると、変更頻度の異なるプレフィックスをそれぞれ保存できます。1 リクエストで最大 4 回のキャッシュ書き込みが可能です。
• additional_tools 入力項目には、現時点では prompt_cache_breakpoint を指定できません。

暗黙モード：OpenAI が、多くのユースケースに適したブレークポイントの位置を自動で選択します。

• リクエストで prompt_cache_options.mode が implicit の場合、OpenAI は対象メッセージのうち最後のものの末尾にブレークポイントを配置します。対象は次のとおりです。
  • ユーザーメッセージ
  • 連続するツール応答のうち最後の応答
  • 冒頭で連続する開発者メッセージのうち最後のメッセージ
• 暗黙的なブレークポイントを有効にしたまま、明示的なブレークポイントを追加できます。4 つのキャッシュ書き込み枠のうち 1 つを暗黙的なブレークポイントが使用するため、残りの 3 枠を明示的な書き込みに使用できます。

暗黙的キャッシュのみ利用できます。OpenAI は、非表示の OpenAI システムメッセージの先頭を起点として、モデルごとに決まった間隔で暗黙的なブレークポイントを配置します。このうち、非表示コンテキストの末尾から数えてキャッシュ可能な最小長に達した位置以降のブレークポイントのみが対象になります。

報告される cached_tokens の値は、最後に一致したブレークポイントまでのトークン数から非表示のシステムトークン数を差し引き、128 の倍数に切り捨てて算出します。

Responses API では、prompt_cache_options.ttl でキャッシュの最小有効期間を選択します。

表の単価は書き込み料金の全額を表し、通常の入力料金に上乗せされるものではありません。キャッシュ読み取り単価はどちらの有効期間でも同じです。OpenAI は指定された最小有効期間を超えてエントリを保持する場合があります。"12h" を指定しても削除期限は設定されず、データの最大保持期間に関するポリシーも変わりません。

リクエスト単位の ttl は、暗黙的なブレークポイントと、個別に ttl を指定していない明示的なブレークポイントに適用されます。明示的なブレークポイントごとに上書きするには、prompt_cache_breakpoint.ttl を設定します。両方を省略すると、デフォルトの "30m" が適用されます。サポートされていない値を指定すると 400 invalid_request_error が返されます。これらの設定は、従来のモデルで使われる prompt_cache_retention パラメーターには影響しません。

1 つのリクエストでの有効期間の使い分け

一日を通じて再利用する資料はプロンプトの先頭に置き、そのブレークポイントの有効期間を "12h" に設定します。変更頻度が高いセッションのコンテキストには "30m" を使用します。次の例ではリクエストのデフォルトを 30 分とし、共通のプレフィックスについてのみ上書きしています。明示モードで現在の質問を最後のブレークポイントより後に置くため、質問の内容にはキャッシュ書き込み料金が発生しません。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{
  "model": "gpt-6.1-sol",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Shared instructions and reference material reused throughout the day...",
          "prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Session context reused over the next few minutes...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "The current question, which does not need a cache write..."
        }
      ]
    }
  ]
}

プレースホルダーのテキストを実際の内容に置き換えてください。キャッシュする各プレフィックスは、モデルのキャッシュ可能な最小長を満たす必要があります。

書き込み範囲の重複と有効期間の変更

各ブレークポイントは、先頭からその位置までのプレフィックス全体を対象とします。1 つのリクエストでは、各トークンを対象とする書き込みのうち、選択された最も長い有効期間の単価で 1 回だけ課金されます。後方のブレークポイントで 12 時間の書き込みを行うと、そのプレフィックス内で選択した手前のブレークポイントにも 12 時間の有効期間が適用されます。

以下の例では、既存のキャッシュ済みプレフィックスがある場合、その終端が新しいリクエストの検索対象の境界と一致すると仮定します。

有効な 30 分のキャッシュを 12 時間に延長すると、対象のトークンには新たに 12 時間の書き込み料金がかかり、先に支払った書き込み料金は差し引かれません。有効な 12 時間のエントリがすでにある部分は、引き続きキャッシュ読み取りとして課金されます。

30 分設定で読み取ると、その時点から少なくとも 30 分間はキャッシュが有効になります。有効な 12 時間のエントリを読み取った場合、有効期限は既存の期限と読み取り時点から 30 分後のうち遅い方になります。12 時間の有効期間が最初から始まることはなく、新たな書き込み料金もかかりません。

保持期間の設定には prompt_cache_retention を使用します。指定できる値はモデルによって異なります。

• in_memory：エントリはアクセスが途絶えてから通常 5～10 分程度、最長で 1 時間有効です。
• 24h：延長保持では通常 30 分程度エントリを利用でき、最長で 24 時間保持されます。

デフォルトの保持設定とゼロデータ保持

プロンプトキャッシュは、暗号化したキーと値のテンソルをアプリケーションの状態として GPU のローカルストレージに保存する場合があります。in_memory と 24h の両方に対応するモデルでは、組織のデータ保持ポリシーによってデフォルトが決まります。

• ゼロデータ保持が無効の組織では、デフォルトは 24h です。
• ゼロデータ保持が有効の組織では、デフォルトは in_memory です。

値を選択する前に、使用するモデルと組織で利用可能な保持ポリシーを確認してください。

GPT-5.6 より前のモデルでは、再利用可能なプレフィックスを共有するリクエストに一定の prompt_cache_key を指定すると、関連するリクエストが同じキャッシュにルーティングされやすくなります。リクエストが多いグループでは、キーごとに、そのキーを使うすべてのプレフィックスの合計が毎分 15 リクエスト程度になるようにします。トラフィックが多い場合は、同じ入力が常に同じキーに対応する規則で複数のキーに分散してください。関連するリクエストでは同じ prompt_cache_key を使うと、そのキャッシュを再利用できます。キーはルーティングに影響しますが、リクエストの送信先マシンを固定したり、キャッシュヒットを保証したりするものではありません。

GPT-5.6 以降では、OpenAI がキャッシュルーティングを自動で行うため、キャッシュの最適化にキーは不要です。アプリケーション内の顧客やユーザーごとにキャッシュ使用量を個別に集計するには、それぞれに別のキーを使用できます。

キーを分けると、顧客やユーザーごとのキャッシュ済みトークンの使用量と請求額の内訳を説明しやすくなります。また、ユーザーをまたいだキャッシュヒットの探査を防ぐのにも役立ちます。これは、候補となるプロンプトを送信してキャッシュヒットを観察し、一致する内容が以前にキャッシュされたかどうかを推測する手法です。キーを使ったキャッシュ使用量の個別集計を参照してください。

複数ターンのアプリケーションでは、最初の指示だけをキャッシュするよりも、ターンごとに増える会話履歴を再利用する方が多くの入力トークンを節約できます。後続のターンで共通のプレフィックス全体を再利用できるよう、過去のメッセージとツールの結果を維持してください。

• プレフィックスを固定します。 変更のない開発者指示や共有の参考資料を先頭に置きます。これらにタイムスタンプ、ユーザー固有の内容、その他の動的な内容が含まれる場合は、その部分を冒頭から末尾に移すか、会話の後続メッセージに移します。
• 会話履歴を維持します。 過去のターンを書き換えずに新しいメッセージを追加します。要約、コンパクション、コンテキストの切り詰めによってプレフィックスが変わると、それまでのキャッシュを再利用できなくなる場合があります。
• プレフィックスを書き換えずに推論強度を変更します。 GPT-6 モデルでは、configuration_update 入力項目を末尾に追加すると、リクエスト単位の reasoning.effort を変えずに応答間で推論強度を変更できます。元のプレフィックスが維持されるため、キャッシュを再利用できます。例と互換性の制約は、会話中の推論設定の変更を参照してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "low", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Stable instructions and shared reference material...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "developer",
      "content": "Dynamic developer instructions, such as user-specific content and timestamps..."
    },
    {
      "role": "user",
      "content": "The user's current question..."
    }
  ]
}

この機能に対応する GPT-6 以降のモデルでは、configuration_update 入力項目を末尾に追加すると、それまでのキャッシュ済みプレフィックスを維持しながら会話中に推論強度を変更できます。トップレベルの reasoning.effort を変更すると非表示のシステム指示が書き換わる場合があるため、元の値のままにしてください。

後続の応答には、reasoning.effort の直近の更新で指定した推論強度が適用されます。input の末尾に次の項目を追加すると、推論強度が high に切り替わります。

1
2
3
4{
  "type": "configuration_update",
  "reasoning": { "effort": "high" }
}

アプリケーションで必要なツールがリクエストごとに異なる場合は、ツール定義を固定したまま、呼び出せるツールを切り替えてください。再利用可能なプレフィックスを維持できます。

• ツールの構成を維持します。 ツール定義、順序、スキーマを変えないようにします。
• リクエストでツールの使用を無効にします。 ツール定義を削除せず、tool_choice を "none" に設定します。
• 選択したツールのみを有効にします。 allowed_tools を使うと、指定した tools リストを変えずに、呼び出せるツールを制限できます。
• 必要になった時点でツールを読み込みます。 ツール検索で defer_loading: true を使うと、複数ターンのスレッドの初期リクエストでツール定義に使う入力トークンを減らせます。見つかったツールはコンテキストの末尾に追加され、それ以前の再利用可能な内容は維持されます。
• ツールの読み込み履歴を維持します。 開発者ロールの additional_tools 入力項目を使うと、アプリケーションのロジックに従ってスレッドの途中でツールを追加できます。

GPT-5.6 以降では、2 つの設定でキャッシュブレークポイントの位置が決まります。prompt_cache_options.mode で暗黙モードまたは明示モードを選択し、prompt_cache_breakpoint で任意の境界を指定します。

• ブレークポイントを自動で配置します。 暗黙的キャッシュを使用すると、最後の対象メッセージの末尾にブレークポイントが配置されます。既存のコンテキストに内容を追加していく複数ターンのスレッドに適しています。
• ブレークポイントの位置を指定します。 変更のない内容の末尾に明示的なブレークポイントを配置します。明示モードを使用すると、頻繁に変わる末尾部分をキャッシュに書き込まずに済みます。

GPT-5.6 以降では、あらかじめ内容がわかっているコンテキストを準備しておくと、後続のリクエストで最初のトークンが返るまでの時間を短縮できます。たとえば対話型アプリケーションでは、ユーザーが最初の質問をする前に、起動時に共有の指示、ツール定義、参考資料をキャッシュに読み込んでおけます。

Responses API リクエストで prompt_cache_options.prewarm を true に設定すると、出力を生成せずにプロンプトキャッシュを準備できます。完了したら、同じプレフィックスを使用し、prewarm を省略するか false に設定して、実際のリクエストを送信してください。

1
2
3
4
5
6
7
8
9
10
11
12{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    }
  ],
  "prompt_cache_options": {
    "prewarm": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "model": "gpt-6.1-sol",
  "input": [
    {
      "role": "developer",
      "content": "Your app's shared instructions and reference material..."
    },
    {
      "role": "user",
      "content": "The user's question..."
    }
  ]
}

事前準備のリクエストでキャッシュに書き込んだトークンには、選択した有効期間のキャッシュ書き込み単価が適用されます。

GPT-5.6 以降では、アプリケーション内の顧客、ユーザー、ワークスペースごとにキャッシュ使用量を集計する場合に prompt_cache_key を使用します。各グループのキャッシュ済みトークンの使用量と請求額の内訳を説明しやすくなります。キーは任意で、これらのモデルでキャッシュを最適化するために指定する必要はありません。

• キャッシュ使用量を分ける単位を決めます。 個別に集計する顧客またはユーザーに、それぞれ異なるキーを割り当てます。たとえば、support:customer_123 と support:customer_456 を使うと、2 人の顧客のリクエストに同じプレフィックスが含まれていても、キャッシュ使用量を別々に集計できます。
• グループ内ではキーを固定します。 同じ顧客の関連するリクエストには同じキーを使います。セッションやスレッドごとのキーを生成するのは、その単位でキャッシュ使用量を個別に集計する必要がある場合だけです。
• キーを一貫して適用します。 顧客ごとの集計を維持するため、その顧客の各リクエストに同じキーを使用します。これは顧客をまたいだキャッシュヒットの探査を防ぐのにも役立ちます。

GPT-5.6 より前のモデルでは、prompt_cache_key がキャッシュヒット率の最適化に重要です。再利用可能なプレフィックスを共有するリクエストには一定のキーを使用し、同じキャッシュにルーティングされやすくします。リクエストが多いグループでは、キーを増やしてトラフィックを分散する方法に従ってください。

Responses API のモデルが prompt_cache_options に対応している場合、頻繁に再利用するコンテキストには "30m" を使用し、長い間隔を空けて再利用する固定のプレフィックスには "12h" を検討してください。12 時間設定の高めの書き込み料金と、30 分設定の有効期限が切れた後にプレフィックスを再度書き込むコストを比較します。ブレークポイント単位で設定を上書きすると、共有資料の有効期間をセッション固有のコンテキストより長くできます。例と課金ルールはキャッシュの有効期間を参照してください。

それより前のモデルでは、モデルが対応しており、データ保持要件でも許容される場合は、prompt_cache_retention を "24h" に設定して延長保持を使用することをおすすめします。対応する設定とデフォルト値はキャッシュの有効期間を参照してください。

多くのリクエストで同じ開発者指示とツール定義を使っていても、共通のプレフィックスがモデルのキャッシュ可能な最小長に満たない場合があります。その場合は、プレフィックスを短くするか、役立つ固定の指示、例、参考資料を加えて長くすることを検討してください。キャッシュの再利用による節約額が、追加入力トークンとキャッシュ書き込みの料金を相殺できるかを測定し、評価結果と動作が安定していることも確認します。

下のグラフは、プレフィックスが短いためにキャッシュを使えず、キャッシュ可能な最小トークン数まで長くした場合よりもコストがかかる範囲を示しています。GPT-5.6 以降の 30 分設定のキャッシュ書き込み単価を使用しています。

• 実際のキャッシュ性能を測定します。 使用量のうち usage.input_tokens_details.cached_tokens、usage.input_tokens_details.cache_write_tokens、有効期間別の書き込み数、入力トークン数を追跡し、レイテンシと実際のコストも記録します。トークン単位のキャッシュヒット率は、キャッシュ済みトークン数の合計を入力トークン数の合計で割って求めます。両方のトークン数をユーザー別、ワークスペース別、日別など、用途に合った単位で集計してください。
• 入力コストを計算します。 計算には response.usage のトークン数と、モデルの100 万トークンあたりの単価を使用します。
• プロンプトキャッシュダッシュボードを使用します。 キャッシュヒット率はプロンプトキャッシュダッシュボードで監視できます。

Responses API のモデルが prompt_cache_options に対応している場合、input_tokens_details.cache_write_tokens_details に、書き込みトークン数の内訳が ttl_30m_tokens と ttl_12h_tokens に分けて示されます。両者に重複はなく、合計は cache_write_tokens と一致します。一方がゼロでも、両方のフィールドが返されます。cached_tokens は読み取りとして課金されたトークン数です。30 分から 12 時間への延長分を含め、書き込みとして課金されたトークンは含まれません。

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 3000,
        "ttl_12h_tokens": 4000
      }
    }
  }
}

この例では、入力のうち 1,000 トークンが通常の入力です（12000 - 4000 - 7000）。入力コストを計算するには、通常の入力トークン数にモデルの入力単価を、cached_tokens にキャッシュ済み入力単価を、ttl_30m_tokens に入力単価の 1.25 倍を、ttl_12h_tokens に入力単価の 2.5 倍を掛けます。100 万トークンあたりの単価を使う場合は、これらを合計して 1,000,000 で割ります。書き込みトークン数の 2 つの内訳を計上した後で、cache_write_tokens を重ねて加算しないでください。

たとえば、100 万トークンあたりの入力単価が 1 ドル、キャッシュ済み入力単価が 0.10 ドルの場合、この使用量の入力コストは (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515 です。キャッシュ済み入力単価を含め、使用するモデルの実際の単価で計算してください。

次のヘルパーでは、すべてのキャッシュ書き込みに同じ単価倍率を適用します。すべての書き込みの有効期間が 30 分の場合は 1.25、すべて 12 時間の場合は 2.5 を使用します。両方の有効期間を使うリクエストでは、上記の方法で期間ごとに書き込み料金を計算してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18function calculateInputCost(
  usage,
  inputPricePerMillion,
  cacheInputMultiplier = 0.1,
  cacheWriteMultiplier = 1.25
) {
  const inputTokens = usage.input_tokens;
  const cachedTokens = usage.input_tokens_details.cached_tokens;
  const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
  const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;

  const weightedInputTokens =
    ordinaryInputTokens +
    cachedTokens * cacheInputMultiplier +
    cacheWriteTokens * cacheWriteMultiplier;
  const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
  return inputCost;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai.types.responses import ResponseUsage


def calculate_input_cost(
    usage: ResponseUsage,
    input_price_per_million: float,
    cache_input_multiplier: float = 0.1,
    cache_write_multiplier: float = 1.25,
) -> float:
    input_tokens = usage.input_tokens
    cached_tokens = usage.input_tokens_details.cached_tokens
    cache_write_tokens = usage.input_tokens_details.cache_write_tokens
    ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

    weighted_input_tokens = (
        ordinary_input_tokens
        + cached_tokens * cache_input_multiplier
        + cache_write_tokens * cache_write_multiplier
    )
    input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
    return input_cost

1
2
3
4
5func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
	ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
	weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
	return weighted * pricePerMillion / 1_000_000
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.models.responses.ResponseUsage;

static double calculateInputCost(
    ResponseUsage usage,
    double pricePerMillion,
    double cacheInputMultiplier,
    double cacheWriteMultiplier) {
  long cached = usage.inputTokensDetails().cachedTokens();
  long written = usage.inputTokensDetails().cacheWriteTokens();
  long ordinary = usage.inputTokens() - cached - written;
  return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
      * pricePerMillion
      / 1_000_000;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def calculate_input_cost(
  usage,
  input_price_per_million,
  cache_input_multiplier = 0.1,
  cache_write_multiplier = 1.25
)
  input_tokens = usage.input_tokens
  details = usage.input_tokens_details
  cached_tokens = details.cached_tokens
  cache_write_tokens = details.cache_write_tokens
  ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens

  weighted_input_tokens = ordinary_input_tokens +
                          (cached_tokens * cache_input_multiplier) +
                          (cache_write_tokens * cache_write_multiplier)
  (weighted_input_tokens * input_price_per_million) / 1_000_000
end

• 既存の固定プレフィックスを維持します。
• 移行前から prompt_cache_key を使用している場合は、顧客やユーザーごとのキャッシュ使用量の集計を維持するため、既存の値を引き継ぎます。
• 保持期間の設定を prompt_cache_retention から prompt_cache_options.ttl に変更します。
• 再利用するプレフィックスがモデルのキャッシュ可能な最小長を満たしていることを確認します。
• デフォルトのブレークポイントまでの範囲にリクエストごとに変わる内容が含まれる場合は、固定プレフィックスの末尾に明示的なブレークポイントを追加します。
• それ以降の内容を書き込む利点がない場合は、prompt_cache_options.mode: "explicit" を使用します。
• cached_tokens、cache_write_tokens、レイテンシ、合計コストを比較して、移行前後の違いを確認してください。

チャットボットとの対話が終わった後、そのやり取りにユーザーの満足を示す証拠があるかを 1 ターンで判定する LLM を考えます。各リクエストでは、同じ採点基準とラベル付きのフューショット例を使い、それぞれ異なる対話を評価します。

• プレフィックスの維持：固定の採点基準と例を先頭に置きます。評価のばらつきを抑えるのに役立つ内容を使って、両者の合計がモデルのキャッシュ可能な最小長を少し上回るように調整します。評価対象の対話は末尾に置きます。
• キャッシュモードとブレークポイント：明示モードを有効にし、固定の採点基準と例の直後にブレークポイントを置きます。評価対象のユーザーとチャットボットの会話はその後に続くため、キャッシュに書き込まれません。これにより、再利用の見込みが低い内容へのキャッシュ書き込み料金を避けられます。

この方法を採用した導入例では、トークン単位のキャッシュヒット率が約 70% と報告されています。これは達成可能な結果の一例です。実際のキャッシュヒット率の上限は、コンテキストやアプリケーションの利用状況によって異なります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    {
      "role": "user",
      "content": "Completed interaction to evaluate..."
    }
  ]
}

長い共通の開発者指示を使い、ツールを頻繁に呼び出す複数ターンのエージェントを考えます。典型的な利用パターンでは、ユーザーはこのエージェントで複数のセッションを同時に実行し、スレッドを頻繁にフォークします。

• プレフィックスの維持：各ターンで以前のコンテキストを書き換えず、新しいメッセージ、ツール呼び出し、結果を末尾に追加します。これにより、再利用可能なプレフィックスがターンごとに長くなります。
• 任意のプロンプトキャッシュキー：この例では agent_123_v1:user_456 を使用してユーザー 456 のキャッシュ使用量を個別に集計し、キャッシュ済みトークンの使用量と請求額の内訳を説明しやすくしています。ユーザーをまたいだキャッシュヒットの探査を防ぐのにも役立ちます。このユーザーがエージェントを使うセッションと、そこからフォークしたスレッドには、すべて同じキーを使います。アプリケーションで個別集計が不要ならキーを省略してください。
• 暗黙的キャッシュ：暗黙モードを有効にすると、対象となるユーザーメッセージまたはツールメッセージのうち最後のものの末尾にブレークポイントが配置されます。
• 明示的なブレークポイント：各ツール結果の直後にブレークポイントを追加することで、そこまでの再利用可能なプレフィックスを維持し、スレッドをフォークしたときのキャッシュ効率を高めます。

この方法を採用した導入例では、トークン単位のキャッシュヒット率が 90% を超えたと報告されています。これは達成可能な結果の一例です。実際のキャッシュヒット率の上限は、コンテキストやアプリケーションの利用状況によって異なります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "medium" },
  "prompt_cache_key": "agent_123_v1:user_456",
  "prompt_cache_options": { "mode": "implicit" },
  "tools": [
    {
      "type": "function",
      "name": "function_name",
      "description": "Function description",
      "parameters": { "...": "..." }
    }
  ],
  "input": [
    {
      "role": "developer",
      "content": "Stable developer instructions and reference material..."
    },
    { "role": "user", "content": "Can you do...?" },
    {
      "type": "function_call",
      "call_id": "call_123",
      "name": "function_name",
      "arguments": "..."
    },
    {
      "type": "function_call_output",
      "call_id": "call_123",
      "output": [
        {
          "type": "input_text",
          "text": "Tool result...",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        }
      ]
    },
    { "role": "assistant", "content": "Assistant response..." },
    { "role": "user", "content": "Can you also do...?" }
  ]
}

これは、暗黙的キャッシュの動作が変わるため、従来モデルから GPT-5.6 以降に移行する場合に特によく起こります。複数のリクエストの先頭に長い共通部分があっても、その後の内容が異なる場合、最初のリクエスト全体を暗黙的にキャッシュするだけでは、それより短い共通プレフィックスを再利用できません。

たとえば、各リクエストで固定の開発者メッセージに続いて動的なユーザーメッセージを送るとします。次のリクエスト例では動的な内容の末尾まで書き込みます。その次のリクエストで動的な内容が変わると、キャッシュ済みの長いプレフィックスには一致しません。また、固定部分の直後には個別のブレークポイントがありません。

1
2
3
4
5
6
7
8
9
10{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "implicit" },
  "input": [
    { "role": "developer", "content": "Static content..." },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

これを解決するには、両方のリクエストで固定部分の直後に明示的なブレークポイントを配置します。最初のリクエストで再利用可能なプレフィックスを書き込むので、次のリクエストでは動的な内容が変わっても再利用できます。次の例では明示モードを使用し、動的な内容がキャッシュに書き込まれないようにしています。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "model": "gpt-6.1-sol",
  "reasoning": { "effort": "medium", "context": "all_turns" },
  "text": { "verbosity": "low" },
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Static content...",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    { "role": "user", "content": "Dynamic content..." }
  ]
}

リクエスト 1 では暗黙モードでユーザーメッセージの末尾までのプレフィックスをキャッシュし、後続のリクエスト 2 ではそのプレフィックスを維持しながら prompt_cache_options.mode: "explicit" に切り替えたとします。プレフィックス照合の仕組みで説明したとおり、リクエスト 2 が照合するのは自身の入力にある明示的なブレークポイントだけです。リクエスト 1 が暗黙的に保存したプレフィックスを再利用できるのは、そのいずれかがリクエスト 1 でキャッシュした終端に一致する場合だけです。

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message] ▼

- Request 2: explicit-only mode. Does not hit cache.
  [Developer message][User message][Follow-up] ▼

リクエスト 1 の暗黙的なプレフィックスを再利用するには、リクエスト 2 で、それに一致するコンテンツブロックの境界に明示的なブレークポイントを置きます。または、以前の対象メッセージの末尾が引き続き検索候補になるように、暗黙モードを有効にしたままにします。

両方のリクエストで暗黙モードを使用しても、先頭のトークン列を維持するだけでは不十分な場合があります。たとえば、リクエスト 1 の最後のユーザーメッセージに Content A が含まれ、後続のリクエスト 2 で同じメッセージを Content A + Content B に拡張したとします。Content A の直後にあった終端は、メッセージの末尾から途中に移ります。プレフィックス照合の仕組みで説明したとおり、その境界に明示的なブレークポイントがなければ、リクエスト 2 はそこまでの保存済みプレフィックスを再利用しません。

▼ = breakpoint

- Request 1: implicit mode
  [Developer message][User message: Content A] ▼

- Request 2: implicit mode. Cannot reuse the prefix through Content A.
  [Developer message][User message: Content A + Content B] ▼

会話の構造上可能であれば、元のメッセージを維持し、新しいメッセージを末尾に追加してください。それが難しい場合は、再利用するテキストを別のコンテンツブロックに置き、両方のリクエストでその直後に明示的なブレークポイントを配置します。

暗黙モードでは、冒頭で連続する開発者メッセージ群より後にある開発者メッセージは、自動的にはキャッシュ検索の境界になりません。再利用する開発者メッセージの末尾に明示的なブレークポイントを追加し、後続のリクエストでも維持してください。これにより、OpenAI は一致するキャッシュ済みプレフィックスをその位置で検索できます。

あるモデルでキャッシュできるプレフィックスが、別のモデルでは短すぎる場合があります。モデルの比較を確認し、実際に使用するモデルと設定で再利用可能なプレフィックスの長さを測定してください。モデルを変更するときは、以前のモデルのしきい値がそのまま適用されると考えず、改めて確認してください。

コンパクションは、それまでの会話のコンテキストを短い表現に置き換えます。これによってプレフィックスが変わることがあるため、会話の意味が同じでも、コンパクション後の最初のリクエストで再利用できる既存のキャッシュは少なくなる場合があります。

再利用する指示や参考資料は可能な限り固定し、後続のターンではコンパクション後のコンテキストに内容を追加します。コンパクション前後の入力コストの合計を比較してください。キャッシュヒット率が下がっても、入力トークン数が減ることでコストを節約できる場合があります。

いいえ。プロンプトキャッシュによってモデルの出力トークンの生成方法が変わることはありません。モデルはキャッシュ済みプレフィックスを使って新たに応答を生成するため、同一のリクエストでも同一の出力になるとは限りません。

いいえ。現在、キャッシュを手動で消去する機能はありません。キャッシュエントリは、モデルのキャッシュの有効期間と保持設定に従って失効します。

はい。キャッシュ済みの入力トークンも、1 分あたりのトークン数の上限にカウントされます。プロンプトキャッシュを使用しても、レート制限の計算方法は変わりません。