為什麼要使用提示詞快取?
當多個請求共用相同的提示詞前綴時,提示詞快取可以重複使用先前的運算結果。這有三項主要好處:
- 節省運算資源: 模型已處理過的提示詞前綴無須重新計算。
- 降低輸入 Token 費用: 重複使用的 Token 按模型的快取輸入費率計費,最高可省 95%。
- 加快回應: 縮短開始回應前處理輸入的時間。
支援提示詞快取的 OpenAI 模型預設會啟用這項功能。你可以在提示詞快取儀表板監控快取讀取命中率,並使用提示詞快取診斷工具找出快取未命中的原因,提高快取重用率。
透過 Agents API 呼叫模型時,提示詞快取的運作方式與 Responses API 相同。在同一工作階段中重複使用上下文有助於保留共用的提示詞前綴,但持續使用同一工作階段並不能保證快取命中。如需瞭解工作階段的用量欄位,以及子代理程式的用量如何計入,請參閱可觀測性與用量。
提示詞快取的價格因模型而異。如需目前的快取輸入與快取寫入費率,請參閱 API 定價。快取寫入費用不會額外加收。每個輸入 Token 只會按未快取輸入、快取輸入或快取寫入其中一種費率計費。
什麼是提示詞快取?
模型處理輸入 Token 時,必須計算稱為鍵值(KV)狀態的中間狀態。模型處理新輸入及產生輸出 Token 時,可以透過這些狀態參照先前的 Token。
提示詞快取會為可重複使用的前綴保存這些狀態。前綴是提示詞開頭維持不變的一段 Token。如果後續請求具有相同前綴,且找到相符的快取項目,模型就能重複使用已儲存的狀態,省去再次處理這些 Token 的運算。模型仍須處理新增的輸入,才能產生新的回應。
提示詞快取儲存的是鍵值(KV)張量,而非 Token 本身。
請 ChatGPT 詳細解說
OpenAI 會快取模型實際接收的完整上下文,包括 OpenAI 提供的指示、開發者訊息、工具定義,以及對話記錄中的文字、圖片、文件和支援的音訊。
模型實際接收的整段前綴都必須相符,才能重複使用快取。如果中斷點之前的內容或相關設定有所變動,從變動處起,前綴就無法與現有快取項目相符。
變更請求不一定會讓現有快取項目失效。重要的是後續請求是否具有相同前綴,以及能否找到符合條件且相符的中斷點。請優先檢查以下設定:
| 設定 | 影響 |
|---|---|
model |
不同模型可能使用不同權重,快取的運作方式也可能不同。 |
tools |
會改變工具名稱、說明、結構描述、順序或個別工具的指示。 |
parallel_tool_calls |
可能改變在同一輪呼叫多個工具的相關指示。 |
text.format(結構化輸出) |
在支援此功能的 GPT-6 及後續模型上,請附加格式更新,以便在前綴中保留原有的結構描述。 |
reasoning.effort |
可能改變模型端的推理指示。在支援的模型上,可透過更新設定調整推理強度,同時保留先前的前綴。 |
text.verbosity |
可能改變控制回應詳盡程度的指示。 |
context_management(壓縮) |
會以壓縮後的上下文取代先前的對話內容。從第一個變動的 Token 起,就可能無法重複使用快取。 |
快取的運作方式
快取中斷點標示提示詞前綴的結尾,OpenAI 可以將截至該處的前綴寫入快取,供後續請求重複使用。第一個請求會將符合條件的前綴寫入快取。後續請求則會從後往前逐一檢查符合條件的中斷點,直到找到可用且相符的最長快取前綴。
提示詞前綴必須達到模型的可快取 Token 數下限,才能寫入快取。OpenAI 提供的隱藏系統內容所含的 Token 不計入此下限。GPT-5.6 及後續模型的提示詞至少要有 1,024 個 Token 才能快取,較早模型的下限則取決於請求設定。詳情請參閱模型比較。
達到可快取 Token 數下限後,你可以明確指定快取中斷點的位置,也可以讓 OpenAI 自動選擇。可用選項取決於模型。
在 GPT-5.6 及後續模型上,快取的預設有效期間為 30 分鐘,寫入費率是標準未快取輸入 Token 費率的 1.25 倍。使用 Responses API 時,可選擇至少保留 12 小時,寫入費率為一般輸入的 2.5 倍。無論選擇哪種有效期間,這些模型大多按一般輸入費率的 0.1 倍計算後續讀取費用,GPT-6.1 Sol 和 GPT-6.1 Terra 則按 0.05 倍計費。
假設讀取費率為 0.1 倍,寫入時選擇 30 分鐘的有效期間,寫入前綴一次並完整重用一次,總費用是該前綴一般輸入費用的 1.35 倍。若不使用快取,處理兩次則要 2 倍。以相同費率計算,10 個請求中寫入一次、完整讀取九次的總費用為 2.15 倍,不使用快取則為 10 倍。
模型支援隱含與明確兩種快取模式。明確快取可讓你更精確地控制要將哪些上下文寫入快取。
明確模式: 依上下文管理需求,自行選擇快取中斷點的位置。
- 將
prompt_cache_options.mode設為explicit,即可只使用開發者指定的中斷點。請在輸入訊息中支援此功能的內容區塊加入prompt_cache_breakpoint: { "mode": "explicit" },逐一標記所需的中斷點。 - 如果沒有設定明確中斷點,請求就不會使用提示詞快取,也不會寫入快取。
- 在僅使用明確中斷點的模式下,你可以決定快取寫到哪裡為止。最後一個指定中斷點之後的內容按未快取輸入 Token 費率處理,不收取快取寫入費用。這樣就能避免寫入經常變動且不太可能重用的內容。
- 設定多個明確中斷點,可保留變動頻率不同的前綴。每個請求最多可寫入快取四次。
additional_tools輸入項目目前不接受prompt_cache_breakpoint。
頂層 instructions 不能包含明確中斷點。若要標記可重用的開發者指示,請將指示放在開發者訊息的 input_text 區塊中。
隱含模式: OpenAI 會自動選擇適合大多數使用情境的中斷點位置。
- 當
prompt_cache_options.mode為implicit時,OpenAI 會在最近一則符合條件的訊息結尾放置中斷點。符合條件的訊息包括:- 使用者訊息
- 一組連續工具回應中的最後一則回應
- 開頭一組連續開發者訊息中的最後一則訊息。
- 你可以保留隱含中斷點,同時新增明確中斷點。隱含中斷點會占用四個快取寫入名額中的一個,剩下三個可供明確中斷點使用。
較早的模型只支援隱含快取。OpenAI 會從隱藏的 OpenAI 系統訊息開頭算起,按各模型指定的間隔放置隱含中斷點。但判斷前綴是否達到可快取長度下限時,會從隱藏上下文的結尾算起。只有達到或超過此下限的中斷點才符合條件。
計算回報的 cached_tokens 時,會先從最後一個命中中斷點的 Token 總數扣除隱藏的系統 Token,再向下取整至最接近的 128 的倍數。
如何比對前綴
OpenAI 只會檢查傳入請求中的快取查找邊界(如下所述),依前綴由長到短的順序,尋找該機器上已快取且可用的相符前綴。
在 GPT-5.6 及後續模型上,傳入請求的快取查找邊界如下:
- 僅使用明確中斷點的模式: 最前面的 2 個與最近的 50 個明確中斷點。
- 隱含模式: 最前面的 2 個與最近的 50 個明確中斷點、隱含中斷點、最多 20 則較早且符合條件的訊息結尾,以及開頭一組連續開發者訊息的結尾。因此,即使較早的訊息結尾沒有明確中斷點,隱含模式仍可重用截至該處的前綴。
隱式斷點設在最後一則符合條件的使用者訊息處。
請求 1
12,000 個輸入 Token請求 2
15,000 個輸入 Token請求 1 · Responses API 請求
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
"model": "gpt-5.6",
"reasoning": {
"effort": "medium",
"context": "all_turns"
},
"text": { "verbosity": "medium" },
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "8,000 tokens"
}
]
},
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "2,000 tokens"
}
]
}
],
"tools": [
"Tool definitions, 2,000 tokens"
],
"prompt_cache_key": "shared-workflow-v1",
"prompt_cache_options": {
"mode": "implicit",
"ttl": "30m"
}
});請求 2 · Responses API 請求
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
"model": "gpt-5.6",
"reasoning": {
"effort": "medium",
"context": "all_turns"
},
"text": { "verbosity": "medium" },
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "8,000 tokens"
}
]
},
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "2,000 tokens"
}
]
},
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "3,000 tokens"
}
]
}
],
"tools": [
"Tool definitions, 2,000 tokens"
],
"prompt_cache_key": "shared-workflow-v1",
"prompt_cache_options": {
"mode": "implicit",
"ttl": "30m"
}
});請求 1 · 回應中的用量資訊
1
2
3
4
5
6
7
8
9{
"usage": {
"input_tokens": 12000,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 12000
}
}
}請求 2 · 回應中的用量資訊
1
2
3
4
5
6
7
8
9{
"usage": {
"input_tokens": 15000,
"input_tokens_details": {
"cached_tokens": 12000,
"cache_write_tokens": 3000
}
}
}快取有效期間
快取項目不會永久儲存。快取的最短有效期間、保留設定,以及請求重用前綴時的行為,都取決於模型。
在 Responses API 中,可設定 prompt_cache_options.ttl 來選擇快取的最短有效期間:
| 值 | 最短有效期間 | 快取寫入費率 | 適用情境 |
|---|---|---|---|
"30m"(預設) |
30 分鐘 | 未快取輸入 Token 費率的 1.25 倍 | 頻繁重用上下文的對話與智慧體執行步驟。 |
"12h" |
12 小時 | 未快取輸入 Token 費率的 2.5 倍 | 相隔較長時間仍會重用的固定指示或參考資料。 |
上表列出寫入的完整費率,無須另加一般輸入費用。兩種有效期間的快取讀取費率相同。OpenAI 可能會保留快取項目超過請求指定的最短期間。"12h" 不會設定刪除期限,也不會改變最長資料保留期限的政策。
請求層級的 ttl 適用於隱含中斷點,以及未個別指定 ttl 的明確中斷點。若要覆寫個別明確中斷點的有效期間,請設定 prompt_cache_breakpoint.ttl。兩項設定都省略時,會沿用預設的 "30m"。指定不支援的值會傳回 400 invalid_request_error。這些設定不會改變較早模型的 prompt_cache_retention 參數。
在同一個請求中搭配使用不同的有效期間
將一整天都會重用的資料放在提示詞開頭,並將該中斷點的有效期間設為 "12h"。較常變動的工作階段上下文則使用 "30m"。以下範例將請求的預設有效期間設為 30 分鐘,再為共用前綴覆寫此設定。在僅使用明確中斷點的模式下,目前的問題位於最後一個中斷點之後,因此不會產生快取寫入費用。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30{
"model": "gpt-6.1-sol",
"prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "Shared instructions and reference material reused throughout the day...",
"prompt_cache_breakpoint": { "mode": "explicit", "ttl": "12h" }
}
]
},
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Session context reused over the next few minutes...",
"prompt_cache_breakpoint": { "mode": "explicit" }
},
{
"type": "input_text",
"text": "The current question, which does not need a cache write..."
}
]
}
]
}請將預留位置的文字替換成你的內容。要快取的每個前綴都必須達到模型的可快取長度下限。
寫入範圍重疊與有效期間變更
每個中斷點涵蓋其前方的整段前綴。在同一個請求中,每個 Token 只計費一次,費率取決於涵蓋該 Token 的所有指定寫入中最長的有效期間。如果較後方的中斷點指定寫入 12 小時快取,同一前綴中較早指定的中斷點也會享有 12 小時的有效期間。
以下範例假設,現有的快取前綴都與新請求中符合條件的查找邊界相符。
| 請求前的快取狀態 | 指定的中斷點 | 按讀取計費的 Token 數 | 按 30 分鐘寫入計費的 Token 數 | 按 12 小時寫入計費的 Token 數 |
|---|---|---|---|---|
| 沒有快取前綴 | "12h" 設於第 2,000 個 Token,"30m" 設於第 5,000 個 |
0 | 3,000 | 2,000 |
| 沒有快取前綴 | "30m" 設於第 2,000 個 Token,"12h" 設於第 5,000 個 |
0 | 0 | 5,000 |
| 前 2,000 個 Token 的 30 分鐘快取仍有效 | "12h" 設於第 5,000 個 Token |
0 | 0 | 5,000 |
| 前 2,000 個 Token 的 12 小時快取仍有效 | "30m" 設於第 5,000 個 Token |
2,000 | 3,000 | 0 |
將仍有效的 30 分鐘快取升級為 12 小時時,這些 Token 會重新按 12 小時寫入費率計費,先前支付的寫入費用不予折抵。已有有效 12 小時快取涵蓋的部分仍按快取讀取計費。
以 30 分鐘有效期間讀取快取後,該快取至少會持續有效至此次讀取後 30 分鐘。如果讀取的項目仍在 12 小時有效期間內,則取原到期時間與讀取後 30 分鐘兩者中較晚的時間。這不會重新起算 12 小時,也不會再次收取寫入費用。
最短有效期間決定哪些 Token 符合快取讀取費率的計費條件,但不保證每個請求都會重用已儲存的 KV 張量,或縮短延遲時間。
請使用 prompt_cache_retention。各模型支援的值有所不同:
in_memory:快取項目在閒置後通常仍可使用約 5 至 10 分鐘,最長可達 1 小時。24h:延長保留時,快取項目通常可使用約 30 分鐘,最長可保留 24 小時。
預設保留設定與零資料保留
提示詞快取可能會將加密的鍵值張量作為應用程式狀態,儲存在 GPU 本機儲存空間。若模型同時支援 in_memory 和 24h,預設值取決於組織的資料保留政策:
- 如果組織 未啟用 零資料保留,預設使用
24h。 - 如果組織 已啟用 零資料保留,預設使用
in_memory。
選擇設定值前,請先確認你的模型與組織可用的保留政策。
快取位置
快取狀態儲存在個別機器上。當流量超過每分鐘 15 個請求時,超出的流量可能會被轉送至其他機器。只有當請求送達的機器存有相符且尚未到期的項目,才能重用快取前綴。因此,將請求路由至正確的機器,對重用快取十分重要。
不同組織之間不共用快取,也無法跨區域處理邊界重用快取。
OpenAI 會自動處理路由。在同一組織與處理區域內,特定模型的請求路由取決於下列因素:
- 機器目前的負載與可用容量。
- OpenAI 隱藏內容之後最前面一段 Token 的雜湊值。如有工具定義,也會納入計算。用於計算雜湊的 Token 數量因模型而異。
- 請求提供的
prompt_cache_key。這個鍵可將不同請求群組的快取重用範圍分開,在 GPT-5.6 之前的模型上也有助於最佳化快取路由。
在 GPT-5.6 之前的模型上,對於共用可重用前綴的請求,請使用固定的 prompt_cache_key,以便將相關請求路由至同一快取。若群組流量較大,請讓每個鍵所涵蓋的所有前綴合計維持在每分鐘約 15 個請求。流量更高時,請使用固定、結果可重現的對應規則,將流量分配到多個鍵。相關請求應沿用同一個 prompt_cache_key,以便重用其快取。鍵會影響路由,但不會將請求綁定至特定機器,也不保證快取命中。
在 GPT-5.6 及後續模型上,OpenAI 會自動處理快取路由,無須使用快取鍵來最佳化快取。你可以使用不同的鍵,分別計算應用程式內各個客戶或使用者的快取用量與費用。
使用不同的鍵,有助於向各個客戶或使用者說明其快取 Token 用量與費用。舉例來說,不同的鍵有助於防止使用者探測其他使用者的快取命中情形。這類探測會提交候選提示詞,觀察是否命中快取,以推斷相符的內容先前是否曾被快取。請參閱使用快取鍵分開計算用量與費用。
模型差異一覽
| 行為 | 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 幫我最佳化提示詞快取
在多輪應用程式中,重用逐輪累積的對話記錄,能比只快取開頭的指示節省更多輸入 Token。請保留先前的訊息與工具結果,讓後續回合可以重用完整的共用前綴。
- 維持前綴不變。 將固定的開發者指示與共用參考資料放在開頭。如果其中包含時間戳記、個別使用者專屬內容或其他動態內容,請將這些內容放在結尾,或移至後續的對話訊息。
- 保留對話記錄。 將新訊息附加在後面,避免改寫先前的回合。產生摘要、壓縮或截斷上下文都可能改變前綴,使快取重用從頭開始。
- 調整推理強度,同時保留原有前綴。 在 GPT-6 模型上,可附加
configuration_update輸入項目,在兩次回應之間調整推理強度,同時維持請求層級的reasoning.effort不變。這樣即可保留原有前綴,供快取重用。範例與相容性限制請參閱在對話中途調整推理強度。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
"model": "gpt-6.1-sol",
"reasoning": { "effort": "low", "context": "all_turns" },
"text": { "verbosity": "medium" },
"prompt_cache_options": { "mode": "explicit" },
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "Stable instructions and shared reference material...",
"prompt_cache_breakpoint": { "mode": "explicit" }
}
]
},
{
"role": "developer",
"content": "Dynamic developer instructions, such as user-specific content and timestamps..."
},
{
"role": "user",
"content": "The user's current question..."
}
]
}在支援此功能的 GPT-6 及後續模型上,可附加 configuration_update 輸入項目,以便在對話期間調整推理強度,同時保留先前快取的前綴。請維持頂層 reasoning.effort 的原值,因為變更這項設定可能會改寫隱藏的系統指示。
後續回應的推理強度取決於最近一次對 reasoning.effort 的更新。將以下項目附加至 input,即可將推理強度切換為 high。
1
2
3
4{
"type": "configuration_update",
"reasoning": { "effort": "high" }
}如果應用程式在不同請求中需要不同工具,請調整可呼叫的工具,同時維持工具定義不變,以保留可重用的前綴。
- 維持工具一致。 保留工具定義、順序與結構描述。
- 在個別請求中停用工具。 將
tool_choice設為"none",無須移除工具定義。 - 只啟用指定的工具。 使用
allowed_tools限制可呼叫的工具,同時維持提供的tools清單不變。 - 按需載入工具。 搭配工具搜尋與
defer_loading: true,可減少多輪對話串在前幾個請求中用於工具定義的輸入 Token。搜尋到的工具會附加至上下文結尾,保留先前可重用的內容。 - 保留工具載入記錄。 在對話串中,使用開發者角色的
additional_tools輸入項目,依應用程式的邏輯新增工具。
在 GPT-5.6 及後續模型上,快取中斷點的位置由兩項設定控制。prompt_cache_options.mode 可選擇隱含模式或僅使用明確中斷點的模式,prompt_cache_breakpoint 則用於標記你選擇的邊界。
- 自動放置中斷點。 使用隱含快取,將中斷點放在最近一則符合條件的訊息結尾。對於會持續在既有上下文後附加內容的多輪對話串,這種方式很方便。
- 自行指定中斷點。 在固定內容的結尾加上明確標記。僅使用明確中斷點,可避免將會變動的後綴寫入快取而產生不必要的費用。
在 GPT-5.6 及後續模型上,可事先準備已知的上下文,縮短後續請求收到第一個 Token 的時間。例如,互動式應用程式可在啟動時、使用者提出第一個問題之前,先為共用指示、工具定義或參考資料預熱快取。
在 Responses API 請求中,將 prompt_cache_options.prewarm 設為 true,即可在不產生輸出的情況下準備提示詞快取。預熱完成後,以相同的提示詞前綴傳送實際請求,並省略 prewarm 或將其設為 false。
1
2
3
4
5
6
7
8
9
10
11
12{
"model": "gpt-6.1-sol",
"input": [
{
"role": "developer",
"content": "Your app's shared instructions and reference material..."
}
],
"prompt_cache_options": {
"prewarm": true
}
}1
2
3
4
5
6
7
8
9
10
11
12
13{
"model": "gpt-6.1-sol",
"input": [
{
"role": "developer",
"content": "Your app's shared instructions and reference material..."
},
{
"role": "user",
"content": "The user's question..."
}
]
}預熱請求寫入快取的 Token,會按所選有效期間的快取寫入費率計費。
在 GPT-5.6 及後續模型上,如果你想分別計算應用程式內各個客戶、使用者或工作區的快取用量與費用,可使用 prompt_cache_key。這樣較容易說明每個群組的快取 Token 用量與費用。這個鍵是選用的,這些模型無須使用快取鍵來最佳化快取。
- 決定如何分開計算快取用量與費用。 為每個需要單獨計算快取用量與費用的客戶或使用者指派不同的鍵。例如,使用
support:customer_123和support:customer_456,即使兩個客戶的請求包含相同前綴,仍會分開計算兩者的快取用量與費用。 - 在各群組內使用固定的鍵。 同一客戶的相關請求應重複使用相同的鍵。只有在工作階段或對話串需要單獨計算快取用量與費用時,才為其產生專屬鍵。
- 一致地套用快取鍵。 在客戶的各個請求中使用該客戶的鍵,以維持分開計算。這也有助於防止客戶探測其他客戶的快取命中情形。
在 GPT-5.6 之前的模型上,prompt_cache_key 對提升快取命中率十分重要。對於共用可重用前綴的請求,請使用固定的鍵,以便將請求路由至同一快取。若群組流量較大,請依照將流量分配到更多鍵的指引操作。
如果許多請求都重用相同的開發者指示與工具定義,但共用前綴未達模型的可快取長度下限,可考慮縮短前綴,或加入實用且固定的指示、範例或參考資料來延長前綴。請實際衡量重用快取所節省的費用能否抵銷額外的輸入 Token 與快取寫入費用,並確認評估結果與模型行為維持穩定。
下圖顯示可快取長度下限對成本的影響。短前綴若無法快取,費用可能比將前綴延長至可快取 Token 數下限還高。圖中採用 GPT-5.6 及後續模型的 30 分鐘快取寫入費率。
若只比較成本,設 M 為可快取長度下限,L<M 為原始前綴長度,r 為快取讀取費率倍數,w 為快取寫入費率倍數,N 為請求總數。假設延長後的前綴恰好有 M 個 Token,僅寫入一次,後續每個請求都會完整重用。以一個未快取輸入 Token 的費用為單位,保留原始前綴的成本為 N×L,延長前綴的成本則為 M[w+(N−1)r]。兩者成本相等時的原始前綴長度為:
Lbreak-even=M(r+Nw−r)當 L>Lbreak-even 時,延長前綴較划算。當 L<Lbreak-even 時,保留較短的前綴成本較低。兩者相等時,成本相同。以整數個 Token 計算,延長前綴開始比較划算的最短原始長度為 ⌊Lbreak-even⌋+1。反過來說,若將原本可快取的前綴縮短至低於 M,就無法使用快取。在相同假設下,縮短後的未快取前綴必須低於 Lbreak-even,成本才會比快取 M 個 Token 低。沒有一個適用於所有情況的「成本最高的提示詞長度」。兩種做法的成本在哪個長度相等,取決於重用次數與費率。
例如,採用一般快取讀取費率與 30 分鐘寫入費率,設 M=1,024、r=0.1、w=1.25,兩者成本相等時的長度為 102.4+N1,177.6 個 Token。如果共有 10 個請求,原始前綴至少有 221 個 Token 時,延長至 1,024 個 Token 就會更便宜。隨著重用次數增加,成本相等時的長度會趨近 102.4 個 Token。對於 103 個 Token 的前綴,請求總數至少要達到 1,963 次,延長前綴才會省錢。在上述假設下,102 個 Token 以下(含 102 個)的前綴無論重用幾次,延長都不會省錢。這項比較未計入效能、輸出 Token 與請求中不變的成本。若有額外的快取未命中或寫入,或模型費率不同,結果也會改變。
- 衡量實際快取效能。 追蹤
usage.input_tokens_details.cached_tokens、usage.input_tokens_details.cache_write_tokens、各有效期間的寫入 Token 數、輸入 Token 數、延遲與實際成本。若要追蹤 Token 快取命中率,可按使用者、工作區、日期或其他適合的方式分組,將各組的快取 Token 總數除以該組的輸入 Token 總數。 - 計算輸入成本。 使用
response.usage中的 Token 數量,以及模型的每百萬個 Token 價格計算。 - 使用提示詞快取儀表板。 在提示詞快取儀表板監控快取命中率。
對於支援 prompt_cache_options 的 Responses API 模型,input_tokens_details.cache_write_tokens_details 會將寫入量分為 ttl_30m_tokens 與 ttl_12h_tokens。兩者沒有重疊,加總即為 cache_write_tokens。即使其中一項為零,兩個欄位仍都會傳回。cached_tokens 只計算按讀取計費的 Token。所有按寫入計費的 Token 都不計入,其中也包括從 30 分鐘快取升級為 12 小時快取的 Token。
1
2
3
4
5
6
7
8
9
10
11
12
13{
"usage": {
"input_tokens": 12000,
"input_tokens_details": {
"cached_tokens": 4000,
"cache_write_tokens": 7000,
"cache_write_tokens_details": {
"ttl_30m_tokens": 3000,
"ttl_12h_tokens": 4000
}
}
}
}在這個用量範例中,一般輸入共有 1,000 個 Token,計算方式為 12000 - 4000 - 7000。若要計算輸入成本,請將一般輸入 Token 數乘以模型的輸入價格,將 cached_tokens 乘以快取輸入價格,將 ttl_30m_tokens 乘以輸入價格的 1.25 倍,再將 ttl_12h_tokens 乘以輸入價格的 2.5 倍。如果使用每百萬個 Token 的價格,請將上述金額加總後除以 1,000,000。計入兩種有效期間的寫入量後,不要再加上 cache_write_tokens。
例如,若每百萬個 Token 的輸入價格為 1 美元、快取輸入價格為 0.10 美元,此範例的輸入費用為 (1000 + 4000 × 0.1 + 3000 × 1.25 + 4000 × 2.5) / 1000000 = $0.01515。計算時請使用模型的實際費率,包括其快取輸入費率。
以下輔助函式對所有寫入使用同一個快取寫入費率倍數。如果所有寫入的有效期間都是 30 分鐘,請使用 1.25。如果都是 12 小時,請使用 2.5。如果同一請求使用兩種有效期間,請依照上述方式分別計算各自的寫入費用。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21function calculateInputCost(
usage: {
input_tokens: number;
input_tokens_details: { cached_tokens: number; cache_write_tokens: number };
},
inputPricePerMillion: number,
cacheInputMultiplier = 0.1,
cacheWriteMultiplier = 1.25
) {
const inputTokens = usage.input_tokens;
const cachedTokens = usage.input_tokens_details.cached_tokens;
const cacheWriteTokens = usage.input_tokens_details.cache_write_tokens;
const ordinaryInputTokens = inputTokens - cachedTokens - cacheWriteTokens;
const weightedInputTokens =
ordinaryInputTokens +
cachedTokens * cacheInputMultiplier +
cacheWriteTokens * cacheWriteMultiplier;
const inputCost = (weightedInputTokens * inputPricePerMillion) / 1_000_000;
return inputCost;
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai.types.responses import ResponseUsage
def calculate_input_cost(
usage: ResponseUsage,
input_price_per_million: float,
cache_input_multiplier: float = 0.1,
cache_write_multiplier: float = 1.25,
) -> float:
input_tokens = usage.input_tokens
cached_tokens = usage.input_tokens_details.cached_tokens
cache_write_tokens = usage.input_tokens_details.cache_write_tokens
ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens
weighted_input_tokens = (
ordinary_input_tokens
+ cached_tokens * cache_input_multiplier
+ cache_write_tokens * cache_write_multiplier
)
input_cost = weighted_input_tokens * input_price_per_million / 1_000_000
return input_cost1
2
3
4
5func calculateInputCost(usage responses.ResponseUsage, pricePerMillion, cacheInputMultiplier, cacheWriteMultiplier float64) float64 {
ordinary := usage.InputTokens - usage.InputTokensDetails.CachedTokens - usage.InputTokensDetails.CacheWriteTokens
weighted := float64(ordinary) + float64(usage.InputTokensDetails.CachedTokens)*cacheInputMultiplier + float64(usage.InputTokensDetails.CacheWriteTokens)*cacheWriteMultiplier
return weighted * pricePerMillion / 1_000_000
}1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.models.responses.ResponseUsage;
static double calculateInputCost(
ResponseUsage usage,
double pricePerMillion,
double cacheInputMultiplier,
double cacheWriteMultiplier) {
long cached = usage.inputTokensDetails().cachedTokens();
long written = usage.inputTokensDetails().cacheWriteTokens();
long ordinary = usage.inputTokens() - cached - written;
return (ordinary + cached * cacheInputMultiplier + written * cacheWriteMultiplier)
* pricePerMillion
/ 1_000_000;
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17def calculate_input_cost(
usage,
input_price_per_million,
cache_input_multiplier = 0.1,
cache_write_multiplier = 1.25
)
input_tokens = usage.input_tokens
details = usage.input_tokens_details
cached_tokens = details.cached_tokens
cache_write_tokens = details.cache_write_tokens
ordinary_input_tokens = input_tokens - cached_tokens - cache_write_tokens
weighted_input_tokens = ordinary_input_tokens +
(cached_tokens * cache_input_multiplier) +
(cache_write_tokens * cache_write_multiplier)
(weighted_input_tokens * input_price_per_million) / 1_000_000
end- 保留既有的固定前綴。
- 如果使用
prompt_cache_key,請保留現有值,以繼續分別計算各個客戶或使用者的快取用量與費用。 - 將
prompt_cache_retention替換為prompt_cache_options.ttl。 - 確認可重用的前綴達到模型的可快取長度下限。
- 如果預設中斷點涵蓋的內容會因請求而變動,請在固定前綴之後新增明確中斷點。
- 如果後面的內容不值得寫入快取,請使用
prompt_cache_options.mode: "explicit"。 - 遷移前後,請比較
cached_tokens、cache_write_tokens、延遲與總成本。
範例
以下範例適用於 GPT-5.6 及後續模型。
假設你使用 LLM 在單輪請求中評分,判斷一段已結束的對話是否有跡象顯示使用者對與聊天機器人的互動感到滿意。每個請求都使用同一套評分規準與附有標註的少樣本範例,評估不同的互動。
- 保留前綴: 將固定的評分規準與範例放在開頭。選用有助於校準評分的資料,並刻意讓兩者的總長度略高於模型的可快取長度下限。將待評估的互動放在最後。
- 快取模式與中斷點: 啟用僅使用明確中斷點的快取模式,在固定的評分規準與範例之後設定中斷點。將待評估的使用者與聊天機器人對話放在該中斷點之後,就不會將這段不太可能重用的內容寫入快取,也不會產生快取寫入費用。
有個採用上述做法的部署案例回報,Token 快取命中率約為 70%。這只是可能的結果之一,實際可達到的命中率上限取決於你的上下文與應用程式使用情況。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
"model": "gpt-6.1-sol",
"reasoning": { "effort": "medium", "context": "all_turns" },
"text": { "verbosity": "low" },
"prompt_cache_options": { "mode": "explicit" },
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "Judge whether the completed interaction provides evidence that the user is satisfied. Return true or false. Full grading rubric and labeled few-shot examples...",
"prompt_cache_breakpoint": { "mode": "explicit" }
}
]
},
{
"role": "user",
"content": "Completed interaction to evaluate..."
}
]
}假設有個多輪智慧體使用很長的共用開發者指示,並頻繁呼叫工具。使用者通常會同時與智慧體進行多個工作階段,也經常從對話串建立分支。
- 保留前綴:每一輪都在原有上下文之後附加新訊息、工具呼叫與結果,不改寫先前的上下文,因此可重用的前綴會逐輪增長。
- 選用的提示詞快取鍵: 本例使用
agent_123_v1:user_456單獨計算使用者 456 的快取用量與費用,方便說明該使用者的快取 Token 用量與帳單。這也有助於防止使用者探測其他使用者的快取命中情形。該使用者與智慧體互動的各個工作階段及分支都使用同一個鍵。如果應用程式無須分開計算,可以省略這個鍵。 - 隱含快取模式: 啟用隱含快取,讓最近一則符合條件的使用者訊息或工具訊息的結尾成為中斷點。
- 明確中斷點: 在每個工具結果後新增中斷點,以保留先前可重用的前綴,提高建立分支時的快取效率。
有個採用上述做法的部署案例回報,Token 快取命中率超過 90%。這只是可能的結果之一,實際可達到的命中率上限取決於你的上下文與應用程式使用情況。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41{
"model": "gpt-6.1-sol",
"reasoning": { "effort": "medium", "context": "all_turns" },
"text": { "verbosity": "medium" },
"prompt_cache_key": "agent_123_v1:user_456",
"prompt_cache_options": { "mode": "implicit" },
"tools": [
{
"type": "function",
"name": "function_name",
"description": "Function description",
"parameters": { "...": "..." }
}
],
"input": [
{
"role": "developer",
"content": "Stable developer instructions and reference material..."
},
{ "role": "user", "content": "Can you do...?" },
{
"type": "function_call",
"call_id": "call_123",
"name": "function_name",
"arguments": "..."
},
{
"type": "function_call_output",
"call_id": "call_123",
"output": [
{
"type": "input_text",
"text": "Tool result...",
"prompt_cache_breakpoint": { "mode": "explicit" }
}
]
},
{ "role": "assistant", "content": "Assistant response..." },
{ "role": "user", "content": "Can you also do...?" }
]
}常見陷阱
從較早的模型遷移至 GPT-5.6 或後續模型時,特別容易遇到這種情況,因為隱含快取的運作方式有所改變。如果多個請求共用很長的前綴,但後綴各不相同,僅以隱含模式快取第一個完整請求,並不會讓其中較短的共用前綴可以重用。
假設每個請求都以固定的開發者訊息開頭,後接會變動的使用者訊息。這個請求會一路寫入快取,直到動態內容的結尾。下一個請求如果變更動態內容,就無法與已快取的較長前綴相符,而固定內容之後也沒有獨立的中斷點。
1
2
3
4
5
6
7
8
9
10{
"model": "gpt-6.1-sol",
"reasoning": { "effort": "medium", "context": "all_turns" },
"text": { "verbosity": "low" },
"prompt_cache_options": { "mode": "implicit" },
"input": [
{ "role": "developer", "content": "Static content..." },
{ "role": "user", "content": "Dynamic content..." }
]
}解決方式是在兩個請求中,都於固定內容之後放置明確中斷點。第一個請求會將可重用的前綴寫入快取,下一個請求即使變更動態內容,也能重用該前綴。本例僅使用明確中斷點,避免將動態內容寫入快取。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
"model": "gpt-6.1-sol",
"reasoning": { "effort": "medium", "context": "all_turns" },
"text": { "verbosity": "low" },
"prompt_cache_options": { "mode": "explicit" },
"input": [
{
"role": "developer",
"content": [{
"type": "input_text",
"text": "Static content...",
"prompt_cache_breakpoint": { "mode": "explicit" }
}]
},
{ "role": "user", "content": "Dynamic content..." }
]
}假設請求 1 使用隱含模式,將截至使用者訊息結尾的前綴寫入快取。後續的請求 2 保留該前綴,但切換為 prompt_cache_options.mode: "explicit"。如如何比對前綴所述,請求 2 只會檢查自身輸入中的明確中斷點。因此,除非請求 2 的某個明確中斷點與請求 1 的快取前綴結尾相符,否則無法重用請求 1 以隱含模式儲存的前綴。
▼ = breakpoint
- Request 1: implicit mode
[Developer message][User message] ▼
- Request 2: explicit-only mode. Does not hit cache.
[Developer message][User message][Follow-up] ▼若要重用請求 1 的隱含前綴,請在請求 2 相符的內容區塊邊界放置明確中斷點,或繼續使用隱含模式,讓先前符合條件的訊息結尾仍列入查找範圍。
即使兩個請求都使用隱含模式,只保留相同的開頭 Token 有時仍然不夠。假設請求 1 的最後一則使用者訊息包含 Content A,後續的請求 2 將同一則訊息延長為 Content A + Content B。原本位於 Content A 之後的結尾,現在落在訊息中間。如如何比對前綴所述,如果沒有在該邊界放置明確中斷點,請求 2 就無法重用先前儲存至該處的前綴。
▼ = breakpoint
- Request 1: implicit mode
[Developer message][User message: Content A] ▼
- Request 2: implicit mode. Cannot reuse the prefix through Content A.
[Developer message][User message: Content A + Content B] ▼如果對話結構允許,請保留原始訊息,將新內容另以一則訊息附加在後。否則,請將可重用的文字保留在獨立的內容區塊中,並在兩個請求中都於該區塊之後放置明確中斷點。
在隱含模式下,開頭一組連續開發者訊息之後出現的開發者訊息,其結尾不會自動成為快取查找邊界。請在可重用的開發者訊息結尾新增明確中斷點,並在後續請求中保留這個中斷點,讓 OpenAI 可以檢查是否有相符的快取前綴。
在某個模型上符合快取條件的前綴,對另一個模型而言可能太短。請查看模型比較,並使用實際採用的模型與設定來測量可重用的前綴。更換模型時應重新檢查,不能假設原模型的門檻仍然適用。
壓縮會將先前的對話上下文替換為較短的表示形式。這可能改變前綴,因此即使在邏輯上仍是同一段對話,壓縮後的第一個請求也可能只能重用較少的既有快取。
請盡可能維持可重用的指示與參考資料不變,再讓後續回合接續壓縮後的上下文。請比較壓縮前後的總輸入成本。即使快取命中率下降,減少輸入 Token 仍可能節省費用。
常見問題
不會。提示詞快取不會改變模型產生輸出 Token 的方式。模型會使用快取的前綴產生新的回應,因此即使請求完全相同,也不保證輸出相同。
不可以。目前無法手動清除快取。快取項目會依模型的快取有效期間與保留設定到期。
會。已快取的輸入 Token 仍會計入每分鐘 Token 數上限。提示詞快取不會改變速率限制的計算方式。
資料保留
所有提示詞快取功能都與零資料保留(ZDR)相容。
提示詞快取儲存的是鍵值(KV)張量,而非原始提示詞文字。這些張量可能會以加密的應用程式狀態儲存在 GPU 本機儲存空間,最長保留 24 小時。各模型的快取有效期間與有效期限更新方式,請參閱快取有效期間。
不同組織之間不共用快取,也無法跨區域處理邊界重用快取。各項 API 功能的資料處理方式與 ZDR 適用條件,請參閱你的資料。