Claude Platform Docs
Messages上下文管理

提示快取

使用 cache_control 快取提示前綴以降低成本與延遲，可採用自動快取或具有 5 分鐘或 1 小時 TTL 的明確斷點。

用法因產品而異

Messages API
透過在頂層或區塊上設定 cache_control 來選擇啟用。
Managed Agents
永遠開啟快取項目預設存留 5 分鐘，快取讀取與寫入會顯示在工作階段的用量中。

「Prompt caching」（提示快取）可讓 API 從您提示中的特定前綴繼續處理，藉此最佳化您的 API 使用。這能大幅減少重複性任務或具有一致元素之提示的處理時間與成本。

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

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

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

client = anthropic.Anthropic()

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

存留時間是從寫入或讀取快取項目之請求的開始時計算，而非從其回應結束時計算。生成回應所花費的時間會計入存留時間：如果一個回應需要 4 分鐘來串流，則重複使用相同快取前綴的後續請求必須在該回應完成後約 1 分鐘內開始。

定價

提示快取有其專屬的定價。下表顯示每個支援模型每百萬 token 的價格：

模型基本 Token提示快取
名稱輸入輸出5 分鐘寫入1 小時寫入命中與重新整理
Claude Fable 5.2For demanding reasoning and long-horizon agentic work
US$8 / MTok
US$40 / MTok
US$10 / MTok
US$16 / MTok
US$0.20 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work
US$4 / MTok
US$20 / MTok
US$5 / MTok
US$8 / MTok
US$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence
US$2 / MTok
US$10 / MTok
US$2.50 / MTok
US$4 / MTok
US$0.10 / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
US$0.10 / MTok適用於不超過 100,000 個 Token 的提示詞
US$0.50 / MTok
US$0.125 / MTok
US$0.20 / MTok
US$0.01 / MTok
US$0.50 / MTok適用於超過 100,000 個 Token 的提示詞
US$2.50 / MTok
US$0.625 / MTok
US$1 / MTok
US$0.05 / MTok
US$8 / MTok
US$40 / MTok
US$10 / MTok
US$16 / MTok
US$0.20 / MTok1
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$0.25 / MTok1
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$0.25 / MTok1
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$1 / MTok
US$10 / MTok
US$50 / MTok
US$12.50 / MTok
US$20 / MTok
US$1 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
US$5 / MTok
US$25 / MTok
US$6.25 / MTok
US$10 / MTok
US$0.50 / MTok
Claude Opus 4.1
US$15 / MTok
US$75 / MTok
US$18.75 / MTok
US$30 / MTok
US$1.50 / MTok
Claude Opus 4
US$15 / MTok
US$75 / MTok
US$18.75 / MTok
US$30 / MTok
US$1.50 / MTok
US$2 / MTok
US$10 / MTok
US$2.50 / MTok
US$4 / MTok
US$0.20 / MTok
US$3 / MTok
US$15 / MTok
US$3.75 / MTok
US$6 / MTok
US$0.30 / MTok
US$3 / MTok
US$15 / MTok
US$3.75 / MTok
US$6 / MTok
US$0.30 / MTok
Claude Sonnet 4
US$3 / MTok
US$15 / MTok
US$3.75 / MTok
US$6 / MTok
US$0.30 / MTok
US$1 / MTok
US$5 / MTok
US$1.25 / MTok
US$2 / MTok
US$0.10 / MTok

1 Claude Fable 5.2、Claude Mythos 5.2、Claude Fable 5.1和Claude Mythos 5.1 的快取命中與重新整理價格為基本輸入價格的 0.025x。

2 Claude Opus 5.5和Claude Sonnet 5.5 的快取命中與重新整理價格為基本輸入價格的 0.05x。

所有其他模型皆使用標準的 0.1x 倍率。

支援的模型

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

自動快取

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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())

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

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

請求內容快取行為
請求 1System
+ User(1) + Asst(1)
+ User(2) ◀ 快取		所有內容寫入快取
請求 2System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) ◀ 快取		System 到 User(2) 從快取讀取；
Asst(2) + User(3) 寫入快取
請求 3System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ User(4) ◀ 快取		System 到 User(3) 從快取讀取；
Asst(3) + User(4) 寫入快取

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

TTL 支援

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

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

與區塊層級快取結合使用

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

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

