載入中

實戰中的提示快取

第 45 課7 分鐘
載入中

提示快取是一項強大的優化功能,當您重複向 Claude 發送相同內容時,能讓您的 API 請求更快速且更經濟。讓我們來探討如何在您的應用程式中有效地實作它。

提示快取的運作方式

當您啟用提示快取時,第一個請求會將內容寫入快取,預設存活時間為 5 分鐘,每次使用快取內容時,該時間窗口會免費刷新。如果您需要更長的時間窗口,可以選擇以額外費用啟用 1 小時的快取持續時間。後續請求會從此快取讀取,而不必重新處理相同的內容。當您發送以下內容時,這特別有價值:

  • 大型系統提示(例如一個 6K token 的程式編碼助手提示)
  • 複雜的工具架構(例如多個工具的詳細定義)
  • 重複的訊息內容

關鍵在於,快取只有在您重複發送相同內容時才有幫助——但在許多應用程式中,這種情況發生得極為頻繁。

設定工具架構快取

要快取您的工具架構,您需要在工具列表的最後一個工具上新增一個快取控制欄位。以下是正確的做法,不會修改您原始的工具定義:

python
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"],但採用複製的方式可以避免您日後重新排序工具時出現問題。

系統提示快取

對於系統提示,您需要將其結構化為帶有快取控制的文字區塊:

python
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

快取極度敏感——即使只是在您的工具或系統提示中變更單一字元,也會使該組件的整個快取失效。

快取順序與斷點

您可以在單一請求中設定多個快取斷點。順序很重要:

  1. 工具(如果有提供)
  2. 系統提示(如果有提供)
  3. 訊息

如果您變更了系統提示,但保留相同的工具,您會看到部分快取讀取(針對工具)和快取寫入(針對新的系統提示)。只有當工具本身達到最小長度時,您才會得到那個部分讀取,因為如果快取斷點到該點為止的內容低於最小長度,則不會寫入任何內容。這種細粒度的快取機制意味著您只需為實際變更的部分付費處理。

實務考量

在以下情況下,提示快取最為有效:

  • 跨請求保持一致的工具架構
  • 穩定的系統提示
  • 在相似情境下發出多個請求的應用程式

請記住,預設快取持續 5 分鐘(每次使用時刷新),並可透過額外費用選擇 1 小時的選項,因此它是為使用 API 相對頻繁的應用程式所設計,而非用於長期儲存。