提示詞快取

提示詞快取透過允許從提示詞中的特定前綴恢復來優化您的 API 使用。這顯著降低了重複任務或具有一致元素的提示詞的處理時間和成本。

啟用提示詞快取有兩種方式：

• 自動快取：在請求的頂層新增單一 cache_control 欄位。系統會自動將快取斷點套用至最後一個可快取的區塊，並隨著對話增長而向前移動。最適合需要自動快取不斷增長的訊息歷史的多輪對話。
• 明確快取斷點：直接在個別內容區塊上放置 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-opus-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

使用自動快取時，系統會快取所有內容，直到並包含最後一個可快取的區塊。在後續具有相同前綴的請求中，快取的內容會自動被重複使用。

提示詞快取的運作方式

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

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

這對以下情況特別有用：

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

預設情況下，快取的有效期為 5 分鐘。每次使用快取內容時，快取都會免費刷新。

定價

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

支援的模型

提示詞快取（自動和明確）目前支援：

• Claude Opus 4.6
• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.6
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7（已棄用）
• Claude Haiku 4.5
• Claude Haiku 3.5（已棄用）
• Claude Haiku 3

自動快取

自動快取是啟用提示詞快取最簡單的方式。不需要在個別內容區塊上放置 cache_control，只需在請求主體的頂層新增單一 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-opus-4-6",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are a helpful assistant that remembers our conversation.",
    "messages": [
      {"role": "user", "content": "My name is Alex. I work on machine learning."},
      {"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
      {"role": "user", "content": "What did I say I work on?"}
    ]
  }'

自動快取在多輪對話中的運作方式

使用自動快取時，快取點會隨著對話增長自動向前移動。每個新請求都會快取直到最後一個可快取區塊的所有內容，而之前的內容則從快取中讀取。

快取斷點會自動移動到每個請求中最後一個可快取的區塊，因此您不需要隨著對話增長而更新任何 cache_control 標記。

TTL 支援

預設情況下，自動快取使用 5 分鐘的 TTL。您可以以基本輸入 token 價格的 2 倍指定 1 小時的 TTL：

"cache_control": {"type": "ephemeral", "ttl": "1h"}

與區塊級快取結合使用

自動快取與明確快取斷點相容。當一起使用時，自動快取斷點會使用 4 個可用斷點槽位中的一個。

這讓您可以結合兩種方式。例如，使用明確斷點獨立快取系統提示詞和工具，同時自動快取處理對話：

{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [...]
}

保持不變的部分

自動快取使用相同的底層快取基礎設施。定價、最小 token 閾值、上下文排序要求和 20 個區塊的回溯視窗都與明確斷點相同。

邊緣情況

• 如果最後一個區塊已有具有相同 TTL 的明確 cache_control，自動快取為無操作。
• 如果最後一個區塊有具有不同 TTL 的明確 cache_control，API 會返回 400 錯誤。
• 如果已存在 4 個明確的區塊級斷點，API 會返回 400 錯誤（自動快取沒有剩餘槽位）。
• 如果最後一個區塊不符合自動快取斷點目標的資格，系統會靜默地向後查找最近的符合資格的區塊。如果找不到，則跳過快取。

明確快取斷點

為了更精細地控制快取，您可以直接在個別內容區塊上放置 cache_control。當您需要以不同頻率快取不同部分，或需要精細控制確切快取的內容時，這非常有用。

結構化您的提示詞

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

快取前綴按以下順序建立：tools、system，然後是 messages。此順序形成一個層次結構，每個層級都建立在前一個層級之上。

自動前綴檢查的運作方式

您可以在靜態內容的末尾只使用一個快取斷點，系統會自動找到最長的匹配快取區塊序列。了解其運作方式有助於您優化快取策略。

三個核心原則：

1. 快取鍵是累積的：當您使用 cache_control 明確快取一個區塊時，快取雜湊鍵是透過依序雜湊對話中所有先前的區塊來生成的。這意味著每個區塊的快取取決於其之前的所有內容。

2. 向後順序檢查：系統透過從您的明確斷點向後工作，以相反順序檢查每個先前的區塊來檢查快取命中。這確保您獲得最長可能的快取命中。

3. 20 個區塊的回溯視窗：系統只檢查每個明確 cache_control 斷點之前最多 20 個區塊。在沒有匹配的情況下檢查 20 個區塊後，它停止檢查並移動到下一個明確斷點（如果有的話）。

範例：了解回溯視窗

考慮一個有 30 個內容區塊的對話，您只在區塊 30 上設置 cache_control：

• 如果您發送區塊 31 且沒有更改先前的區塊：系統檢查區塊 30（匹配！）。您在區塊 30 獲得快取命中，只有區塊 31 需要處理。

