提示快取

「Prompt caching」（提示快取）透過允許從提示中的特定前綴恢復來優化您的 API 使用。這可顯著減少重複性任務或具有一致元素之提示的處理時間和成本。

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

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

最簡單的入門方式是使用自動快取：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 分鐘。每次使用快取內容時，快取會免費重新整理。



定價

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



支援的模型

所有現行 Claude 模型均支援提示快取（包括自動和明確兩種方式）。



自動快取

自動快取是啟用提示快取最簡單的方式。您無需在個別內容區塊上放置 cache_control，只需在請求主體的頂層新增單一 cache_control 欄位即可。系統會自動將快取斷點套用至最後一個可快取的區塊。

client = anthropic.Anthropic()

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



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

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

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



TTL 支援

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

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



與區塊層級快取結合使用

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

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

{
  "model": "claude-opus-4-8",
  "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?" }]
}



保持不變的部分

自動快取使用相同的底層快取基礎架構。定價、最小 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 個區塊。 系統每個斷點最多檢查 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 比基本輸入 token 多 25%）
• 快取讀取：當使用快取內容時（基本輸入 token 價格的 10%）
• 一般輸入 token：任何未快取的內容

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



快取策略與考量事項



快取限制

在 Claude API、AWS 上的 Claude Platform、Vertex AI 和 Microsoft Foundry（測試版）上，最小可快取提示長度為：

• Claude Fable 5 和 Claude Mythos 5 為 512 個 token
• Claude Mythos Preview 和 Claude Opus 4.7 為 2,048 個 token
• Claude Opus 4.6 和 Claude Opus 4.5 為 4,096 個 token
• Claude Opus 4.8、Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Opus 4.1（已棄用）、Claude Opus 4（已停用，Vertex AI 除外）和 Claude Sonnet 4（已停用，Bedrock 和 Vertex AI 除外）為 1,024 個 token
• Claude Haiku 4.5 為 4,096 個 token
• Claude Haiku 3.5（已停用，Vertex AI 除外）為 2,048 個 token

模型可用性因平台而異，新發布模型的最小值也可能不同：在 Amazon Bedrock 上，Claude Fable 5 和 Claude Mythos 5 的最小可快取提示長度為 1,024 個 token。

較短的提示無法快取，即使標記了 cache_control 也一樣。任何快取少於此 token 數量的請求都會在不快取的情況下處理，且不會回傳錯誤。若要驗證提示是否已快取，請檢查回應的 usage 欄位：如果 cache_creation_input_tokens 和 cache_read_input_tokens 都是 0，則提示未被快取（可能是因為未達到最小長度要求）。

如果您的提示略低於您的模型和平台的最小值，擴充快取內容以達到門檻通常是值得的。快取讀取的成本遠低於未快取的輸入 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 預算很重要。

快取失效模式：

• 當僅提供工具結果作為使用者訊息時，快取保持有效
• 在 Opus 4.5+ 和 Sonnet 4.6+ 上，即使新增非工具結果的使用者內容，思考區塊預設也會保留，因此快取保持有效
• 在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，當新增非工具結果的使用者內容時，快取會失效，導致所有先前的思考區塊從上下文中移除
• 即使沒有明確的 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]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

在較早的 Opus/Sonnet 模型和所有 Haiku 模型上，此時所有先前的思考區塊都會從上下文中移除。在 Opus 4.5+ 和 Sonnet 4.6+ 上，先前的思考區塊預設會保留，並仍是快取前綴的一部分。

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



快取儲存與共用

• 組織和工作區隔離： 快取在組織之間是隔離的。不同的組織永遠不會共用快取，即使它們使用相同的提示。自 2026 年 2 月 5 日起，在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry（測試版）上，快取也會在組織內按工作區隔離；Bedrock 和 Vertex AI 繼續僅使用組織層級隔離。

• 精確比對： 快取命中需要 100% 相同的提示區段，包括直到並包含以 cache control 標記之區塊的所有文字和圖片。

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



有效快取的最佳實務

若要優化提示快取效能：

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



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

根據您的情境調整提示快取策略：

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



疑難排解常見問題

如果遇到非預期的行為：

• 確保快取區段在各次呼叫之間完全相同。對於明確斷點，請驗證 cache_control 標記位於相同位置
• 檢查呼叫是否在快取存活時間內進行（預設為 5 分鐘）
• 驗證 tool_choice 和圖片使用在各次呼叫之間保持一致
• 驗證您快取的 token 數量至少達到您的模型和平台的最小值（請參閱快取限制）
• 確認您的斷點位於跨請求保持相同的區塊上。快取寫入只發生在斷點處，如果該區塊變更（時間戳記、每次請求的上下文、傳入的訊息），前綴雜湊永遠不會相符。回溯不會找到斷點後方的穩定內容；它只會找到先前請求在其自身斷點處寫入的項目
• 驗證您的 tool_use 內容區塊中的鍵具有穩定的排序，因為某些語言（例如 Swift、Go）在 JSON 轉換期間會隨機化鍵的順序，從而破壞快取
• 使用快取診斷讓 API 比較連續的請求，並報告提示的哪個部分出現分歧



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": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

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

