如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

提示詞快取診斷

比較回應,找出未能重用提示詞快取的原因。

如果請求重用的 Token 比預期少,可以透過提示詞快取診斷了解原因。將請求與先前的回應比較,即可找出模型、工具、設定或輸入中有哪些變更導致快取無法重用。

在 Responses API 中,GPT-5.6 及後續支援的模型均可使用診斷功能。你可以用這項功能調查個別請求,並透過提示詞快取儀表板監控整個應用程式的快取效能。

運作方式

提示詞快取診斷會將目前的請求與先前的回應比較,協助你了解為什麼未能如預期重用提示詞前綴。前綴是指提示詞開頭的一段內容。若要重用快取,前綴必須完全相符,而且模型、服務層級、工具等請求設定也必須相容。

  1. 選擇基準回應。 從同一個組織中選擇一筆近期已完成的回應,例如上一輪對話的回應。該回應的前綴應是你預期目前請求會重用的內容。
  2. 要求比較。 將 prompt_cache_options.comparison_response_id 設為基準回應的 id。
  3. 查看結果。 檢查目前回應中的 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,或先前的訊息曾經過編輯、重新排序或移除。 將會變動的內容移到可重用前綴及其快取中斷點之後。保留先前的訊息和工具結果,並在末端加入新一輪對話。請參閱保留對話記錄。

確認改善成效

完成變更後:

  1. 再傳送一個具代表性的請求,並與預定的基準回應比較。
  2. 查看診斷結果,確認是否仍有差異。
  3. 比較多個請求的 cached_tokens、cache_write_tokens 和總成本。

如需了解用量指標和成本計算方式,請參閱監控快取效能。

計價與速率限制

提示詞快取診斷不會產生額外費用,也不會另外計入速率限制。為建立基準或重試而額外傳送至 Responses API 的請求,均會照常計費並計入速率限制。

零資料保留

提示詞快取診斷與零資料保留相容。OpenAI 不會為了這項功能儲存原始提示詞或模型輸出。診斷記錄包含設定中繼資料、Token 數估計值,以及用來比較會影響快取重用的內容的雜湊值。這些記錄的使用範圍限於所屬組織,會在短時間後過期,且僅用於說明提示詞快取命中或未命中的原因。

設定 comparison_response_id 不會擷取或持久儲存先前回應的內容。如需了解 OpenAI 提供的資料控制措施,請參閱你的資料。

限制

  • 在 Responses API 中,GPT-5.6 及後續支援的模型均可使用診斷功能。
  • 診斷記錄會在短時間後過期。記錄過期後,即使仍可透過 API 取得回應,診斷也會傳回 comparison_response_not_found。
  • 診斷只會回報第一個能歸類的原因。請先處理該原因,再次比較以確認是否還有其他原因。
  • 診斷會盡可能找出原因,但未必能為每次快取未命中歸類。比較結果尚未就緒時,會傳回 unavailable,這個值無法用來判斷快取是否命中。
  • 診斷絕不會阻擋請求、導致請求失敗,或改變模型產生輸出的方式。