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

提示詞快取

使用提示詞快取降低延遲與成本。

為什麼要使用提示詞快取?

當多個請求共用相同的提示詞前綴時,提示詞快取可以重複使用先前的運算結果。這有三項主要好處:

  • 節省運算資源: 模型已處理過的提示詞前綴無須重新計算。
  • 降低輸入 Token 費用: 重複使用的 Token 按模型的快取輸入費率計費,最高可省 95%。
  • 加快回應: 縮短開始回應前處理輸入的時間。

支援提示詞快取的 OpenAI 模型預設會啟用這項功能。你可以在提示詞快取儀表板監控快取讀取命中率,並使用提示詞快取診斷工具找出快取未命中的原因,提高快取重用率。

透過 Agents API 呼叫模型時,提示詞快取的運作方式與 Responses API 相同。在同一工作階段中重複使用上下文有助於保留共用的提示詞前綴,但持續使用同一工作階段並不能保證快取命中。如需瞭解工作階段的用量欄位,以及子代理程式的用量如何計入,請參閱可觀測性與用量。

提示詞快取的價格因模型而異。如需目前的快取輸入與快取寫入費率,請參閱 API 定價。快取寫入費用不會額外加收。每個輸入 Token 只會按未快取輸入、快取輸入或快取寫入其中一種費率計費。

什麼是提示詞快取?

模型處理輸入 Token 時,必須計算稱為鍵值(KV)狀態的中間狀態。模型處理新輸入及產生輸出 Token 時,可以透過這些狀態參照先前的 Token。

提示詞快取會為可重複使用的前綴保存這些狀態。前綴是提示詞開頭維持不變的一段 Token。如果後續請求具有相同前綴,且找到相符的快取項目,模型就能重複使用已儲存的狀態,省去再次處理這些 Token 的運算。模型仍須處理新增的輸入,才能產生新的回應。

提示詞快取儲存的是鍵值(KV)張量,而非 Token 本身。

請 ChatGPT 詳細解說

OpenAI 會快取模型實際接收的完整上下文,包括 OpenAI 提供的指示、開發者訊息、工具定義,以及對話記錄中的文字、圖片、文件和支援的音訊。

模型實際接收的整段前綴都必須相符,才能重複使用快取。如果中斷點之前的內容或相關設定有所變動,從變動處起,前綴就無法與現有快取項目相符。

快取的運作方式

快取中斷點標示提示詞前綴的結尾,OpenAI 可以將截至該處的前綴寫入快取,供後續請求重複使用。第一個請求會將符合條件的前綴寫入快取。後續請求則會從後往前逐一檢查符合條件的中斷點,直到找到可用且相符的最長快取前綴。

提示詞前綴必須達到模型的可快取 Token 數下限,才能寫入快取。OpenAI 提供的隱藏系統內容所含的 Token 不計入此下限。GPT-5.6 及後續模型的提示詞至少要有 1,024 個 Token 才能快取,較早模型的下限則取決於請求設定。詳情請參閱模型比較。

達到可快取 Token 數下限後,你可以明確指定快取中斷點的位置,也可以讓 OpenAI 自動選擇。可用選項取決於模型。

如何比對前綴

OpenAI 只會檢查傳入請求中的快取查找邊界(如下所述),依前綴由長到短的順序,尋找該機器上已快取且可用的相符前綴。

在 GPT-5.6 及後續模型上,傳入請求的快取查找邊界如下:

  • 僅使用明確中斷點的模式: 最前面的 2 個與最近的 50 個明確中斷點。
  • 隱含模式: 最前面的 2 個與最近的 50 個明確中斷點、隱含中斷點、最多 20 則較早且符合條件的訊息結尾,以及開頭一組連續開發者訊息的結尾。因此,即使較早的訊息結尾沒有明確中斷點,隱含模式仍可重用截至該處的前綴。
模型世代
快取模式

隱式斷點設在最後一則符合條件的使用者訊息處。

隱藏的系統內容工具開發者上下文歷史紀錄後續訊息已快取的輸入未快取的輸入
可快取的最短長度(依模型而異)

請求 1

12,000 個輸入 Token
3,000 個 Token(示意)

請求 2

15,000 個輸入 Token
3,000 個 Token(示意)
0
2.5k
5k
7.5k
10k
12.5k
15k
17.5k
20k
輸入 Token(含示意用的隱藏 Token)
15,000
最後一個相符的斷點
−
3,000
隱藏的 Token
=
12,000
回報的已快取 Token 數

快取有效期間

