プロンプトキャッシュ

プロンプトキャッシュの重要性

プロンプトキャッシュは、同じプロンプトプレフィックスを共有するリクエスト間で処理結果を再利用します。主なメリットは次の 3 つです。

計算効率の向上： モデルがすでに処理したプロンプトプレフィックスの再計算を省きます。
入力トークンのコスト削減： 再利用するトークンには、モデルの割安なキャッシュ済み入力料金が適用され、最大 90% 割引になります。
高速化： 応答が始まるまでの入力処理時間を短縮します。

対応する OpenAI モデルでは、プロンプトキャッシュがデフォルトで有効になっています。プロンプトキャッシュダッシュボードでキャッシュ読み取りのヒット率を監視し、プロンプトキャッシュの診断ツールでキャッシュミスの原因を調べ、キャッシュの再利用を改善できます。

Agents API のモデル呼び出しでは、Responses API と同じプロンプトキャッシュの仕組みが使われます。セッション内でコンテキストを再利用すると、共通のプロンプトプレフィックスを維持できますが、セッションを維持してもキャッシュヒットが保証されるわけではありません。セッションの使用量フィールドとサブエージェントの使用量の集計については、可観測性と使用状況を参照してください。

プロンプトキャッシュの料金はモデルによって異なります。キャッシュ済み入力とキャッシュ書き込みの最新の単価については、API 料金を参照してください。キャッシュ書き込み料金は追加料金ではありません。入力トークンには、未キャッシュ入力、キャッシュ済み入力、キャッシュ書き込みのいずれかの単価が適用されます。

プロンプトキャッシュとは

モデルは入力トークンを処理する際、キー・バリュー（KV）状態と呼ばれる中間状態を計算する必要があります。この状態により、新しい入力の処理や出力トークンの生成中に、それまでのトークンを参照できます。

プロンプトキャッシュは、再利用可能な プレフィックス、つまりプロンプトの先頭にある変化しないトークン列の状態を保持します。後続のリクエストが同じプレフィックスを持ち、一致するキャッシュエントリが見つかると、モデルはそのトークン列を再処理せずに保存済みの状態を再利用できます。ただし、新しい応答を生成するには、新たな入力を処理する必要があります。

プロンプトキャッシュに保存されるのは、トークンそのものではなく、キー・バリュー（KV）テンソルです。

ChatGPT に詳しい説明を依頼

OpenAI は、モデルのレンダリング済みコンテキスト全体をキャッシュします。これには、OpenAI が提供する指示、開発者メッセージ、ツール定義、およびテキスト、画像、ドキュメント、サポート対象の音声を含む会話履歴が含まれます。

キャッシュを再利用するには、レンダリング済みのプレフィックス全体が一致する必要があります。ブレークポイントより前でコンテンツや関連する設定が変わると、その変更箇所以降を含むプレフィックスは既存のキャッシュエントリと一致しなくなります。

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

設定	影響
`model`	モデルが異なると、使用する重みやキャッシュの動作が異なる場合があります。
`tools`	ツールの名前、説明、スキーマ、順序、またはツール固有の指示が変わります。
`parallel_tool_calls`	1 回のターンで複数のツールを呼び出す際の指示が変わる場合があります。
`text.format`（構造化出力）	出力形式の指示と、指定したスキーマが追加されます。
`reasoning.effort`	モデル側の推論に関する指示が変わる場合があります。対応するモデルでは、構成の更新を使用すると、それまでのプレフィックスを保持しながら推論強度を変更できます。
`text.verbosity`	応答の詳しさに関する指示が変わる場合があります。
`context_management`（コンパクション）	それまでの会話内容を圧縮されたコンテキストに置き換えるため、最初に変更されたトークン以降を再利用できなくなる場合があります。

キャッシュの仕組み

キャッシュブレークポイント は、OpenAI がキャッシュに保存し、後続のリクエストで再利用できるプロンプトプレフィックスの終端を示します。最初のリクエストで対象のプレフィックスをキャッシュに書き込みます。後続のリクエストでは、一致するものが見つかるまで対象のブレークポイントを末尾側から順にたどり、利用可能なキャッシュ済みプレフィックスのうち、一致する最長のものを探します。

