提示詞快取

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

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

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

​

提示詞快取的工作原理

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

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

這特別適用於：

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

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

​

定價

提示詞快取引入了新的定價結構。下表顯示了每個支持模型的每個令牌的價格：

注意：

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

​

如何實現提示詞快取

​

支持的模型

提示詞快取目前支持：

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

​

構建您的提示詞

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

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

使用 cache_control 參數，您可以定義最多 4 個快取斷點，允許您分別快取不同的可重用部分。

​

快取限制

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

• Claude 3.5 Sonnet 和 Claude 3 Opus 為 1024 個令牌
• Claude 3.5 Haiku 和 Claude 3 Haiku 為 2048 個令牌

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

快取的生命週期為 5 分鐘（TTL）。目前，“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 和圖片使用在調用之間保持一致
• 驗證您至少快取了最小數量的令牌

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

​

快取存儲和共享

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

• 精確匹配：快取命中需要 100% 相同的提示詞段，包括標記有快取控制的區塊之前和包括該區塊的所有文本和圖片。在快取讀取和創建期間必須使用相同的快取控制標記相同的區塊。

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

​

提示詞快取示例

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

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

​

常見問題

client.beta.promptCaching.messages.create(...)

client.messages.create(...)