提示快取是一項強大的優化功能,當您重複向 Claude 發送相同內容時,能讓您的 API 請求更快速且更經濟。讓我們來探討如何在您的應用程式中有效地實作它。
提示快取的運作方式
當您啟用提示快取時,第一個請求會將內容寫入快取,預設存活時間為 5 分鐘,每次使用快取內容時,該時間窗口會免費刷新。如果您需要更長的時間窗口,可以選擇以額外費用啟用 1 小時的快取持續時間。後續請求會從此快取讀取,而不必重新處理相同的內容。當您發送以下內容時,這特別有價值:
- 大型系統提示(例如一個 6K token 的程式編碼助手提示)
- 複雜的工具架構(例如多個工具的詳細定義)
- 重複的訊息內容
關鍵在於,快取只有在您重複發送相同內容時才有幫助——但在許多應用程式中,這種情況發生得極為頻繁。
設定工具架構快取
要快取您的工具架構,您需要在工具列表的最後一個工具上新增一個快取控制欄位。以下是正確的做法,不會修改您原始的工具定義:
if tools:
tools_clone = tools.copy()
last_tool = tools_clone[-1].copy()
last_tool["cache_control"] = {"type": "ephemeral"}
tools_clone[-1] = last_tool
params["tools"] = tools_clone此方法會在新增快取控制欄位之前,建立工具列表和最後一個工具架構的副本。雖然您可以直接修改 tools[-1]["cache_control"],但採用複製的方式可以避免您日後重新排序工具時出現問題。
系統提示快取
對於系統提示,您需要將其結構化為帶有快取控制的文字區塊:
if system:
params["system"] = [
{
"type": "text",
"text": system,
"cache_control": {"type": "ephemeral"}
}
]這會將您的系統提示從簡單的字串轉換為支援快取的結構化格式。
了解快取行為
當您在啟用快取的情況下執行請求時,您會在回應中看到不同的使用模式:
- 第一個請求:
cache_creation_input_tokens顯示寫入了多少 token——Claude 寫入快取 - 後續請求:
cache_read_input_tokens顯示讀回了相同數量的 token——Claude 從快取讀取 - 內容變更時:會出現新的快取建立 token
快取極度敏感——即使只是在您的工具或系統提示中變更單一字元,也會使該組件的整個快取失效。
快取順序與斷點
您可以在單一請求中設定多個快取斷點。順序很重要:
- 工具(如果有提供)
- 系統提示(如果有提供)
- 訊息
如果您變更了系統提示,但保留相同的工具,您會看到部分快取讀取(針對工具)和快取寫入(針對新的系統提示)。只有當工具本身達到最小長度時,您才會得到那個部分讀取,因為如果快取斷點到該點為止的內容低於最小長度,則不會寫入任何內容。這種細粒度的快取機制意味著您只需為實際變更的部分付費處理。
實務考量
在以下情況下,提示快取最為有效:
- 跨請求保持一致的工具架構
- 穩定的系統提示
- 在相似情境下發出多個請求的應用程式
請記住,預設快取持續 5 分鐘(每次使用時刷新),並可透過額外費用選擇 1 小時的選項,因此它是為使用 API 相對頻繁的應用程式所設計,而非用於長期儲存。