• 如果您修改區塊 25 並發送區塊 31：系統從區塊 30 → 29 → 28... → 25（不匹配）→ 24（匹配！）向後檢查。由於區塊 24 沒有更改，您在區塊 24 獲得快取命中，只有區塊 25-30 需要重新處理。

• 如果您修改區塊 5 並發送區塊 31：系統從區塊 30 → 29 → 28... → 11（第 20 次檢查）向後檢查。在 20 次檢查後沒有找到匹配，它停止查找。由於區塊 5 超出了 20 個區塊的視窗，不會發生快取命中，所有區塊都需要重新處理。但是，如果您在區塊 5 上設置了明確的 cache_control 斷點，系統將繼續從該斷點檢查：區塊 5（不匹配）→ 區塊 4（匹配！）。這允許在區塊 4 獲得快取命中，說明了為什麼您應該在可編輯內容之前放置斷點。

關鍵要點：始終在對話末尾設置明確的快取斷點，以最大化快取命中的機會。此外，在可能可編輯的內容區塊之前設置斷點，以確保這些部分可以獨立快取。

何時使用多個斷點

如果您想要以下情況，可以定義最多 4 個快取斷點：

• 快取以不同頻率更改的不同部分（例如，工具很少更改，但上下文每天更新）
• 更精細地控制確切快取的內容
• 確保在最終斷點之前超過 20 個區塊的內容可以被快取
• 在可編輯內容之前放置斷點，以保證即使在 20 個區塊視窗之外發生更改時也能獲得快取命中

了解快取斷點成本

快取斷點本身不會增加任何成本。 您只需為以下內容付費：

• 快取寫入：當新內容寫入快取時（5 分鐘 TTL 比基本輸入 token 多 25%）
• 快取讀取：當使用快取內容時（基本輸入 token 價格的 10%）
• 常規輸入 token：對於任何未快取的內容

添加更多 cache_control 斷點不會增加您的成本——您仍然根據實際快取和讀取的內容支付相同的金額。斷點只是讓您控制哪些部分可以獨立快取。

快取策略與注意事項

快取限制

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

• Claude Opus 4.6、Claude Opus 4.5 為 4096 個 token
• Claude Sonnet 4.6 為 2048 個 token
• Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4 和 Claude Sonnet 3.7（已棄用）為 1024 個 token
• Claude Haiku 4.5 為 4096 個 token
• Claude Haiku 3.5（已棄用）和 Claude Haiku 3 為 2048 個 token

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

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

目前，"ephemeral" 是唯一支援的快取類型，預設有效期為 5 分鐘。

可以快取的內容

請求中的大多數區塊都可以被快取。這包括：

• 工具：tools 陣列中的工具定義
• 系統訊息：system 陣列中的內容區塊
• 文字訊息：messages.content 陣列中的內容區塊，適用於使用者和助手輪次
• 圖片和文件：messages.content 陣列中的內容區塊，在使用者輪次中
• 工具使用和工具結果：messages.content 陣列中的內容區塊，在使用者和助手輪次中

這些元素中的每一個都可以被快取，無論是自動快取還是通過標記 cache_control。

無法快取的內容

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

• 思考區塊無法直接使用 cache_control 快取。但是，當思考區塊出現在先前的助手輪次中時，它們可以與其他內容一起被快取。以這種方式快取時，從快取讀取時它們確實計為輸入 token。

• 子內容區塊（如引用）本身無法直接快取。請改為快取頂層區塊。

  在引用的情況下，作為引用來源材料的頂層文件內容區塊可以被快取。這允許您通過快取引用將參考的文件來有效地使用帶有引用的提示詞快取。

• 空文字區塊無法被快取。

使快取失效的因素

對快取內容的修改可能會使部分或全部快取失效。

如結構化您的提示詞中所述，快取遵循層次結構：tools → system → messages。每個層級的更改都會使該層級及所有後續層級失效。

下表顯示了不同類型的更改會使快取的哪些部分失效。✘ 表示快取失效，✓ 表示快取保持有效。

追蹤快取效能

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

• cache_creation_input_tokens：建立新條目時寫入快取的 token 數量。
• cache_read_input_tokens：此請求從快取中檢索的 token 數量。
• input_tokens：未從快取讀取或用於建立快取的輸入 token 數量（即最後一個快取斷點之後的 token）。

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

使用思考區塊進行快取

當使用擴展思考和提示詞快取時，思考區塊有特殊行為：

與其他內容一起自動快取：雖然思考區塊無法明確標記 cache_control，但當您使用工具結果進行後續 API 呼叫時，它們會作為請求內容的一部分被快取。這通常在工具使用期間發生，當您傳回思考區塊以繼續對話時。

輸入 token 計數：當從快取讀取思考區塊時，它們在您的使用指標中計為輸入 token。這對於成本計算和 token 預算很重要。

快取失效模式：

