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

保持前綴不變

避免變更前綴,讓更多內容能沿用快取,並讓模型能在後續回合沿用先前的推理。

在智慧體式應用程式和多回合應用程式中,如果能在多次 API 請求之間保留推理,並一律將新的動作和指示附加在模型上下文的末尾,我們的模型就能發揮最佳效能。保持前綴完整,一直是使用提示詞快取的最佳做法。快取會從請求的開頭依序比對,因此一旦變更前綴,從變更處開始的內容就可能無法沿用快取。將變更附加在末尾,可讓更多對話內容沿用快取,進而大幅降低輸入成本並加快回應速度。

從較新的前沿模型開始,只要前綴有變更,API 就會捨棄變更處之後的推理項目。這是我們防止模型蒸餾的措施之一。模型可能因此必須重新進行部分推理,進而增加 Token 用量與成本,並拉長延遲。如果模型無法還原先前的推理,輸出品質也可能下降。

為了讓我們的模型發揮最佳效能,建議你避免變更前綴,並盡可能採用只在上下文末尾附加內容的整合方式。

什麼是前綴變更?

推理項目的前綴,就是該項目之前的對話歷程。修改這段歷程就會變更前綴,例如縮短工具結果、改寫開發者訊息,或用摘要取代較早的對話回合。

變更對話歷程
原始對話下一個請求與 API 的處理方式
使用者訊息請核對帳本的總金額。相同的訊息
呼叫工具前的推理 可重複使用
工具呼叫lookup_ledger()相同的工具呼叫
工具結果[{"amount": 40}, {"amount": 50}]相同的資料列
取得工具結果後的推理可重複使用
Both reasoning items have the same history before them as in the original conversation.

如何調整整合方式以避免變更前綴

更新 Responses API 的 tools、instructions 或 text.format 等參數,或編輯先前的 input 項目,都可能在無意間變更前綴。請檢查你的應用程式在整合 API 時是否做了這些變更。

下表列出整合 API 時常見的前綴變更情境,並說明在可行的情況下,如何將內容附加在上下文末尾以達到相同目的。

變更前綴的常見原因 如何避免變更前綴
調整推理強度 保留 Responses API 原有的 reasoning.effort 參數,在輸入項目清單末尾附加一個 configuration_update 項目,並在該項目中指定新的推理強度。請維持原有的請求層級設定。
變更結構化輸出的結構描述 保留 Responses API 原有的 text.format 參數,在輸入項目清單末尾附加一個 configuration_update 項目,並在該項目中指定新的結構描述。請維持原有的請求層級設定。
變更智慧體可用的工具 保留 Responses API 原有的 tools 參數。若要新增工具,請使用 additional_tools 項目。若要限制模型在某個回合可呼叫的工具,請搭配使用 tool_choice 和 allowed_tools。請維持既有工具定義的順序。附加 additional_tools 項目時,請將角色設為 developer,並提供 tools 陣列。重新傳送該項目時,請維持其原有位置。
更新開發者指示 保留原始開發者訊息,並附加一則新的 developer 訊息,要求模型忽略舊指示,遵循你提供的新指示。如果指示僅適用於單一回合,請在最新一則開發者訊息的正前方明確設定快取中斷點,讓可重複使用的前綴止於該訊息之前。
壓縮 壓縮會變更前綴,因此很難避免快取未命中。

OpenAI 壓縮: 如果你使用 OpenAI 壓縮功能,並透過 /responses/compact 或 context_management 執行壓縮,即使前綴已變更,我們的系統仍會保留後續的推理項目。OpenAI 壓縮項目可以出現在上下文中的任何位置。呼叫 /responses/compact 時,請省略 instructions,並將傳回的上下文視窗依原有順序傳入下一次請求。如果對話歷程含有 configuration_update 項目,請遵循含有設定更新時的壓縮要求。

自訂壓縮: 如果你使用其他壓縮策略或自行開發的壓縮策略,請將壓縮後的項目放在模型上下文的末尾,避免放在最近幾個回合之前。你也可以接受這項取捨,讓 API 捨棄原始對話歷程中位於該項目之後的推理項目。
縮短先前的工具輸出,或縮小先前的檔案或圖像 有些應用程式會截斷先前的工具輸出、檔案或圖像等項目,而未使用壓縮功能。這些做法都會變更前綴。我們強烈建議使用壓縮功能,或在首次將內容傳送給模型之前,先縮短過長的工具輸出,並縮小圖像或檔案。

檢查整合流程中是否有前綴變更

使用提示詞快取診斷查看何時發生快取未命中,並調查前綴變更。若要將某個請求與較早的回應進行比對,請將 prompt_cache_options.comparison_response_id 設為該回應的 ID,然後查看診斷結果列出的原因與已快取的 Token 數量。你可以根據這些資訊,減少整合流程中的前綴變更。診斷工具會盡可能找出差異,並回報找到的第一處差異,但無法確認模型是否沿用了先前的推理。

查看 Responses API 回應中的 input_transformations,即可得知 API 從輸入中移除了哪些推理項目,以及移除原因。如果移除原因是 prefix_mismatch,你可以根據 id,在較早回應的 output 中找出對應的推理項目。如果你的整合流程修改了先前的輸入,可以依照上述建議調整整合方式,以保留推理項目。