プロンプトプレフィックスをキャッシュするには、モデルの キャッシュ可能な最小トークン長 を満たす必要があります。OpenAI が提供する非表示のシステムコンテンツ内のトークンは、この最小トークン長に含まれません。キャッシュ可能なプロンプトの最小長は、GPT-5.6 以降では 1,024 トークンで、それ以前のモデルではリクエスト設定によって異なります。詳しくは、モデルの比較をご覧ください。

キャッシュ可能な最小トークン長に達した後は、キャッシュブレークポイントの位置を明示的に指定するか、OpenAI に暗黙的な選択を任せることができます。利用できる選択肢はモデルによって異なります。

GPT-5.6 以降では、キャッシュ書き込みの料金は、キャッシュを使わない標準の入力トークン料金の 1.25 倍です。その後の読み取り料金は標準料金のわずか 0.1 倍なので、プレフィックスを再利用することがわかっている場合は、この書き込み料金を支払う価値があります。プレフィックスを 1 回書き込み、全体を 1 回再利用した場合のコストは通常の入力コストの 1.35 倍で、キャッシュを使わずに 2 回処理した場合の 2 倍より安くなります。キャッシュを読み取るたびに削減効果は大きくなります。10 回のリクエストで、1 回の書き込みと 9 回の全体読み取りを行う場合のコストは 2.15 倍で、キャッシュを使わない場合の 10 倍と比べて抑えられます。

暗黙的キャッシュと明示的キャッシュの両方がサポートされています。明示的キャッシュでは、キャッシュに書き込むコンテキストをより細かく制御できます。

明示的モード： コンテキストの管理方法に合わせて、キャッシュブレークポイントを配置する位置を選択します。

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

トップレベルの instructions には、明示的ブレークポイントを含めることができません。再利用可能な開発者の指示にブレークポイントを付けるには、その指示を開発者メッセージ内の input_text ブロックに配置します。

暗黙的モード： 特別な設定なしで、OpenAI がほとんどのユースケースに適した位置にブレークポイントを配置します。

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

プレフィックス照合の仕組み

OpenAI は、受信したリクエスト内の キャッシュ検索境界 （後述）のみを、プレフィックスが長い順に確認します。そのマシンにすでにキャッシュされている、一致する利用可能なプレフィックスを探します。

GPT-5.6 以降では、受信したリクエスト内のキャッシュ検索境界は次のとおりです。

明示的指定のみのモード： 最初の 2 個と直近の 50 個の明示的ブレークポイント
暗黙的モード： 最初の 2 個と直近の 50 個の明示的ブレークポイント、暗黙的ブレークポイント、それ以前の対象メッセージの末尾（最大 20 件）、および冒頭の連続した開発者メッセージ群の末尾が対象です。このため、暗黙的モードでは、以前のメッセージの末尾に明示的ブレークポイントがなくても、そこまでのプレフィックスを再利用できます。

モデルの世代

キャッシュモード

暗黙的

明示的

暗黙的ブレークポイントは、対象となる最新のユーザーメッセージに配置されます。

非表示のシステムツール開発者コンテキスト履歴追加メッセージキャッシュ済み入力キャッシュされていない入力

キャッシュ可能な最小長（モデルによって異なる）

リクエスト 1

入力トークン数：12,000

3,000 トークン（説明用の例）

リクエスト 2

入力トークン数：15,000

3,000 トークン（説明用の例）

2.5k

7.5k

10k

12.5k

15k

17.5k

20k

入力トークン（説明用の非表示トークンを含む）

15,000

最後に一致したブレークポイント

−

3,000

非表示のトークン

12,000

報告されるキャッシュ済みトークン数

リクエスト 1・Responses API リクエスト

import OpenAI from "openai";

const client = new OpenAI();
const response = await client.responses.create({
  "model": "gpt-5.6",
  "reasoning": {
    "effort": "medium",
    "context": "all_turns"
  },
  "text": { "verbosity": "medium" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "8,000 tokens"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "2,000 tokens"
        }
      ]
    }
  ],
  "tools": [
    "Tool definitions, 2,000 tokens"
  ],
  "prompt_cache_key": "shared-workflow-v1",
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "30m"
  }
});

リクエスト 2・Responses API リクエスト

import OpenAI from "openai";

const client = new OpenAI();
const response = await client.responses.create({
  "model": "gpt-5.6",
  "reasoning": {
    "effort": "medium",
    "context": "all_turns"
  },
  "text": { "verbosity": "medium" },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "8,000 tokens"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "2,000 tokens"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "3,000 tokens"
        }
      ]
    }
  ],
  "tools": [
    "Tool definitions, 2,000 tokens"
  ],
  "prompt_cache_key": "shared-workflow-v1",
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "30m"
  }
});

