提示詞快取

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

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

• 自動快取：在您的請求頂層添加單個 cache_control 欄位。系統會自動將快取斷點應用於最後一個可快取區塊，並隨著對話增長而向前移動。最適合多輪對話，其中不斷增長的訊息歷史應自動快取。
• 明確快取斷點：直接在各個內容區塊上放置 cache_control，以精細控制究竟快取什麼。

最簡單的開始方式是使用自動快取：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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'.",
        }
    ],
)
print(response.usage.model_dump_json())

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

提示詞快取如何運作

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

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

這對以下情況特別有用：

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

預設情況下，快取的生命週期為 5 分鐘。每次使用快取內容時，快取都會以零額外成本刷新。

定價

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

支援的模型

提示詞快取（自動和明確）在所有活躍 Claude 模型上都受支援。

自動快取

自動快取是啟用提示詞快取的最簡單方式。與其在各個內容區塊上放置 cache_control，而是在您的請求正文頂層添加單個 cache_control 欄位。系統會自動將快取斷點應用於最後一個可快取區塊。

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

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

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

TTL 支援

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

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

與區塊級快取結合

自動快取與明確快取斷點相容。一起使用時，自動快取斷點使用 4 個可用斷點槽之一。

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

{
  "model": "claude-opus-4-7",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

保持不變的內容

自動快取使用相同的基礎快取基礎設施。定價、最小代幣閾值、上下文排序要求和 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 個區塊。 系統每個斷點最多檢查 20 個位置，將斷點本身計為第一個。如果系統在該窗口中找不到匹配的條目，檢查停止（或如果有任何其他明確斷點，則從下一個明確斷點恢復）。

範例：在不斷增長的對話中回溯

您每輪附加新區塊並在每個請求的最後一個區塊上設置 cache_control：

• 輪 1： 10 個區塊，斷點在區塊 10。不存在先前的快取條目。系統在區塊 10 寫入一個條目。
• 輪 2： 15 個區塊，斷點在區塊 15。區塊 15 沒有條目，因此系統向後走到區塊 10 並找到輪 1 條目。在區塊 10 快取命中；系統僅新鮮處理區塊 11 至 15 並在區塊 15 寫入新條目。
• 輪 3： 35 個區塊，斷點在區塊 35。系統檢查 20 個位置（區塊 35 至 16）並找不到任何內容。輪 2 條目在區塊 15 位於窗口外一個位置，因此沒有快取命中。在區塊 15 添加第二個斷點會在那裡啟動第二個回溯窗口，該窗口找到輪 2 條目。

常見錯誤：斷點在每個請求都變化的內容上

您的提示詞有大型靜態系統上下文（區塊 1 至 5），後面是包含時間戳和使用者訊息的每個請求區塊（區塊 6）。您在區塊 6 上設置 cache_control：

• 請求 1： 在區塊 6 快取寫入。雜湊包括時間戳。
• 請求 2： 時間戳不同，因此區塊 6 的前綴雜湊不同。回溯走過區塊 5、4、3、2 和 1，但系統從未在任何這些位置寫入條目。沒有快取命中。您在每個請求上為新快取寫入付費，永遠不會獲得讀取。

回溯不會在您的斷點後面找到穩定內容並快取它。它找到先前請求已寫入的條目，寫入僅在斷點處發生。將 cache_control 移動到區塊 5，即跨請求保持相同的最後一個區塊，每個後續請求都會讀取快取的前綴。自動快取陷入相同的陷阱：它將斷點放在最後一個可快取區塊上，在此結構中是每個請求都變化的區塊，因此改用區塊 5 上的明確斷點。

關鍵要點： 將 cache_control 放在其前綴在您想共享快取的請求中相同的最後一個區塊上。在不斷增長的對話中，只要每輪添加少於 20 個區塊，最後一個區塊就可以工作：較早的內容永遠不會變化，因此下一個請求的回溯找到先前的寫入。對於具有變化後綴的提示詞（時間戳、每個請求的上下文、傳入訊息），將斷點放在靜態前綴的末尾，而不是在變化區塊上。

何時使用多個斷點

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

• 快取以不同頻率變化的不同部分（例如，工具很少變化，但上下文每天更新）
• 對究竟快取什麼有更多控制
• 確保當不斷增長的對話將您的斷點推過最後一次寫入 20 個或更多區塊時快取命中

理解快取斷點成本

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

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

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

快取策略和考慮

快取限制

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

• Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Opus 4.5 的 4096 個代幣
• Claude Sonnet 4.6 的 2048 個代幣
• Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4 和 Claude Sonnet 3.7 的 1024 個代幣（已棄用）
• Claude Haiku 4.5 的 4096 個代幣
• Claude Haiku 3.5（已棄用）和 Claude Haiku 3 的 2048 個代幣

較短的提示詞無法快取，即使標記有 cache_control。任何快取少於此代幣數的請求都將在不快取的情況下處理，並且不會返回錯誤。要驗證提示詞是否被快取，請檢查回應使用欄位：如果 cache_creation_input_tokens 和 cache_read_input_tokens 都為 0，提示詞未被快取（可能是因為它未達到最小長度要求）。

如果您的提示詞剛好低於您使用的模型的最小值，擴展快取內容以達到閾值通常是值得的。快取讀取的成本遠低於未快取的輸入代幣，因此達到最小值可以降低頻繁重複使用的提示詞的成本。

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

目前，「ephemeral」是唯一支援的快取類型，預設情況下生命週期為 5 分鐘。

可以快取的內容

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

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

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

無法快取的內容

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

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

• 子內容區塊（如引用）本身無法直接快取。相反，快取頂層區塊。

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

• 空文字區塊無法快取。

什麼使快取失效

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

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

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

追蹤快取效能

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

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

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

使用思考塊進行快取

當使用延伸思考搭配提示快取時，思考塊有特殊的行為：

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

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

快取失效模式：

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

有關快取失效的更多詳細資訊，請參閱什麼會使快取失效。

工具使用範例：

請求 1：使用者："巴黎的天氣如何？"
回應：[thinking_block_1] + [tool_use block 1]

請求 2：
使用者：["巴黎的天氣如何？"],
助手：[thinking_block_1] + [tool_use block 1],
使用者：[tool_result_1, cache=True]
回應：[thinking_block_2] + [text block 2]
# 請求 2 快取其請求內容（不是回應）
# 快取包括：使用者訊息、thinking_block_1、tool_use block 1 和 tool_result_1

請求 3：
使用者：["巴黎的天氣如何？"],
助手：[thinking_block_1] + [tool_use block 1],
使用者：[tool_result_1, cache=True],
助手：[thinking_block_2] + [text block 2],
使用者：[文字回應, cache=True]
# 非工具結果的使用者塊會指定新的助手迴圈，所有先前的思考塊都會從上下文中移除
# 此請求的處理方式就像思考塊從未存在過一樣

當包含非工具結果的使用者塊時，它會指定新的助手迴圈，所有先前的思考塊都會從上下文中移除。

有關更詳細的資訊，請參閱延伸思考文件。

快取儲存和共享

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

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

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

有效快取的最佳實踐

為了優化提示快取效能：

• 從自動快取開始進行多輪對話。它會自動處理斷點管理。
• 當您需要快取具有不同變更頻率的不同部分時，使用明確的塊級斷點。
• 快取穩定、可重複使用的內容，例如系統指令、背景資訊、大型上下文或頻繁的工具定義。
• 將快取內容放在提示的開頭以獲得最佳效能。
• 策略性地使用快取斷點來分離不同的可快取前綴部分。
• 將斷點放在跨請求保持相同的最後一個塊上。對於具有靜態前綴和變動後綴（時間戳、每個請求的上下文、傳入訊息）的提示，這是前綴的末尾，而不是變動塊。
• 定期分析快取命中率並根據需要調整您的策略。

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

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

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

疑難排解常見問題

如果遇到意外行為：

• 確保快取的部分在呼叫中相同。對於明確的斷點，驗證 cache_control 標記位於相同的位置
• 檢查呼叫是否在快取生命週期內進行（預設為 5 分鐘）
• 驗證 tool_choice 和圖像使用在呼叫之間保持一致
• 驗證您快取的令牌數至少是您使用的模型的最小數量（請參閱快取限制）。基於長度的快取失敗是無聲的：請求成功，但 cache_creation_input_tokens 和 cache_read_input_tokens 都將為 0
• 確認您的斷點位於跨請求保持相同的塊上。快取寫入僅在斷點處進行，如果該塊變更（時間戳、每個請求的上下文、傳入訊息），前綴雜湊永遠不會匹配。回溯不會在斷點後面找到穩定內容；它只會找到較早請求在其自己的斷點處寫入的條目
• 驗證您的 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 時，API 在您的提示中確定三個計費位置：

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

您將被收費：

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

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

提示詞快取範例

為了幫助您開始使用提示詞快取，提示詞快取食譜提供了詳細的範例和最佳實踐。

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

資料保留

提示詞快取（自動和明確的）符合 ZDR 資格。Anthropic 不會儲存您的提示詞或 Claude 回應的原始文本。

KV（鍵值）快取表示和快取內容的密碼雜湊值僅保存在記憶體中，不會儲存在靜止狀態。快取項目的最短生命週期為 5 分鐘（標準）或 60 分鐘（延長），之後會迅速（但不是立即）刪除。快取項目在組織之間是隔離的。

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

常見問題

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