Claude Platform Docs
Messages上下文管理

提示快取

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

「Prompt caching」（提示快取）可讓您從提示中的特定前綴繼續處理，藉此最佳化您的 API 使用。對於重複性任務或包含固定元素的提示，這能大幅縮短處理時間並降低成本。

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

  • 自動快取：在請求的最上層加入單一 cache_control 欄位。系統會自動將「cache breakpoint」（快取斷點）套用到最後一個可快取的區塊，並隨著對話增長向前移動。最適合需要自動快取不斷增長之訊息歷史的多輪對話。
  • 明確快取斷點：將 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 的價格：

ModelBase tokensPrompt caching
NameInputOutput5m writes1h writesHits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work
$10 / MTok
$50 / MTok
$12.50 / MTok
$20 / MTok
$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work
$4 / MTok
$20 / MTok
$5 / MTok
$8 / MTok
$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence
$2 / MTok
$10 / MTok
$2.50 / MTok
$4 / MTok
$0.10 / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing
$0.10 / MTokfor prompts up to 100,000 tokens
$0.50 / MTok
$0.125 / MTok
$0.20 / MTok
$0.01 / MTok
$0.50 / MTokfor prompts over 100,000 tokens
$2.50 / MTok
$0.625 / MTok
$1 / MTok
$0.05 / MTok
Claude Mythos 5.1
$10 / MTok
$50 / MTok
$12.50 / MTok
$20 / MTok
$0.25 / MTok1
Claude Fable 5
$10 / MTok
$50 / MTok
$12.50 / MTok
$20 / MTok
$1 / MTok
Claude Mythos 5
$10 / MTok
$50 / MTok
$12.50 / MTok
$20 / MTok
$1 / MTok
Claude Opus 5
$5 / MTok
$25 / MTok
$6.25 / MTok
$10 / MTok
$0.50 / MTok
Claude Opus 4.8
$5 / MTok
$25 / MTok
$6.25 / MTok
$10 / MTok
$0.50 / MTok
Claude Opus 4.7
$5 / MTok
$25 / MTok
$6.25 / MTok
$10 / MTok
$0.50 / MTok
Claude Opus 4.6
$5 / MTok
$25 / MTok
$6.25 / MTok
$10 / MTok
$0.50 / MTok
Claude Opus 4.5
$5 / MTok
$25 / MTok
$6.25 / MTok
$10 / MTok
$0.50 / MTok
Claude Opus 4.1
$15 / MTok
$75 / MTok
$18.75 / MTok
$30 / MTok
$1.50 / MTok
Claude Opus 4
$15 / MTok
$75 / MTok
$18.75 / MTok
$30 / MTok
$1.50 / MTok
Claude Sonnet 5
$2 / MTok
$10 / MTok
$2.50 / MTok
$4 / MTok
$0.20 / MTok
Claude Sonnet 4.6
$3 / MTok
$15 / MTok
$3.75 / MTok
$6 / MTok
$0.30 / MTok
Claude Sonnet 4.5
$3 / MTok
$15 / MTok
$3.75 / MTok
$6 / MTok
$0.30 / MTok
Claude Sonnet 4
$3 / MTok
$15 / MTok
$3.75 / MTok
$6 / MTok
$0.30 / MTok
Claude Haiku 4.5
$1 / MTok
$5 / MTok
$1.25 / MTok
$2 / MTok
$0.10 / MTok
Claude Haiku 3.5
$0.80 / MTok
$4 / MTok
$1 / MTok
$1.60 / MTok
$0.08 / MTok

1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.

2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.

All other models use the standard 0.1x multiplier.

支援的模型

所有現行 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 分鐘的「time to live」（存留時間），即 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 個區塊的「lookback window」（回溯視窗），皆與明確斷點的情況相同。

邊界情況

  • 如果最後一個區塊已有相同 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 發生「cache hit」（快取命中）；系統只需重新處理區塊 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%，在 Claude Fable 5.1 和 Claude Mythos 5.1 上為 2.5%，在 Claude Opus 5.5 和 Claude Sonnet 5.5 上為 5%）
  • 一般輸入 token： 任何未快取的內容

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

快取策略與注意事項

快取限制

在 Claude API、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 上，最小可快取提示長度為：

這些最低要求適用於提供各模型的每個平台。

較短的提示無法被快取，即使已標記 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。每個層級的變更都會使該層級及所有後續層級失效。

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

變更內容工具快取系統快取訊息快取影響
工具定義✘✘✘修改工具定義（名稱、描述、參數）會使整個快取失效
網頁搜尋切換✓✘✘啟用/停用網頁搜尋會修改系統提示
引用切換✓✘✘啟用/停用引用會修改系統提示
速度設定✓✘✘在 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 Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Sonnet 5.5 或 Claude Haiku 5.5 的思考區塊，且該區塊在該請求中未被保留時（例如，您將其重播給無法讀取它的模型），該請求的快取前綴會從該區塊的位置開始變更。接收模型可以讀取且未經變更傳回的區塊，會讓快取保持完整。

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

追蹤快取效能

使用回應中 usage 內的以下 API 回應欄位（若使用串流，則為 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 上，快取也會在組織內依工作區隔離；Bedrock 和 Google Cloud 僅使用組織層級的隔離。

  • 完全比對： 快取命中需要 100% 相同的提示區段，包括直到以 cache control 標記的區塊（含該區塊）為止的所有文字和圖片。

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

有效快取的最佳實務

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

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

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

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

  • 對話代理：降低長時間對話的成本和「latency」（延遲），特別是包含冗長指示或上傳文件的對話。
  • 程式設計助理：透過在提示中保留相關區段或程式碼庫的摘要版本，改善自動完成和程式碼庫問答。
  • 大型文件處理：在提示中納入包含圖片的完整長篇資料，而不會增加回應延遲。
  • 詳細指示集：分享大量的指示、程序和範例清單，以微調 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 時，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 個請求的輸入 token，每個請求都有不同的快取命中與快取未命中。因此，每個請求都有不同的計算價格，顯示在彩色方框中。

Cache Read1h Cache Write 5m Cache Write Rest of the prompt1h hit(A)1h miss1h miss1h miss(B)5m miss(C)1h Cache Write 5m Cache Write Rest of the prompt(A is zero)1h miss1h miss1h miss1h miss(B)5m miss(C)Cache ReadRest of the prompt1h miss5m hit(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: 0 推出之前，有些應用程式使用 max_tokens: 1 的預熱呼叫來達到相同的效果。建議使用 max_tokens: 0 的方式：它不會產生任何輸出，因此沒有需要捨棄的單一 token 回覆，不會對輸出 token 計費，而且請求的意圖也很明確。

提示快取範例

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

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

資料保留

提示快取（包括自動和明確快取）符合「zero data retention」（零資料保留），即 ZDR 的資格。Anthropic 不會儲存您提示或 Claude 回應的原始文字。

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

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

常見問題

Was this page helpful?