リクエスト 1・レスポンスの使用量

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 12000
    }
  }
}

リクエスト 2・レスポンスの使用量

{
  "usage": {
    "input_tokens": 15000,
    "input_tokens_details": {
      "cached_tokens": 12000,
      "cache_write_tokens": 3000
    }
  }
}

キャッシュの有効期間

キャッシュエントリは無期限に保存されるわけではありません。後続のリクエストでキャッシュ済みのプレフィックスを再利用できるのは、そのエントリが利用可能な間だけです。プレフィックスを再利用すると、キャッシュ書き込み料金が再度発生することなく、有効期間が更新されます。有効期間と保持の設定はモデルによって異なります。

キャッシュの保存場所

キャッシュされた状態は個々のマシンに保存されます。1 分あたり 15 件を超えるリクエストがあると、オーバーフローによって別のマシンにルーティングされる場合があります。リクエストがキャッシュ済みのプレフィックスを再利用できるのは、一致する有効期限内のエントリを保持するマシンに到達した場合だけです。そのため、キャッシュの再利用には、適切なマシンへのリクエストのルーティングが重要です。

キャッシュは組織間で共有されず、処理リージョンの境界を越えて再利用することもできません。

OpenAI はルーティングを自動的に処理します。同じ組織と処理リージョン内では、特定のモデルへのルーティングは次の要素によって決まります。

マシンの現在の負荷と利用可能な容量
非表示の OpenAI コンテンツに続く先頭のトークンのハッシュ値。ツール定義がある場合はそれも含まれます。ハッシュ化するトークンの数はモデルによって異なります。
指定された prompt_cache_key。リクエストのグループ間でキャッシュの再利用を分離し、GPT-5.6 より前のモデルではキャッシュルーティングの最適化に役立ちます。

モデル間の違いの概要

動作	GPT-5.6 以降	GPT-5.5 と GPT-5.5 Pro	その他の以前のモデル
暗黙的なブレークポイント	対象となる最新のメッセージの末尾に配置されます。	2,048 トークンごとの一定間隔で配置されます。	モデルに応じた一定間隔で配置されます。
明示的なブレークポイント	サポートあり	サポートなし	サポートなし
`prompt_cache_key`	キャッシュの利用量と料金を分けて管理する場合に任意で使用	同じキーを使い続けてキャッシュルーティングを最適化	同じキーを使い続けてキャッシュルーティングを最適化
キャッシュ可能なプレフィックスの最小長	可視の入力トークン 1,024 個	リクエストの設定によって異なります	リクエストの設定によって異なります
キャッシュ済みトークン数の報告	非表示トークンを除外し、対象となる境界までの正確な数を報告	非表示トークンを除外し、128 の倍数に切り捨て	非表示トークンを除外し、128 の倍数に切り捨て
キャッシュ読み取り料金	キャッシュされていない入力トークンの単価の 0.1 倍	モデルに応じたキャッシュ済み入力の単価	モデルに応じたキャッシュ済み入力の単価
キャッシュ書き込み料金	キャッシュされていない入力トークンの単価の 1.25 倍	キャッシュ書き込みの追加料金なし	キャッシュ書き込みの追加料金なし
キャッシュの有効期間の制御	`prompt_cache_options.ttl`	`prompt_cache_retention`	`prompt_cache_retention`
サポートされている保持設定値	`"30m"`	`"24h"` のみ	`"in_memory"` または `"24h"`^*
キャッシュの有効期間	最後の書き込みまたは再利用から少なくとも 30 分	通常は 30 分程度、最長で 24 時間	`in_memory` では使用されなくなってから通常 5～10 分、`24h` では最長で 24 時間

* 拡張保持は、gpt-5.5、gpt-5.5-pro、gpt-5.4、gpt-5.2、gpt-5.1-codex-max、gpt-5.1、gpt-5.1-codex、gpt-5.1-codex-mini、gpt-5.1-chat-latest、gpt-5、gpt-5-codex、gpt-4.1 でサポートされています。

GPT-5.6 より前のモデルでは、キャッシュ可能な入力の最小長は、ツール、画像、出力スキーマ、推論強度、応答の詳しさなど、リクエストの設定によって異なります。