快取項目不會永久儲存。快取的最短有效期間、保留設定,以及請求重用前綴時的行為,都取決於模型。

快取位置

快取狀態儲存在個別機器上。當流量超過每分鐘 15 個請求時,超出的流量可能會被轉送至其他機器。只有當請求送達的機器存有相符且尚未到期的項目,才能重用快取前綴。因此,將請求路由至正確的機器,對重用快取十分重要。

不同組織之間不共用快取,也無法跨區域處理邊界重用快取。

OpenAI 會自動處理路由。在同一組織與處理區域內,特定模型的請求路由取決於下列因素:

  • 機器目前的負載與可用容量。
  • OpenAI 隱藏內容之後最前面一段 Token 的雜湊值。如有工具定義,也會納入計算。用於計算雜湊的 Token 數量因模型而異。
  • 請求提供的 prompt_cache_key。這個鍵可將不同請求群組的快取重用範圍分開,在 GPT-5.6 之前的模型上也有助於最佳化快取路由。

模型差異一覽

行為 GPT-5.6 及後續模型 GPT-5.5 與 GPT-5.5 Pro 其他較早的模型
隱含中斷點 位於最近一則符合條件的訊息結尾。 每隔 2,048 個 Token 設置一個。 按固定間隔設置,間隔長度因模型而異。
明確中斷點 支援 不支援 不支援
prompt_cache_key 選用,可分開計算快取用量與費用 使用固定的鍵來最佳化快取路由 使用固定的鍵來最佳化快取路由
可快取前綴的長度下限 1,024 個可見輸入 Token 取決於請求設定 取決於請求設定
快取 Token 數的回報方式 精確計算至符合條件的邊界,不含隱藏 Token 扣除隱藏 Token,再向下取整至 128 的倍數 扣除隱藏 Token,再向下取整至 128 的倍數
快取讀取費用 未快取輸入的 0.1 倍(GPT-6.1 Sol 與 GPT-6.1 Terra 為 0.05 倍) 依模型的快取輸入費率計費 依模型的快取輸入費率計費
快取寫入費用 "30m" 為 1.25 倍,Responses API 的 "12h" 為 2.5 倍 不額外收取快取寫入費用 不額外收取快取寫入費用
快取有效期間設定 prompt_cache_options.ttl prompt_cache_retention prompt_cache_retention
支援的保留設定值 "30m"(預設),Responses API 也支援 "12h" 僅支援 "24h" "in_memory" 或 "24h"*
快取有效期間 最短有效期間為 30 分鐘或 12 小時,請參閱有效期限的更新方式 通常約 30 分鐘,最長可達 24 小時 in_memory 通常可在閒置後保留 5 至 10 分鐘,24h 最長可保留 24 小時

* 支援延長保留的模型包括 gpt-5.5、gpt-5.5-pro、gpt-5.4、gpt-5.2、gpt-5.1-codex-max、gpt-5.1、gpt-5.1-codex、gpt-5.1-codex-mini、gpt-5.1-chat-latest、gpt-5、gpt-5-codex 和 gpt-4.1。

在 GPT-5.6 之前的模型上,可快取輸入的長度下限會隨請求設定而變動,包括工具、圖片、輸出結構描述、推理強度及回應詳盡程度。

請 ChatGPT 找出我的請求可快取的長度下限

如何最佳化提示詞快取

請優先保留對話記錄、維持工具定義不變,並選擇適當的快取中斷點位置。在 GPT-5.6 及後續模型上,使用 prompt_cache_options.mode 與 prompt_cache_breakpoint 控制快取中斷點。如果應用程式需要分別計算各個客戶的快取用量與費用,也可以使用選用的 prompt_cache_key。在 GPT-5.6 之前的模型上,對於共用可重用前綴的請求,請使用固定的 prompt_cache_key 來最佳化快取路由。

請 ChatGPT 幫我最佳化提示詞快取

範例

以下範例適用於 GPT-5.6 及後續模型。

常見陷阱

常見問題

資料保留

所有提示詞快取功能都與零資料保留(ZDR)相容。

提示詞快取儲存的是鍵值(KV)張量,而非原始提示詞文字。這些張量可能會以加密的應用程式狀態儲存在 GPU 本機儲存空間,最長保留 24 小時。各模型的快取有效期間與有效期限更新方式,請參閱快取有效期間。

不同組織之間不共用快取,也無法跨區域處理邊界重用快取。各項 API 功能的資料處理方式與 ZDR 適用條件,請參閱你的資料。