提示詞快取診斷可協助你瞭解，為何請求重複使用的 Token 數量少於預期。將請求與先前的回應比較，即可找出模型、工具、設定或輸入的哪些變更導致無法重複使用快取。
Responses API 中的 GPT-5.6 及後續支援的模型提供診斷功能。你可以使用此功能調查個別請求，並透過提示詞快取儀表板監控整個應用程式的快取效能。
運作方式
提示詞快取診斷會將目前的請求與先前的回應比較，協助你瞭解為何未能如預期重複使用提示詞前綴。前綴是提示詞開頭的內容。若要重複使用快取，前綴必須完全相符，且模型、服務層級、工具等請求設定也必須相容。
- 選擇基準回應。 從同一組織中，選擇一個近期已完成、且你預期目前請求會重複使用其前綴的回應，例如前一輪對話的回應。
- 要求比較。 將
prompt_cache_options.comparison_response_id設為基準回應的id。 - 查看結果。 檢查目前回應中的
prompt_cache_diagnostics。若診斷發現快取未命中，結果會包含原因，協助你調查。使用usage.input_tokens_details.cached_tokens衡量實際的快取重複使用情況。
設定 comparison_response_id 只會要求執行診斷，不會載入先前的對話或改變快取行為。目前的請求仍可重複使用其他請求中相符的快取項目。
使用範例
以下範例會傳送兩個使用相同模型、指令與輸入的請求，但將函式工具的名稱從 get_time 改為 get_date。第二個請求會以第一個請求為基準，比較快取重複使用情況。
請在 support-policy.txt 中放入你自己的政策文件。可重複使用的前綴必須符合模型的可快取內容最小長度；GPT-5.6 及後續模型的最低要求為 1,024 個 Token。
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)如果工具變更導致快取未命中，結果可能如下所示。Token 數量會隨輸入而異。
{
"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 | 此次比較無法得出確定的結果，或模型不支援診斷功能。 | 請確認模型是否支援診斷功能，並嘗試使用另一個近期回應進行比較。你仍可正常使用此回應。 |
解讀 Token 數量
cache_hit 表示此次比較未偵測到快取未命中，但仍可能需要處理新的輸入。例如，一個含有 2,500 個輸入 Token 的請求，若重複使用了比較回應中長度為 2,000 個 Token 的前綴，並處理了 500 個新 Token，仍可回報 cache_hit。
若結果為 cache_miss：
- 若有
comparison_reusable_tokens欄位，其值代表比較回應中可重複使用前綴的原始 Token 數量。 cache_missed_tokens估算這些 Token 中有多少未被重複使用。
這些診斷計數可能與用量計數不同。請使用目前回應的用量欄位，衡量回報的快取重複使用情況與計費金額。
修正快取未命中問題
根據 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 | 壓縮作業取代了先前的對話內容。 | 保持指令穩定，讓後續輪次接續壓縮後的上下文。比較輸入總成本：即使快取重用減少，較少的輸入 Token 仍可能節省費用。請參閱壓縮。 |
input_changed | 先前的輸入有所變更，例如指令包含時間戳記或請求 ID，或先前的訊息經過編輯、重新排序或移除。 | 將會變動的內容移到可重用的前綴及其快取斷點之後。保留先前的訊息和工具結果，並在後方新增輪次。請參閱保留對話歷史記錄。 |
確認改善成效
進行變更後：
- 再傳送一個具代表性的請求，並與預定的基準比較。
- 檢查診斷結果，確認是否仍有差異。
- 比較多個請求的
cached_tokens、cache_write_tokens和總成本。
如需瞭解用量指標和成本計算方式，請參閱監控快取效能。
定價與速率限制
提示詞快取診斷不會產生額外費用，也不會另行計入速率限制。任何額外傳送至 Responses API 的基準請求或重試請求，均按一般方式計費，並計入速率限制。
零資料保留
提示詞快取診斷與零資料保留相容。OpenAI 不會為此功能儲存原始提示詞或模型輸出。診斷記錄包含組態中繼資料、Token 數量估計值，以及用於比較會影響快取的內容的雜湊值。這些記錄的使用範圍限於所屬組織，會在短時間後到期，且僅用於說明提示詞快取命中或未命中的原因。
設定 comparison_response_id 不會擷取或持久儲存先前回應的內容。如需瞭解 OpenAI 的資料控管措施，請參閱你的資料。
限制
- Responses API 的 GPT-5.6 及後續支援的模型提供診斷功能。
- 診斷記錄會在短時間後到期。記錄到期後，即使仍可透過 API 取得該回應，也會傳回
comparison_response_not_found。 - 診斷會回報第一個可歸類的原因。解決該原因後，請再次比較，以檢查是否有其他原因。
- 診斷會盡力判別原因，但可能無法將每次未命中歸類。若比較尚未就緒，會傳回
unavailable結果；此結果不代表命中或未命中。 - 診斷絕不會阻擋請求或導致請求失敗，也不會改變模型產生輸出的方式。