ChatGPT に、このリクエストでキャッシュ可能な最小入力長の確認を依頼

プロンプトキャッシュの最適化方法

会話履歴の保持、ツール定義を変えずに維持すること、キャッシュする箇所の選択に重点を置いてください。GPT-5.6 以降では、prompt_cache_options.mode と prompt_cache_breakpoint を使用してキャッシュのブレークポイントを制御します。アプリケーションで顧客ごとにキャッシュの利用量と料金を分けて管理する必要がある場合は、任意で prompt_cache_key も使用できます。GPT-5.6 より前のモデルでは、再利用可能なプレフィックスを共有するリクエストに同じ prompt_cache_key を使い続けて、キャッシュルーティングを最適化してください。

ChatGPT にプロンプトキャッシュの最適化を依頼

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

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

変更される内容をブレークポイントの後に配置

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-5.6",
  "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 は元の値を維持してください。この設定を変更すると、非表示のシステム指示の内容が書き換わることがあります。

最新の構成更新によって、後続の応答の推論強度が決まります。たとえば、以降のリクエストの推論強度を high に切り替えるには、既存の input 配列の末尾に次の項目を追加します。

input 配列の末尾に追加する項目

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

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

キャッシュの利用量と料金を分けて管理する単位を決めます。 個別に管理する必要がある顧客やユーザーごとに、異なるキーを割り当てます。たとえば、support:customer_123 と support:customer_456 を使用すると、2 人の顧客のリクエストに同じプレフィックスが含まれていても、キャッシュの利用量と料金を分けて管理できます。
各グループ内でキーを一定に保ちます。 同じ顧客の関連するリクエストでは、同じキーを再利用してください。セッションやスレッドに別のキーを生成するのは、そのキャッシュの利用量と料金を個別に管理する必要がある場合に限ります。
キーを一貫して適用します。 顧客のすべてのリクエストにその顧客のキーを使用し、キャッシュの利用量と料金を分けて管理します。これにより、キャッシュヒットを利用して他の顧客の情報を探る行為の防止にも役立ちます。

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

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

このグラフは、キャッシュ可能な最小トークン長までプレフィックスを長くするよりも、短いままキャッシュせずに使う方が高くつくことがあるという、最小長に伴うコストの落とし穴を示しています。

プロンプトの長さと入力コスト

キャッシュ可能な最小トークン数書き込み 1 回あたりのキャッシュ全体の読み取り回数キャッシュ読み取り料金の倍率キャッシュ書き込み料金の倍率

500

1,000

1,500

2,000

再利用可能なプレフィックスの長さ（トークン数）

コストのみを比較するため、 $M$ をキャッシュ可能な最小の長さ、 $L < M$ を元のプレフィックスの長さ、 $r$ をキャッシュ読み取り料金の倍率、 $w$ をキャッシュ書き込み料金の倍率、 $N$ をリクエストの総数とします。拡張後のプレフィックスは正確に $M$ トークンで、書き込みは 1 回だけ行い、それ以降のすべてのリクエストで全体を再利用すると仮定します。キャッシュされていない入力トークン数に換算すると、元のプレフィックスを維持する場合のコストは $N \times L$ 、拡張する場合のコストは $M \left[w + (N - 1)r\right]$ です。両者のコストが等しくなる元の長さは、次のとおりです。

L_{\mathrm{break\text{-}even}} = M\left(r + \frac{w-r}{N}\right)

拡張するのは、 $L > L_{\mathrm{break\text{-}even}}$ の場合です。短いプレフィックスを維持した方が低コストになるのは、 $L < L_{\mathrm{break\text{-}even}}$ の場合です。等号が成り立つ場合、コストは同じです。拡張した方が低コストになる最小の整数トークン数は $\left\lfloor L_{\mathrm{break\text{-}even}} \right\rfloor + 1$ です。一方、キャッシュ可能なプレフィックスを $M$ 未満に短縮すると、キャッシュを利用できなくなります。同じ仮定の下では、短縮後のキャッシュされないプレフィックスの長さが $L_{\mathrm{break\text{-}even}}$ 未満であることが、 $M$ トークンをキャッシュする場合より低コストになるための条件です。コストが最大になるプロンプトの長さは一律には決まりません。コストが逆転する点は、再利用の回数と料金によって変わります。