如果您在使用伺服器工具（例如網路搜尋）時看到未請求的 ephemeral_5m_input_tokens 寫入，請參閱此關於提示快取與工具使用的指南。



何時使用 1 小時快取

如果您有定期使用的提示（即使用頻率高於每 5 分鐘一次的系統提示），請繼續使用 5 分鐘快取，因為這會持續免費重新整理。

1 小時快取最適合用於以下情境：

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



混合不同的 TTL

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

當混合 TTL 時，API 會在您的提示中確定三個計費位置：

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



預熱快取

快取預熱讓您可以在使用者觸發真實請求之前，將系統提示或工具定義載入提示快取中。這消除了第一次使用者互動時的快取未命中延遲懲罰，降低對延遲敏感之應用程式的「time-to-first-token」（首個 token 時間），即 TTFT。



運作方式

在您的請求中設定 max_tokens: 0。API 會將您的提示讀入模型，並在任何 cache_control 斷點處寫入快取，然後立即回傳而不生成任何輸出。回應具有空的 content 陣列、stop_reason: "max_tokens" 和完整填入的 usage 區塊。

將 cache_control 斷點放在與後續請求共用的最後一個區塊上（通常是您的系統提示或工具定義），而不是佔位符使用者訊息上。否則快取項目會以佔位符為鍵，後續請求將無法命中它。這意味著使用明確快取斷點而非自動快取，因為自動快取會將斷點放在最後一個區塊上，而在此處該區塊正是佔位符。佔位符使用者訊息可以是任何具有非空白內容的字串（此處的範例使用 "warmup"）；其內容會被讀入模型但永遠不會被回答。

client = anthropic.Anthropic()

# 在使用者到達前觸發此操作，以預熱共用的系統提示快取。
prewarm = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

API 回傳空的 content 陣列：

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-4-8",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}



典型使用模式

當您的應用程式啟動時（或按排程間隔）發送預熱請求，然後在預熱完成後發送真實的使用者請求：

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-4-8",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# 在任何使用者流量到達之前預熱快取。
prewarm_cache()

# 之後，當使用者提交訊息時，系統提示前綴已經被快取。
response = respond("How do I implement a binary search tree?")
print(response.content[0].text)

請記住，快取 TTL 仍然適用。對於預設的 5 分鐘快取，至少每 5 分鐘發送一次新的預熱請求以保持快取處於預熱狀態。對於使用者請求之間較長的間隔，請改用 1 小時快取持續時間。



限制

如果設定了以下任何一項，max_tokens: 0 請求將被拒絕並回傳 invalid_request_error，因為每一項都意味著需要產生輸出，而零 token 預算無法產生任何輸出：

• stream: true
• 擴展思考（thinking.type: "enabled"）
• 結構化輸出（output_config.format）
• tool_choice 為 {"type": "tool", ...} 或 {"type": "any"}

在 Message Batches 請求中，max_tokens: 0 也會被拒絕。預熱（pre-warming）的目標是縮短首個 token 的回應時間，這不適用於批次處理，而且在批次處理期間寫入的快取項目很可能在後續請求執行之前就已過期。



取代 max_tokens=1 的變通方法

在 max_tokens: 0 可用之前，某些應用程式使用 max_tokens: 1 的預熱呼叫來達到相同效果。建議優先使用 max_tokens: 0 方法：不會產生任何輸出，因此沒有需要丟棄的單一 token 回覆，不會計費任何輸出 token，且請求的意圖明確無歧義。



提示快取範例

為了協助您開始使用「prompt caching」（提示快取），提示快取 cookbook 提供了詳細的範例和最佳實務。

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



資料保留

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

KV（鍵值）快取表示和已快取內容的加密雜湊僅保存在記憶體中，不會儲存於靜態儲存裝置。快取項目的最短存續期間為 5 分鐘（標準）或 1 小時（延長），之後會被迅速（但非立即）刪除。快取項目在組織之間是隔離的，而在 Claude API、AWS 上的 Claude Platform 以及 Microsoft Foundry（測試版）上，組織內的工作區之間也是隔離的。

有關所有功能的 ZDR 資格，請參閱 API 與資料保留。



常見問題