プロンプトキャッシュの診断では、リクエストで再利用されたトークンが想定より少なかった理由を調べられます。リクエストを過去のレスポンスと比較すると、モデル、ツール、設定、入力のどの変更が再利用を妨げたかを特定できます。
Responses API では、GPT-5.6 およびそれ以降の対応モデルで診断を利用できます。個々のリクエストを調べるには診断を、アプリケーション全体のキャッシュ性能を監視するにはプロンプトキャッシュダッシュボードを使用します。
診断の仕組み
プロンプトキャッシュの診断では、現在のリクエストを過去のレスポンスと比較し、再利用を想定していたプロンプトのプレフィックスが再利用されなかった理由を調べます。プレフィックスとは、プロンプトの先頭部分です。再利用には、プレフィックスが完全に一致し、モデル、サービスティア、ツールなどのリクエスト設定に互換性があることが必要です。
- 基準となるレスポンスを選びます。 同じ組織で最近完了したレスポンスのうち、現在のリクエストでプレフィックスを再利用する想定のものを選びます。たとえば、会話の直前のターンで得たレスポンスを使用できます。
- 比較をリクエストします。
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 を保存し、次のリクエストで comparison_response_id として prompt_cache_options に渡します。最初のターンでは比較用の ID を省略します。
修正の効果をテストするときは、比較用の ID を基準となるレスポンスの ID に固定します。
ストリーミング
stream=True の場合、prompt_cache_diagnostics は event.response に含まれます。response.completed イベントで読み取ってください。
レスポンスの見方
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 |
出力形式またはそのスキーマが変わりました。 | GPT-6 およびそれ以降の対応モデルでは、トップレベルの text.format をリクエスト間で維持します。別のスキーマが必要な場合は、出力形式の更新を末尾に追加します。 |
reasoning_effort_changed |
推論強度が変わりました。 | GPT-6 およびそれ以降の対応モデルでは、configuration_update 入力項目を末尾に追加すると、キャッシュ済みのプレフィックスを維持したまま会話の途中で推論強度を変更できます。それより前のモデルでは、プレフィックスを共有するリクエスト間で 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はヒットもミスも示しません。比較の準備が整っていない場合にも、この結果が返されます。 - 診断によってリクエストがブロックされたり失敗したりすることはなく、モデルの出力生成方法が変わることもありません。