ドキュメントの全ページの一覧は、 llms.txt を参照してください。各ページの URL の末尾に .md を追加すると、そのページの Markdown 版を表示できます。
メインナビゲーション

プレフィックスの維持

プレフィックスを変更せず、キャッシュの再利用を促進し、ターンをまたいで推論を保持します。

エージェント型アプリケーションや複数ターンのアプリケーションでは、API リクエストをまたいで推論を保持し、新しいアクションや指示を常にモデルのコンテキストの末尾に追加すると、OpenAI のモデルは最も高い性能を発揮します。プレフィックスを維持することは、プロンプトキャッシュのベストプラクティスとして以前から推奨されています。キャッシュはリクエストを先頭から照合するため、プレフィックスを変更すると、その箇所以降でキャッシュを再利用できなくなることがあります。変更内容を末尾に追加すれば、会話履歴のより広い範囲でキャッシュを再利用でき、入力コストを大幅に削減し、応答を高速化できます。

新しいフロンティアモデルでは、安全対策の一環として、プレフィックスの変更箇所より後にある推論アイテムを API が破棄します。推論アイテムが破棄されると、モデルが推論の一部をやり直す必要が生じ、トークン使用量、コスト、レイテンシーが増えることがあります。失われた推論をモデルが復元できない場合は、出力品質も低下する可能性があります。

モデルの性能を最大限に引き出すには、プレフィックスの変更を避け、可能な限りコンテキストの末尾にのみ変更内容を追加する実装を推奨します。

プレフィックスの変更とは

推論アイテムのプレフィックスとは、そのアイテムより前の会話履歴です。プレフィックスの変更とは、この履歴を変更することです。たとえば、ツールの実行結果を短くする、開発者メッセージを書き換える、過去のターンを要約に置き換えるといった操作が該当します。

会話履歴の変更
元の会話次のリクエストと API での処理
ユーザーメッセージ元帳の合計額を確認してください。同じメッセージ
ツール呼び出し前の推論 再利用可能
ツール呼び出しlookup_ledger()同じ呼び出し
ツールの実行結果[{"amount": 40}, {"amount": 50}]同じ行
ツールの実行結果を受け取った後の推論再利用可能
Both reasoning items have the same history before them as in the original conversation.

プレフィックスの変更を避けるための実装方法

Responses API の tools や text.format などのパラメーターを更新したり、GPT-6.2 より前のモデルで instructions を変更したり、以前の input アイテムを編集したりすると、意図せずプレフィックスが変わることがあります。実装にこうした変更がないか確認してください。

次の表では、実装でプレフィックスが変わる主な理由と、可能な場合にコンテキストの末尾への追加で同じ目的を達成する方法を示します。

プレフィックスが変わる主な理由 プレフィックスの変更を避ける方法
推論強度の変更 Responses API の reasoning.effort パラメーターを変更する代わりに、新しい推論強度を指定した configuration_update アイテムを入力アイテムのリストの末尾に追加します。リクエストレベルの元の設定は維持してください。
構造化出力のスキーマの変更 Responses API の text.format パラメーターを変更する代わりに、新しいスキーマを指定した configuration_update アイテムを入力アイテムのリストの末尾に追加します。リクエストレベルの元の設定は維持してください。
エージェントが利用できるツールの変更 Responses API の tools パラメーターを変更する代わりに、additional_tools アイテムでツールを追加するか、tool_choice に allowed_tools を指定して、そのターンでモデルが呼び出せるツールを制限します。既存のツール定義の順序は維持してください。additional_tools は、ロールを developer に設定し、tools 配列を含めて末尾に追加します。以降のリクエストでこのアイテムを再送する際は、元の位置に入れてください。
開発者の指示の更新 再利用する指示は、最初の developer メッセージに記述して input に含めます。指示を更新するときは、最初の開発者メッセージはそのままにして、新しい developer メッセージをモデルのコンテキストの末尾に追加してください。

GPT-6.2 以降のモデルでは、そのターンだけに適用する開発者メッセージをトップレベルの instructions に指定します。API はこれらのメッセージを input の後に追加します。これらのメッセージのトークンには、キャッシュされていない入力の料金が適用されます。
コンパクション コンパクションを行うとプレフィックスが変わるため、キャッシュミスを避けることは困難です。

OpenAI のコンパクション:/responses/compact または context_management で OpenAI のコンパクションを使用すると、プレフィックスが変わっても、それ以降の推論アイテムは OpenAI のシステムに保持されます。OpenAI のコンパクションアイテムは、コンテキスト内のどの位置にも配置できます。/responses/compact を呼び出すときは instructions を省略し、返されたコンテキストウィンドウを元の順序のまま次のリクエストに渡してください。context_management は、設定の更新と開発者が追加したツールを引き継ぎます。明示的にコンパクションを行った場合は、次のリクエストでそれらを復元してください。

カスタムコンパクション:別の方式や独自の方式を使用する場合、コンパクションで生成したアイテムを直近のターンより前に挿入せず、モデルのコンテキストの末尾に置いてください。元の履歴で挿入位置より後にある推論アイテムが破棄されることを許容するなら、直近のターンより前に配置することもできます。
過去のツール出力の短縮やファイル・画像のサイズ縮小 コンパクションを使わずに、過去のツール出力、ファイル、画像などのアイテムを切り詰める実装もあります。こうした変更はプレフィックスを変えます。コンパクションを使用するか、モデルに初めて送信する前に、長いツール出力は短くし、画像やファイルはサイズを縮小することを強く推奨します。

プレフィックスの変更箇所の確認

プロンプトキャッシュ診断を使うと、キャッシュミスが発生したタイミングや、プレフィックスの変更箇所を調べられます。リクエストを以前のレスポンスと比較するには、prompt_cache_options.comparison_response_id に以前のレスポンス ID を設定し、診断に表示される理由とキャッシュされたトークン数を確認します。この情報をもとに、実装でプレフィックスが変わるケースを減らしてください。診断では、検出できた最初の差分が報告されます。モデルが推論を再利用したかどうかは確認できません。

Responses API のレスポンスに含まれる input_transformations を確認すると、API が入力からどの推論アイテムを削除したかと、その理由が分かります。prefix_mismatch が理由の場合は、id を以前のレスポンスの output に含まれる推論アイテムと照合できます。実装で以前の入力を変更していた場合は、上記の方法で実装を更新すると推論を保持できます。