プロンプトキャッシュの診断は、リクエストで再利用されたトークン数が想定より少なかった理由を調べるのに役立ちます。リクエストを過去のレスポンスと比較して、再利用を妨げたモデル、ツール、設定、入力の変更を特定します。
診断は、GPT-5.6 およびそれ以降の対応モデルで Responses API を通じて利用できます。個々のリクエストの調査には診断を、アプリケーション全体のキャッシュパフォーマンスの監視にはプロンプトキャッシュダッシュボードを使用します。
仕組み
プロンプトキャッシュの診断では、現在のリクエストと過去のレスポンスを比較し、想定していたプロンプトのプレフィックスが再利用されなかった理由を調べます。プレフィックスとは、プロンプトの先頭部分のコンテンツです。再利用するには、プレフィックスが完全に一致し、モデル、サービスティア、ツールなどのリクエスト設定に互換性がある必要があります。
- 基準となるレスポンスを選択します。 直前の会話ターンなど、現在のリクエストでプレフィックスを再利用する想定のレスポンスを使用します。同じ組織で最近完了したレスポンスを選んでください。
- 比較をリクエストします。
prompt_cache_options.comparison_response_idに、基準となるレスポンスのidを設定します。 - 結果を確認します。 現在のレスポンスの
prompt_cache_diagnosticsを確認します。診断でキャッシュミスが特定された場合、結果には調査に役立つ理由が含まれます。実際のキャッシュ再利用量を測定するには、usage.input_tokens_details.cached_tokensを使用します。
comparison_response_id の設定は、診断をリクエストするだけです。過去の会話を読み込んだり、キャッシュの動作を変更したりすることはありません。現在のリクエストでは、他のリクエストのキャッシュエントリでも、一致するものは引き続き再利用できます。
使用例
次の例では、同じモデル、指示、入力で 2 つのリクエストを送信しますが、関数ツールの名前を get_time から get_date に変更します。2 つ目のリクエストでは、1 つ目を基準にキャッシュの再利用状況を比較します。
support-policy.txt には、ご自身のポリシードキュメントを使用してください。再利用可能なプレフィックスは、モデルのキャッシュ可能な最小長を満たす必要があります。GPT-5.6 以降では 1,024 トークンです。
from pathlib import Path
from openai import OpenAI
client = OpenAI()
policy = Path("support-policy.txt").read_text() # At least 1,024 tokens.
first = client.responses.create(
model="gpt-6-astra",
instructions=policy,
input="Reply with exactly OK.",
tools=[{"type": "function", "name": "get_time"}],
)
second = client.responses.create(
model="gpt-6-astra",
instructions=policy,
input="Reply with exactly OK.",
tools=[{"type": "function", "name": "get_date"}],
prompt_cache_options={"comparison_response_id": first.id},
)
diagnostics = second.prompt_cache_diagnostics
if diagnostics is not None and diagnostics.type == "cache_miss":
print(diagnostics.reason)
print(diagnostics.comparison_reusable_tokens)
print(diagnostics.cache_missed_tokens)ツールの変更によってキャッシュミスが発生すると、次のような結果が返される場合があります。トークン数は入力によって異なります。
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}再利用を維持するには、リクエスト間でツールの定義と順序を変更しないでください。追記のみの更新によるツール管理を参照してください。
複数ターンの会話
連続するターンを比較するには、完了した各レスポンスの id を保存し、次のリクエストで prompt_cache_options 内の comparison_response_id として渡します。最初のターンでは比較 ID を省略します。
修正をテストする際は、比較 ID を基準となるレスポンスの ID に設定したままにしてください。
ストリーミング
stream=True の場合は、response.completed イベントの event.response から prompt_cache_diagnostics を読み取ります。
レスポンスの見方
prompt_cache_diagnostics.type を確認して、比較結果を判断します。
| 種類 | 意味 | 対処方法 |
|---|---|---|
cache_hit | 比較でキャッシュミスは検出されませんでした。 | usage.input_tokens_details.cached_tokens を確認して、実際の再利用量を測定します。 |
cache_miss | 差異があったため、想定していたプレフィックスが再利用されませんでした。結果には reason と cache_missed_tokens が含まれます。comparison_reusable_tokens が含まれる場合もあります。 | キャッシュミスの解消で、理由と推奨される修正方法を確認してください。 |
comparison_response_not_found | 比較対象のレスポンスに、利用可能な診断レコードがありません。レコードが存在しないか、有効期限が切れている可能性があります。 | 同じ組織で最近完了した別のレスポンスを選択してください。 |
unavailable | 比較で確定的な結果が得られなかったか、モデルが診断に対応していません。 | モデルが診断に対応していることを確認し、最近の別のレスポンスとの比較を試してください。レスポンス自体は通常どおり使用できます。 |
トークン数の見方
cache_hit は、比較でキャッシュミスが検出されなかったことを意味します。それでも、新しい入力の処理が必要になる場合があります。たとえば、入力が 2,500 トークンのリクエストで、比較対象のレスポンスの 2,000 トークンのプレフィックスを再利用し、新しい 500 トークンを処理した場合、cache_hit が返されることがあります。
cache_miss の場合は、次のように解釈します。
comparison_reusable_tokensが存在する場合、その値は比較対象のレスポンスの再利用可能なプレフィックスをそのまま数えたトークン数です。cache_missed_tokensは、それらのトークンのうち再利用されなかった数の推定値です。
これらの診断上のトークン数は、使用量として報告されるトークン数とは異なる場合があります。報告されたキャッシュ再利用量と課金額を測定するには、現在のレスポンスの使用量フィールドを使用してください。
キャッシュミスの解消
prompt_cache_diagnostics.reason をもとに、次の表でキャッシュミスの原因と推奨される修正方法を確認してください。
モデルの切り替えや会話のコンパクションなど、意図的に行う変更もあります。キャッシュの再利用が減る場合でも、その変更を維持することを選べます。
| 理由 | 変更内容 | 再利用の改善方法 |
|---|---|---|
model_changed | ルーティング、A/B テスト、フォールバックなどで別のモデルが選択されたため、異なるモデルがリクエストを処理しました。 | モデルの選択時に意図しない切り替えが発生していないか確認してください。キャッシュ済みプレフィックスを共有する想定のリクエストでは、同じモデルを使用してください。キャッシュに影響する設定を参照してください。 |
prompt_cache_key_changed | 指定されたキーがリクエスト間で変わりました。この場合、物理的なキャッシュミスが発生していなくても、レスポンスの usage でキャッシュミスとして報告されることがあります。 | アプリケーションで顧客別やユーザー別にキャッシュ利用量を集計する必要がなければ、prompt_cache_key は省略してください。キーを使用する場合は、各グループ内で同じキーを維持してください。キーによるキャッシュ利用量の個別集計を参照してください。 |
service_tier_changed | リクエストの処理に使用されたサービスティアが変わりました。 | プレフィックスを共有する想定のリクエストでは、サービスティアを統一してください。返された service_tier はリクエストで指定した値と異なる場合があるため、確認してください。対応する値と動作については、service_tierを参照してください。 |
tools_changed | ツールが追加、削除、並べ替えされたか、ツールの説明、スキーマ、構成が変更されました。 | ツールの定義と順序を維持してください。指定するツールリストを変更せずに、tool_choice: "none" でツールを無効にしたり、allowed_tools で実行可能なツールを制限したりできます。追記のみの更新によるツール管理を参照してください。 |
text_format_changed | 出力形式またはそのスキーマが変わりました。 | 必要な出力構造が変わらない場合は、text.format とスキーマを維持してください。構造化出力を参照してください。 |
reasoning_effort_changed | 推論強度が変わりました。 | プレフィックスを共有する想定のリクエストでは、reasoning.effort を統一してください。キャッシュに影響する設定を参照してください。 |
verbosity_changed | レスポンスの詳細度が変わりました。 | プレフィックスを共有する想定のリクエストでは、text.verbosity を統一してください。キャッシュに影響する設定を参照してください。 |
context_compacted | コンパクションによって、以前の会話内容が置き換えられました。 | 共通の指示は変更せず、後続のターンではコンパクション後のコンテキストを引き継ぎます。入力コストの合計を比較してください。キャッシュの再利用が減っても、入力トークン数が少なくなればコストを削減できる場合があります。コンパクションを参照してください。 |
input_changed | 指示にタイムスタンプやリクエスト ID が含まれている、以前のメッセージが編集、並べ替え、削除されたなどの理由で、先行する入力が変更されました。 | 変化するコンテンツは、再利用可能なプレフィックスとそのキャッシュブレークポイントの後に配置します。以前のメッセージとツールの結果を保持し、新しいターンを末尾に追加します。会話履歴の保持を参照してください。 |
改善の確認
変更後は、次の手順を実行します。
- 代表的なリクエストをもう一度送信し、意図したベースラインと比較します。
- 診断結果を確認し、差異が残っていないか調べます。
- 複数のリクエストで
cached_tokens、cache_write_tokens、合計コストを比較します。
使用量の指標とコストの計算については、キャッシュパフォーマンスの監視を参照してください。
料金とレート制限
プロンプトキャッシュの診断には追加料金がかからず、レート制限にも別途カウントされません。ベースラインの取得や再試行のために Responses API に追加で送信するリクエストには、通常どおり料金が発生し、レート制限にもカウントされます。
ゼロデータ保持
プロンプトキャッシュの診断は、ゼロデータ保持に対応しています。OpenAI は、この機能のために生のプロンプトやモデル出力を保存しません。診断レコードには、構成メタデータ、トークン数の推定値、キャッシュに影響するコンテンツの比較に使うハッシュが含まれます。これらのレコードは組織単位で管理され、短期間で有効期限が切れます。用途は、プロンプトキャッシュのヒットまたはミスの理由を説明することに限られます。
comparison_response_id を設定しても、以前のレスポンスの内容が取得されたり、永続化されたりすることはありません。OpenAI のデータ管理については、お客様のデータを参照してください。
制限事項
- 診断は、Responses API で GPT-5.6 およびそれ以降の対応モデルを使用する場合に利用できます。
- 診断レコードは短期間で有効期限が切れます。レスポンス自体が API から引き続き取得可能でも、診断レコードの有効期限が切れている場合は
comparison_response_not_foundが返されます。 - 診断では、最初に分類された理由が報告されます。その原因に対処してから比較を繰り返し、ほかの原因がないか確認してください。
- 診断はベストエフォートで行われるため、すべてのキャッシュミスを分類できるとは限りません。比較の準備ができていない場合は
unavailableが返されます。この結果は、ヒットもミスも示しません。 - 診断によってリクエストがブロックされたり、失敗したり、モデルの出力生成方法が変わったりすることはありません。