たとえば、 $M = 1{,}024$ 、 $r = 0.1$ 、 $w = 1.25$ の場合、コストが逆転する点は $102.4 + \frac{1{,}177.6}{N}$ トークンです。リクエストが 10 回の場合、元の長さが 221 トークン以上のプレフィックスを 1,024 トークンに拡張すると、コストが下がります。再利用が増えるほど、コストが逆転する点は 102.4 トークンに近づきます。103 トークンのプレフィックスでコスト削減効果を得るには、合計で少なくとも 1,963 回のリクエストが必要です。この仮定の下では、102 トークン以下のプレフィックスでは効果が得られません。この比較では、パフォーマンス、出力トークン、変化しないリクエストコストは考慮していません。追加のキャッシュミスや書き込みが発生したり、モデルの料金が異なったりすると、結果は変わります。

実際のキャッシュのパフォーマンスを測定します。 usage.input_tokens_details.cached_tokens、usage.input_tokens_details.cache_write_tokens、入力トークン数、レイテンシ、実際に発生したコストを追跡します。キャッシュされたトークンの総数を入力トークンの総数で割り、トークンのキャッシュヒット率を追跡します。両方のトークン数を、ユーザー別、ワークスペース別、日別など、用途に合った単位で集計してください。
入力コストを計算します。 response.usage のトークン数と、モデルの 100 万トークンあたりの料金を使用します。
プロンプトキャッシュのダッシュボードを使用します。 プロンプトキャッシュのダッシュボードでキャッシュヒット率を監視します。

入力コストの計算

JavaScript

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
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

例

以下の例は、GPT-5.6 以降のモデルに適用されます。

チャットボットとの完了済みのやり取りを調べ、ユーザーが満足したことを示す証拠があるかどうかを判定する、シングルターンの LLM 評価器を考えます。各リクエストでは、同じ評価基準とラベル付きのフューショット例を使用して、異なるやり取りを評価します。

プレフィックスの維持： 固定の評価基準と例を先頭に配置します。評価器の判定を調整するのに役立つ資料を使い、両者の合計の長さがモデルのキャッシュ可能な最小の長さをわずかに上回るよう、意図的に調整します。評価対象のやり取りは最後に配置します。
キャッシュモードとブレークポイント： 明示的なブレークポイントのみを使用するキャッシュを有効にし、固定の評価基準と例の後にブレークポイントを配置します。評価対象のユーザーとチャットボットの会話は、そのブレークポイントの後に配置し、キャッシュには書き込みません。これにより、再利用される可能性が低いコンテンツへのキャッシュ書き込み料金を回避します。

これらの原則を適用した導入例では、 約 70% のトークンキャッシュヒット率が報告されています。この数値は、得られる可能性のある結果の一例です。実際に達成できるキャッシュヒット率の上限は、コンテキストとアプリケーションの利用状況によって異なります。

シングルターンの評価器向けの Responses API リクエスト

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
  "model": "gpt-5.6-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% と報告されています。この数値は、得られる結果の一例です。実際に達成できるキャッシュヒット率の上限は、コンテキストやアプリケーションの利用状況によって異なります。

複数ターンのエージェント向け Responses API リクエスト

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-5.6-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-5.6-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-5.6-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 では自身の入力にある明示的なブレークポイントだけを確認します。そのため、リクエスト 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] ▼

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

おすすめ

はじめに

基本コンセプト

SDK と CLI

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプト

推論

画像と動画

リアルタイムと音声

特化型モデル

Agents API

Agents SDK

ChatKit

検索と取得

ツールとデータの接続

ツールを使ったワークフローの構築

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を活用した開発

接続

音声処理

本番運用の開始

性能と品質

コストとスループット

安全性とガバナンス

インフラとアクセス

オペレーション

基本コンセプト

Plan

Build

Test and publish

Conversion specs

ガイド

リソース

はじめに

ガイド

File Upload

API

Measurement

Advertiser API

API リファレンス

はじめに

基礎

詳しく見る

利用可能な環境

リリース

ワークフロー

できること

リファレンス

カスタマイズ

設定ファイル

エージェントの構成

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

拡張と自動化

環境

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバーセーフティ

はじめに

ChatGPT Work

ID と認証

ワークスペースのアクセス、ポリシー、モデル

プラグインとコネクタの制御

利用状況、ガバナンス、コンプライアンス

展開とモデルプロバイダー

コミュニティ

ブログ

コミュニティ

ブログ