提示詞快取是一個強大的功能，它可以讓您從提示詞中的特定前綴部分繼續執行，從而優化您的 API 使用。這種方法可以顯著減少重複任務或具有一致元素的提示詞的處理時間和成本。

以下是使用 Messages API 實現提示詞快取的示例，使用 cache_control 區塊：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input
JSON
{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

在這個示例中，《傲慢與偏見》的全文使用 cache_control 參數進行快取。這使得這個大型文本可以在多個 API 調用中重複使用，而無需每次都重新處理。只需更改用戶訊息，就可以詢問關於這本書的各種問題，同時利用快取的內容，從而實現更快的回應和更高的效率。

​
提示詞快取的工作原理

當您發送啟用提示詞快取的請求時：

  1. 系統會檢查是否已經從最近的查詢中快取了指定快取斷點之前的提示詞前綴。
  2. 如果找到，則使用快取版本，減少處理時間和成本。
  3. 否則，它會處理完整的提示詞，並在開始回應時快取前綴。

這特別適用於：

  • 包含許多示例的提示詞
  • 大量的上下文或背景信息
  • 具有一致指令的重複任務
  • 長時間的多輪對話

快取的最短生命週期為 5 分鐘，每次使用快取內容時都會刷新。

提示詞快取會快取完整的前綴

提示詞快取會參考整個提示詞 - tools、system 和 messages（按此順序）直到並包括標記有 cache_control 的區塊。

​
定價

提示詞快取引入了新的定價結構。下表顯示了每個支援模型的每百萬代幣的價格：

ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.7$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Sonnet 3.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
Claude Opus 3$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
Claude Haiku 3$0.25 / MTok$0.30 / MTok$0.50 / MTok$0.03 / MTok$1.25 / MTok

注意：

  • 快取寫入代幣比基本輸入代幣貴 25%
  • 快取讀取代幣比基本輸入代幣便宜 90%
  • 常規輸入和輸出代幣按標準費率計費

​
如何實現提示詞快取

​
支援的模型

提示詞快取目前支援：

  • Claude 3.7 Sonnet
  • Claude 3.5 Sonnet
  • Claude 3.5 Haiku
  • Claude 3 Haiku
  • Claude 3 Opus

​
構建您的提示詞

將靜態內容（工具定義、系統指令、上下文、示例）放在提示詞的開頭。使用 cache_control 參數標記要快取的可重用內容的結尾。

快取前綴按以下順序創建：tools、system，然後是 messages。

使用 cache_control 參數，您可以定義最多 4 個快取斷點，允許您分別快取不同的可重用部分。對於每個斷點，系統將自動檢查先前位置的快取命中，如果找到，則使用最長的匹配前綴。

​
快取限制

最小可快取提示詞長度為：

  • Claude 3.7 Sonnet、Claude 3.5 Sonnet 和 Claude 3 Opus 為 1024 個代幣
  • Claude 3.5 Haiku 和 Claude 3 Haiku 為 2048 個代幣

即使標記了 cache_control，較短的提示詞也無法快取。任何請求快取少於此數量代幣的請求都將在不快取的情況下處理。要查看提示詞是否已快取，請參見回應使用欄位。

對於並發請求，請注意快取條目只有在第一個回應開始後才可用。如果您需要並行請求的快取命中，請等待第一個回應後再發送後續請求。

快取的最短生存時間（TTL）為 5 分鐘。目前，“ephemeral” 是唯一支援的快取類型，對應於這個最短 5 分鐘的生命週期。

​
可以快取什麼

請求中的大多數區塊都可以使用 cache_control 進行快取。這包括：

  • 工具：tools 陣列中的工具定義
  • 系統訊息：system 陣列中的內容區塊
  • 文本訊息：messages.content 陣列中的內容區塊，包括用戶和助手的對話
  • 圖片和文檔：用戶對話中 messages.content 陣列中的內容區塊
  • 工具使用和工具結果：用戶和助手對話中 messages.content 陣列中的內容區塊

這些元素中的每一個都可以用 cache_control 標記，以啟用該部分請求的快取。

​
不能快取什麼

雖然大多數請求區塊都可以快取，但也有一些例外：

  • 思考區塊不能快取，因為這些會被剔除並且不計入您的代幣輸入。
  • 子內容區塊（如引用）不能快取。相反，請快取頂層區塊。
  • 空文本區塊不能快取。

​
追蹤快取性能

使用這些 API 回應欄位監控快取性能，這些欄位位於回應中的 usage 內（或如果串流則在 message_start 事件中）：

  • cache_creation_input_tokens：創建新條目時寫入快取的代幣數量。
  • cache_read_input_tokens：從快取中檢索到的此請求的代幣數量。
  • input_tokens：未從快取讀取或用於創建快取的輸入代幣數量。

​
有效快取的最佳實踐

要優化提示詞快取性能：

  • 快取穩定的、可重用的內容，如系統指令、背景信息、大型上下文或頻繁的工具定義。
  • 將快取內容放在提示詞的開頭以獲得最佳性能。
  • 策略性地使用快取斷點來分隔不同的可快取前綴部分。
  • 定期分析快取命中率並根據需要調整您的策略。

​
針對不同使用場景進行優化

根據您的場景調整提示詞快取策略：

  • 對話代理：減少延長對話的成本和延遲，特別是那些具有長指令或上傳文檔的對話。
  • 編碼助手：通過在提示詞中保持相關部分或代碼庫的摘要版本來改進自動完成和代碼庫問答。
  • 大型文檔處理：在提示詞中包含完整的長篇材料（包括圖片），而不會增加回應延遲。
  • 詳細指令集：共享廣泛的指令、程序和示例列表以微調 Claude 的回應。開發人員通常在提示詞中包含一兩個示例，但使用提示詞快取，您可以通過包含 20+ 個高質量答案的多樣化示例來獲得更好的性能。
  • 代理工具使用：增強涉及多個工具調用和迭代代碼更改的場景的性能，其中每個步驟通常需要新的 API 調用。
  • 與書籍、論文、文檔、播客文字稿和其他長篇內容對話：通過將整個文檔嵌入到提示詞中，並讓用戶向其提問，使任何知識庫變得生動起來。

​
常見問題的故障排除

如果遇到意外行為：

  • 確保快取部分在調用之間完全相同，並在相同位置標記了 cache_control
  • 檢查調用是否在 5 分鐘的快取生命週期內進行
  • 驗證 tool_choice 和圖片使用在調用之間保持一致
  • 驗證您至少快取了最小數量的代幣
  • 雖然系統會嘗試在快取斷點之前使用先前快取的內容，但您可以使用額外的 cache_control 參數來保證對提示詞先前部分的快取查找，這對於具有很長內容區塊列表的查詢可能很有用

請注意，更改 tool_choice 或提示詞中任何位置的圖片存在/不存在都會使快取失效，需要創建新的快取條目。

​
快取存儲和共享

  • 組織隔離：快取在組織之間是隔離的。不同的組織永遠不會共享快取，即使它們使用相同的提示詞。

  • 精確匹配：快取命中需要 100% 相同的提示詞段，包括標記有快取控制的區塊之前的所有文本和圖片。

  • 輸出代幣生成：提示詞快取對輸出代幣生成沒有影響。您收到的回應將與不使用提示詞快取時完全相同。

​
提示詞快取示例

為了幫助您開始使用提示詞快取，我們準備了一個提示詞快取食譜，其中包含詳細的示例和最佳實踐。

以下，我們包含了幾個展示各種提示詞快取模式的代碼片段。這些示例演示了如何在不同場景中實現快取，幫助您理解這個功能的實際應用：

​
常見問題