如果請求重用的 Token 比預期少,可以透過提示詞快取診斷了解原因。將請求與先前的回應比較,即可找出模型、工具、設定或輸入中有哪些變更導致快取無法重用。
在 Responses API 中,GPT-5.6 及後續支援的模型均可使用診斷功能。你可以用這項功能調查個別請求,並透過提示詞快取儀表板監控整個應用程式的快取效能。
運作方式
提示詞快取診斷會將目前的請求與先前的回應比較,協助你了解為什麼未能如預期重用提示詞前綴。前綴是指提示詞開頭的一段內容。若要重用快取,前綴必須完全相符,而且模型、服務層級、工具等請求設定也必須相容。
- 選擇基準回應。 從同一個組織中選擇一筆近期已完成的回應,例如上一輪對話的回應。該回應的前綴應是你預期目前請求會重用的內容。
- 要求比較。 將
prompt_cache_options.comparison_response_id設為基準回應的id。 - 查看結果。 檢查目前回應中的
prompt_cache_diagnostics。如果診斷偵測到快取未命中,結果會列出原因,供你進一步調查。使用usage.input_tokens_details.cached_tokens可衡量實際重用的快取 Token 數。
設定 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。傳送下一個請求時,將這個值指定給 comparison_response_id,並將該欄位放在 prompt_cache_options 中。第一輪請省略比較用的 ID。
測試修正是否有效時,請繼續使用基準回應的 ID 進行比較。
串流
使用 stream=True 時,請讀取 prompt_cache_diagnostics。這個欄位位於 event.response 中,請從 response.completed 事件取得。
解讀回應
查看 prompt_cache_diagnostics.type 即可判斷比較結果。
| 類型 | 含義 | 處理方式 |
|---|---|---|
cache_hit |
這次比較未偵測到快取未命中。 | 查看 usage.input_tokens_details.cached_tokens,確認實際重用的 Token 數。 |
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 中未被重用的估計數量。
診斷中的 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 |
輸出格式或其結構描述已變更。 | 在支援此功能的 GPT-6 及後續模型上,請維持相同的頂層 text.format 設定。需要使用不同的結構描述時,請在輸入末端新增格式更新項目。 |
reasoning_effort_changed |
推理強度已變更。 | 在支援此功能的 GPT-6 及後續模型上,可在輸入末端新增 configuration_update 項目,以便在對話中變更推理強度,同時保留先前已快取的前綴。在較舊的模型上,預期共用前綴的請求應使用相同的 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,這個值無法用來判斷快取是否命中。 - 診斷絕不會阻擋請求、導致請求失敗,或改變模型產生輸出的方式。