提示快取

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

以下是如何使用 cache_control 區塊透過 Messages API 實現提示快取的範例：

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,
    "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."
      }
    ]
  }'

# 使用相同的輸入再次呼叫模型，直到快取檢查點
curl https://api.anthropic.com/v1/messages # rest of input

{"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 分鐘。每次使用快取內容時，快取會免費刷新。

定價

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

如何實現提示快取

支援的模型

提示快取目前支援以下模型：

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

結構化您的提示

將靜態內容（工具定義、系統指令、上下文、範例）放在提示的開頭。使用 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 個區塊視窗之外發生變更時也能獲得快取命中

快取限制

最小可快取提示長度為：

• Claude Opus 4.6、Claude Opus 4.5 為 4096 個 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 分鐘。

了解快取斷點成本

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

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

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

可以快取的內容

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

• 工具：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

有效快取的最佳實踐

要優化提示快取效能：

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

針對不同使用案例進行優化

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

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

常見問題排除

如果遇到意外行為：

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

使用思考區塊進行快取

當將延伸思考與提示快取一起使用時，思考區塊具有特殊行為：

與其他內容一起自動快取：雖然思考區塊不能明確標記 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 生成沒有影響。您收到的回應將與不使用提示快取時獲得的回應完全相同。

1 小時快取持續時間

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

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

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

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

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "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，每個請求具有不同的快取命中和快取未命中。每個請求因此有不同的計算定價，顯示在彩色方框中。

提示快取範例

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

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

常見問題

這對於了解成本和速率限制都很重要，因為在有效使用快取時，input_tokens 通常會比您的總輸入小得多。