{
  "model": "claude-opus-5-5",
  "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 個位置，斷點本身算作第一個。如果系統在該視窗內找不到相符的項目，檢查便會停止（或從下一個明確斷點繼續，如果有的話）。在 Claude API 上，一連串連續的 tool_use 區塊算作一個位置，一連串連續的 tool_result 區塊也是如此，因此包含許多平行工具呼叫的單一輪次，不會單獨將先前請求的項目推出視窗之外。

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

您在每一輪附加新區塊，並在每個請求的最後一個區塊上設定 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、Claude Platform on AWS、Claude Models on Google Cloud (Google managed) 和 Microsoft Foundry 上，最低可快取提示長度為：

這些最低值適用於每個模型可用的所有平台。

較短的提示無法被快取，即使標記了 cache_control 也一樣。任何快取少於此數量 token 的請求都會在不快取的情況下處理，且不會傳回錯誤。若要檢查提示是否已被快取，請查看回應用量欄位：如果 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。每個層級的變更都會使該層級及所有後續層級失效。

下表顯示不同類型的變更會使快取的哪些部分失效。✘ 表示快取失效，而 ✓ 表示快取仍然有效。

變更內容工具快取系統快取訊息快取影響
工具定義✘✘✘修改工具定義（名稱、描述、參數）會使整個快取失效
網路搜尋切換✓✘✘啟用/停用網路搜尋會修改系統提示
引用切換✓✘✘啟用/停用引用會修改系統提示
速度設定✓✘✘在 speed: "fast" 與標準速度之間切換會使系統和訊息快取失效
工具選擇✓✓✘變更 tool_choice 參數只會影響訊息區塊
圖片✓✓✘在提示中的任何位置新增/移除圖片會影響訊息區塊
思考參數依模型而定依模型而定✘思考設定（模式，以及擴展模式中的 budget_tokens）會被呈現到提示中，因此變更它一律會使訊息區塊失效；在將設定呈現於工具和系統之前的模型上，工具和系統快取也會失效。請參閱思考與提示快取。
Effort 設定依模型而定依模型而定✘變更 output_config.effort 值一律會使訊息區塊失效，對工具和系統快取的影響則與思考參數相同，依模型而定。將 effort 明確設定為模型的預設值等同於省略它，不會造成失效。在支援每則訊息 effort 的模型上，透過 messages 內的 role: "system" 訊息進行的 effort 變更會保持快取前綴完整。
傳遞給具有思考之請求的非工具結果✓✓依模型而定在 Opus 4.5+、Sonnet 4.6+ 和 Haiku 5.5 上，思考區塊預設會被保留，因此快取仍然有效（✓）。在較早的 Opus/Sonnet 模型以及直到 Claude Haiku 4.5 的 Haiku 模型上，所有先前快取的思考區塊都會從上下文中移除，且這些思考區塊之後的任何訊息都會從快取中移除（✘）。如需更多詳細資訊，請參閱搭配思考區塊的快取。
被捨棄的思考區塊✓✓✘當 API 捨棄在該請求中未被保留的 Claude 5.1 及更新模型的思考區塊時，該請求的快取前綴會從該區塊的位置開始改變。接收模型可讀取且原封不動傳回的區塊，會保持快取完整。

在支援對話中途工具變更的模型上，inline-tools-2026-09-15 beta 標頭可讓您在對話中途新增工具或變更工具定義，而無須編輯 tools。請在對話中途系統訊息的 tool_addition 區塊中傳送定義，並讓 tools 保持與您第一次傳送時完全相同。快取前綴仍然相符，因此只有附加的訊息會作為新輸入處理。唯一的例外是沒有任何非延遲工具的 tools 陣列，在這種情況下，以此方式定義的第一個工具會在該請求中造成一次完整的快取未命中。請參閱在訊息中定義工具。

追蹤快取效能

使用以下 API 回應欄位監控快取效能，這些欄位位於回應中的 usage 內（若使用串流，則位於 message_start 事件中）：

  • cache_creation_input_tokens：建立新項目時寫入快取的 token 數量
  • cache_read_input_tokens：此請求從快取擷取的 token 數量
  • input_tokens：未從快取讀取或未用於建立快取的輸入 token 數量（也就是最後一個快取斷點之後的 token）

搭配思考區塊的快取

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

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

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

快取失效模式：

  • 當只有工具結果作為使用者訊息提供時，快取仍然有效。
  • 在 Opus 4.5+、Sonnet 4.6+ 和 Haiku 5.5 上，即使新增了非工具結果的使用者內容，思考區塊預設也會被保留，因此快取仍然有效。
  • 在較早的 Opus/Sonnet 模型以及直到 Claude Haiku 4.5 的 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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

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

如需更詳細的資訊，請參閱思考與提示快取。

快取儲存與共用

  • 組織與工作區隔離： 快取在組織之間是隔離的。不同組織永遠不會共用快取，即使它們使用相同的提示也一樣。在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上，快取在組織內也依工作區隔離；Claude Models on Google Cloud (Google managed) 和 Bedrock 則僅使用組織層級隔離。

  • 完全比對： 快取命中需要 100% 相同的提示區段，包括直到並包含標記了快取控制之區塊的所有文字和圖片。

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

有效快取的最佳實務

若要最佳化提示快取效能：

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

針對不同使用案例進行最佳化

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

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

常見問題疑難排解

如果您遇到非預期的行為：

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

1 小時快取期限

如果您覺得 5 分鐘太短，Anthropic 也提供 1 小時的快取期限，需額外付費。

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

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

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

Output
{
  "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 時，Claude API 會在您的提示中決定三個計費位置：

  1. 位置 A：您的提示中最後一個快取命中處的 token 數量（若無命中則為 0）。
    • 若某個項目以 5 分鐘 TTL 快取，而位於其之後的某個 TTL 為 1 小時的 cache_control 區塊為快取未命中，則該項目上的命中不會被認定為命中。
    • 讀取以 5 分鐘 TTL 快取之項目的請求，會讓該項目重新開始其 5 分鐘的存留時間，即使這次的請求設定了 "ttl": "1h" 也一樣。
  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。

以下是三個範例請求，每個請求都有不同的快取命中和快取未命中。每個請求都有不同的計算價格，顯示在方塊中。

快取​讀取
1h 快取​寫入
5m 快取​寫入
提示的​其餘​部分
1h 命中
(A)
1h 未命中
1h 未命中
1h 未命中
(B)
5m 未命中
(C)
1h 快取​寫入
5m 快取​寫入
提示的​其餘​部分
(A 為零)
1h 未命中
1h 未命中
1h 未命中
1h 未命中
(B)
5m 未命中
(C)
快取​讀取
提示的​其餘​部分
1h 未命中
5m 命中
(A、B、C)

預熱快取

「Cache pre-warming」（快取預熱）可讓您在使用者觸發實際請求之前，將您的系統提示或工具定義載入提示快取中。這可以減少第一次使用者互動時的快取未命中延遲損失，為對延遲敏感的應用程式縮短「time-to-first-token」（首個 token 時間），即 TTFT。

運作方式

在您的請求中設定 max_tokens: 0。API 會將您的提示讀入模型，並在任何 cache_control 中斷點寫入快取，然後立即返回，不產生任何輸出。回應包含一個空的 content 陣列、stop_reason: "max_tokens"，以及一個完整填入的 usage 區塊。

將 cache_control 中斷點放在與後續請求共用的最後一個區塊上（通常是您的系統提示或工具定義），而不是放在佔位使用者訊息上。否則快取項目會以該佔位訊息為鍵，後續請求將無法命中。也請使用與後續請求相同的思考設定和 output_config.effort：這些值會被渲染到提示中（請參閱什麼會使快取失效），因此使用不同設定進行的預熱可能會寫入一個您的實際流量永遠不會命中的項目。這表示要使用明確快取中斷點而非自動快取，因為自動快取會將中斷點放在最後一個區塊上，而在這裡最後一個區塊是佔位訊息。佔位使用者訊息可以是任何包含非空白內容的字串（此處的範例使用 "warmup"）；其內容會被讀入模型，但永遠不會被回答。

client = anthropic.Anthropic()

# 在使用者到來前先發送此請求，以預熱共用的系統提示快取。
prewarm = client.messages.create(
    model="claude-opus-5-5",
    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 陣列：

Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "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-5-5",
        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-5-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


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

# 之後當使用者送出訊息時，系統提示前綴已經被快取。
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

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

限制

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

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

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

取代 max_tokens=1 的變通方法

有些應用程式會傳送 max_tokens: 1 請求來預熱快取。在請求允許的情況下，建議優先使用 max_tokens: 0：不會產生任何輸出，因此沒有需要捨棄的單一 token 回覆，不會計費輸出 token，且請求的意圖明確無誤。

提示快取範例

為了幫助您開始使用提示快取，Claude Cookbook 中的提示快取範例提供了詳細的範例和最佳實務。

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

資料保留

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

已快取內容的 KV（key-value，鍵值）快取表示和加密雜湊僅保存在記憶體中，不會以靜態方式儲存。快取項目的最短存活期為 5 分鐘（標準）或 1 小時（延長），之後會被及時（但非立即）刪除。快取項目在組織之間是隔離的，並且在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上，在同一組織內的工作區之間也是隔離的。

常見問題

可用性

提示快取
API
  • Messages API
  • Managed Agents Beta
模型
  • 所有模型

資料處理

資料處理概覽

適用端點

  • /v1/messages
零資料保留符合資格

不含 涵蓋的模型

您的提示與 Claude 的輸出不會被儲存。KV 快取表示與加密雜湊會在快取 TTL 期間保存在記憶體中，並在到期後立即刪除。 深入了解

HIPAA符合資格

這個頁面有幫助嗎？