• 當只提供工具結果作為使用者訊息時，快取保持有效
• 當添加非工具結果的使用者內容時，快取失效，導致所有先前的思考區塊被剝離
• 即使沒有明確的 cache_control 標記，也會發生此快取行為

更多關於快取失效的詳情，請參閱使快取失效的因素。

工具使用範例：

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

當包含非工具結果的使用者區塊時，它指定了一個新的助手循環，所有先前的思考區塊都從上下文中刪除。

更多詳細資訊，請參閱擴展思考文件。

快取儲存和共享

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

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

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

有效快取的最佳實踐

要優化提示詞快取效能：

• 從自動快取開始進行多輪對話。它自動處理斷點管理。
• 當您需要以不同更改頻率快取不同部分時，使用明確區塊級斷點。
• 快取穩定、可重複使用的內容，如系統指令、背景資訊、大型上下文或頻繁使用的工具定義。
• 將快取內容放在提示詞的開頭以獲得最佳效能。
• 策略性地使用快取斷點來分隔不同的可快取前綴部分。
• 在對話末尾和可編輯內容之前設置快取斷點，以最大化快取命中率，特別是在處理超過 20 個內容區塊的提示詞時。
• 定期分析快取命中率並根據需要調整您的策略。

針對不同使用案例的優化

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

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

常見問題排除

如果遇到意外行為：

• 確保快取部分在各次呼叫中相同。對於明確斷點，驗證 cache_control 標記在相同位置
• 檢查呼叫是否在快取有效期內進行（預設為 5 分鐘）
• 驗證 tool_choice 和圖片使用在各次呼叫之間保持一致
• 驗證您至少快取了最小數量的 token
• 系統會自動檢查先前內容區塊邊界的快取命中（在您的斷點之前最多約 20 個區塊）。對於超過 20 個內容區塊的提示詞，您可能需要在提示詞早期添加額外的 cache_control 參數，以確保所有內容都可以被快取
• 驗證您的 tool_use 內容區塊中的鍵具有穩定的排序，因為某些語言（例如 Swift、Go）在 JSON 轉換期間會隨機化鍵的順序，從而破壞快取

1 小時快取持續時間

如果您發現 5 分鐘太短，Anthropic 也提供 1 小時的快取持續時間，需額外付費。

要使用擴展快取，請在 cache_control 定義中包含 ttl，如下所示：

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

回應將包含詳細的快取資訊，如下所示：

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 456,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

請注意，目前的 cache_creation_input_tokens 欄位等於 cache_creation 物件中值的總和。

何時使用 1 小時快取

如果您的提示詞以固定頻率使用（即每 5 分鐘以上使用一次的系統提示詞），請繼續使用 5 分鐘快取，因為這將繼續免費刷新。

1 小時快取最適合以下場景：

• 當您的提示詞可能使用頻率低於 5 分鐘，但高於每小時一次。例如，當代理側代理需要超過 5 分鐘時，或者當儲存與使用者的長聊天對話且您通常預期該使用者可能不會在接下來的 5 分鐘內回應時。
• 當延遲很重要且您的後續提示詞可能在 5 分鐘後發送時。
• 當您想要改善速率限制利用率時，因為快取命中不會從您的速率限制中扣除。

混合不同的 TTL

您可以在同一請求中同時使用 1 小時和 5 分鐘的快取控制，但有一個重要限制：具有較長 TTL 的快取條目必須出現在較短 TTL 之前（即 1 小時快取條目必須出現在任何 5 分鐘快取條目之前）。

混合 TTL 時，我們在您的提示詞中確定三個計費位置：

1. 位置 A：最高快取命中時的 token 計數（如果沒有命中則為 0）。
2. 位置 B：A 之後最高 1 小時 cache_control 區塊的 token 計數（如果不存在則等於 A）。
3. 位置 C：最後一個 cache_control 區塊的 token 計數。

您將被收費：

1. A 的快取讀取 token。
2. (B - A) 的 1 小時快取寫入 token。
3. (C - B) 的 5 分鐘快取寫入 token。

以下是 3 個範例。這描繪了 3 個請求的輸入 token，每個請求都有不同的快取命中和快取未命中。每個請求都有不同的計算定價，如彩色框所示。

提示快取範例

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

以下，我們提供了幾個程式碼片段，展示各種提示快取模式。這些範例示範如何在不同情境中實作快取，幫助您了解此功能的實際應用：

資料保留

提示快取儲存 KV（鍵值）快取表示形式和快取內容的加密雜湊值，但不儲存提示或回應的原始文字。快取條目的最短存活時間為 5 分鐘（標準）或 60 分鐘（延長）。快取條目在各組織之間相互隔離。由於 Anthropic 不儲存原始提示或回應文字，此功能可能適合需要 ZDR 類型資料保留承諾的客戶。

如需了解所有功能的 ZDR 資格，請參閱API 與資料保留。

常見問題