提示快取

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

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

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

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

JSON
{"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 呼叫中重複使用，而無需每次都重新處理。僅更改使用者訊息就可以讓您詢問有關該書的各種問題，同時利用快取的內容，從而獲得更快的回應和提高效率。

提示快取的工作原理

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

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

這對以下情況特別有用：

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

預設情況下，快取的生命週期為 5 分鐘。每次使用快取內容時，快取都會免費刷新。

如果您發現 5 分鐘太短，Anthropic 也提供 1 小時的快取持續時間。

更多資訊請參閱 1 小時快取持續時間。

提示快取會快取完整的前綴

提示快取引用整個提示 - tools、system 和 messages（按此順序），直到並包括標記為 cache_control 的區塊。

定價

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

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Sonnet 4	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.5 (deprecated)	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Haiku 3.5	$0.80 / MTok	$1 / MTok	$1.6 / MTok	$0.08 / MTok	$4 / MTok
Claude Opus 3 (deprecated)	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Haiku 3	$0.25 / MTok	$0.30 / MTok	$0.50 / MTok	$0.03 / MTok	$1.25 / MTok

上表反映了提示快取的以下定價倍數：

5 分鐘快取寫入代幣是基本輸入代幣價格的 1.25 倍
1 小時快取寫入代幣是基本輸入代幣價格的 2 倍
快取讀取代幣是基本輸入代幣價格的 0.1 倍

如何實現提示快取

支援的模型

提示快取目前支援：

Claude Opus 4.1
Claude Opus 4
Claude Sonnet 4
Claude Sonnet 3.7
Claude Sonnet 3.5 (已棄用)
Claude Haiku 3.5
Claude Haiku 3
Claude Opus 3 (已棄用)

構建您的提示

將靜態內容（工具定義、系統指令、上下文、範例）放在提示的開頭。使用 cache_control 參數標記可重複使用內容的結尾以進行快取。

快取前綴按以下順序建立：tools、system，然後是 messages。這個順序形成一個層次結構，其中每個層級都建立在前一個層級之上。

自動前綴檢查的工作原理

您只需在靜態內容的末尾使用一個快取斷點，系統將自動找到最長的匹配前綴。 工作原理如下：

當您添加 cache_control 斷點時，系統會自動檢查所有先前內容區塊邊界（在您的明確斷點之前大約 20 個區塊）的快取命中
如果這些先前位置中的任何一個與早期請求的快取內容匹配，系統會使用最長的匹配前綴
這意味著您不需要多個斷點來啟用快取 - 末尾的一個就足夠了

何時使用多個斷點

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

快取以不同頻率變化的不同部分（例如，工具很少變化，但上下文每天更新）
對確切快取內容有更多控制
確保對最終斷點之前超過 20 個內容區塊的內容進行快取

重要限制：自動前綴檢查只會從每個明確斷點向前查看大約 20 個內容區塊。如果您的提示在快取斷點之前有超過 20 個內容區塊，除非您添加額外的斷點，否則早於該點的內容不會被檢查快取命中。

快取限制

最小可快取提示長度為：

Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5 (已棄用) 和 Claude Opus 3 (已棄用) 為 1024 個代幣
Claude Haiku 3.5 和 Claude Haiku 3 為 2048 個代幣

較短的提示無法被快取，即使標記了 cache_control。任何快取少於此數量代幣的請求都將在不快取的情況下處理。要查看提示是否被快取，請參閱回應使用情況欄位。

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

目前，“ephemeral” 是唯一支援的快取類型，預設生命週期為 5 分鐘。

理解快取斷點成本

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

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

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

可以快取的內容

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

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

這些元素中的每一個都可以標記為 cache_control 以啟用該部分請求的快取。

無法快取的內容

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

思考區塊無法直接使用 cache_control 快取。但是，當思考區塊出現在先前的助手輪次中時，它們可以與其他內容一起快取。以這種方式快取時，它們在從快取讀取時確實計為輸入代幣。
子內容區塊（如引用）本身無法直接快取。相反，快取頂級區塊。

在引用的情況下，作為引用來源材料的頂級文件內容區塊可以快取。這允許您通過快取引用將引用的文件來有效地使用提示快取。
空文字區塊無法快取。

什麼會使快取失效

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

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

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

變更內容	工具快取	系統快取	訊息快取	影響
工具定義	✘	✘	✘	修改工具定義（名稱、描述、參數）會使整個快取失效
網路搜尋切換	✓	✘	✘	啟用/停用網路搜尋會修改系統提示
引用切換	✓	✘	✘	啟用/停用引用會修改系統提示
工具選擇	✓	✓	✘	`tool_choice` 參數的變更只影響訊息區塊
圖像	✓	✓	✘	在提示中任何地方添加/移除圖像都會影響訊息區塊
思考參數	✓	✓	✘	擴展思考設定的變更（啟用/停用、預算）會影響訊息區塊
傳遞給擴展思考請求的非工具結果	✓	✓	✘	當在啟用擴展思考時傳遞非工具結果時，所有先前快取的思考區塊都會從上下文中剝離，並且上下文中跟隨這些思考區塊的任何訊息都會從快取中移除。更多詳情請參閱使用思考區塊進行快取。

追蹤快取效能

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

cache_creation_input_tokens：建立新條目時寫入快取的代幣數量。
cache_read_input_tokens：此請求從快取中檢索的代幣數量。
input_tokens：未從快取讀取或用於建立快取的輸入代幣數量。

有效快取的最佳實踐

要優化提示快取效能：

快取穩定、可重複使用的內容，如系統指令、背景資訊、大型上下文或常用工具定義。
將快取內容放在提示的開頭以獲得最佳效能。
策略性地使用快取斷點來分離不同的可快取前綴部分。
定期分析快取命中率並根據需要調整您的策略。

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

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

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

常見問題疑難排解

如果遇到意外行為：

確保快取部分相同並在呼叫之間在相同位置標記為 cache_control
檢查呼叫是否在快取生命週期內進行（預設為 5 分鐘）
驗證 tool_choice 和圖像使用在呼叫之間保持一致
驗證您至少快取了最小數量的代幣
系統會自動檢查先前內容區塊邊界（在您的斷點之前最多約 20 個區塊）的快取命中。對於超過 20 個內容區塊的提示，您可能需要在提示中較早的位置添加額外的 cache_control 參數以確保所有內容都可以快取

對 tool_choice 的變更或提示中任何地方圖像的存在/缺失都會使快取失效，需要建立新的快取條目。有關快取失效的更多詳情，請參閱什麼會使快取失效。

使用思考區塊進行快取

當使用擴展思考與提示快取時，思考區塊有特殊行為：

與其他內容一起自動快取：雖然思考區塊無法明確標記為 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% 相同的提示段，包括所有文字和圖像，直到並包括標記為快取控制的區塊。
輸出代幣生成：提示快取對輸出代幣生成沒有影響。您收到的回應將與不使用提示快取時收到的回應相同。

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 分鐘後發送時。
當您想要改善速率限制利用率時，因為快取命中不會從您的速率限制中扣除。

5 分鐘和 1 小時快取在延遲方面表現相同。對於長文件，您通常會看到改善的首個代幣時間。

混合不同的 TTL

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

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

位置 A：最高快取命中的代幣計數（如果沒有命中則為 0）。
位置 B：A 之後最高 1 小時 cache_control 區塊的代幣計數（如果不存在則等於 A）。
位置 C：最後一個 cache_control 區塊的代幣計數。

如果 B 和/或 C 大於 A，它們必然是快取未命中，因為 A 是最高快取命中。

您將被收費：

A 的快取讀取代幣。
(B - A) 的 1 小時快取寫入代幣。
(C - B) 的 5 分鐘快取寫入代幣。

這裡有 3 個範例。這描述了 3 個請求的輸入代幣，每個請求都有不同的快取命中和快取未命中。每個都有不同的計算定價，如彩色框所示。

提示快取範例

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

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

大型上下文快取範例

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

這個範例演示了基本的提示快取使用，快取法律協議的完整文本作為前綴，同時保持使用者指令未快取。

對於第一個請求：

input_tokens：僅使用者訊息中的代幣數量
cache_creation_input_tokens：整個系統訊息中的代幣數量，包括法律文件
cache_read_input_tokens：0（第一個請求沒有快取命中）

對於快取生命週期內的後續請求：

input_tokens：僅使用者訊息中的代幣數量
cache_creation_input_tokens：0（沒有新的快取建立）
cache_read_input_tokens：整個快取系統訊息中的代幣數量

快取工具定義

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

在這個範例中，我們演示了快取工具定義。

cache_control 參數放在最後一個工具（get_time）上，以將所有工具指定為靜態前綴的一部分。

這意味著所有工具定義，包括 get_weather 和在 get_time 之前定義的任何其他工具，都將作為單個前綴快取。

當您有一組一致的工具想要在多個請求中重複使用而不每次都重新處理它們時，這種方法很有用。

對於第一個請求：

input_tokens：使用者訊息中的代幣數量
cache_creation_input_tokens：所有工具定義和系統提示中的代幣數量
cache_read_input_tokens：0（第一個請求沒有快取命中）

對於快取生命週期內的後續請求：

input_tokens：使用者訊息中的代幣數量
cache_creation_input_tokens：0（沒有新的快取建立）
cache_read_input_tokens：所有快取工具定義和系統提示中的代幣數量

繼續多輪對話

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

在這個範例中，我們演示了如何在多輪對話中使用提示快取。

在每一輪中，我們用 cache_control 標記最後一條訊息的最後一個區塊，這樣對話就可以增量快取。系統將自動查找並使用最長的先前快取前綴進行後續訊息。也就是說，先前標記為 cache_control 區塊的區塊後來沒有標記為此，但如果它們在 5 分鐘內被命中，它們仍然會被視為快取命中（也是快取刷新！）。

此外，請注意 cache_control 參數放在系統訊息上。這是為了確保如果這從快取中被驅逐（在超過 5 分鐘未使用後），它將在下一個請求中被添加回快取。

這種方法對於在持續對話中維護上下文而不重複處理相同資訊很有用。

當正確設定時，您應該在每個請求的使用情況回應中看到以下內容：

input_tokens：新使用者訊息中的代幣數量（將是最少的）
cache_creation_input_tokens：新助手和使用者輪次中的代幣數量
cache_read_input_tokens：對話中直到前一輪的代幣數量

整合所有內容：多個快取斷點

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

這個綜合範例演示了如何使用所有 4 個可用的快取斷點來優化提示的不同部分：

工具快取（快取斷點 1）：最後一個工具定義上的 cache_control 參數快取所有工具定義。
可重複使用指令快取（快取斷點 2）：系統提示中的靜態指令被單獨快取。這些指令在請求之間很少變化。
RAG 上下文快取（快取斷點 3）：知識庫文件被獨立快取，允許您更新 RAG 文件而不使工具或指令快取失效。
對話歷史快取（快取斷點 4）：助手的回應標記為 cache_control 以啟用對話隨著進展的增量快取。

這種方法提供最大的靈活性：

如果您只更新最後的使用者訊息，所有四個快取段都會被重複使用
如果您更新 RAG 文件但保持相同的工具和指令，前兩個快取段會被重複使用
如果您更改對話但保持相同的工具、指令和文件，前三個段會被重複使用
每個快取斷點都可以根據您的應用程式中的變化獨立失效

對於第一個請求：

input_tokens：最後使用者訊息中的代幣
cache_creation_input_tokens：所有快取段中的代幣（工具 + 指令 + RAG 文件 + 對話歷史）
cache_read_input_tokens：0（沒有快取命中）

對於僅有新使用者訊息的後續請求：

input_tokens：僅新使用者訊息中的代幣
cache_creation_input_tokens：添加到對話歷史的任何新代幣
cache_read_input_tokens：所有先前快取的代幣（工具 + 指令 + RAG 文件 + 先前對話）

這種模式對以下情況特別強大：

具有大型文件上下文的 RAG 應用程式
使用多個工具的代理系統
需要維護上下文的長時間對話
需要獨立優化提示不同部分的應用程式

常見問題

我需要多個快取斷點還是末尾的一個就足夠了？

快取斷點會增加額外成本嗎？

快取的生命週期是多長？

我可以使用多少個快取斷點？

提示快取是否適用於所有模型？

提示快取如何與擴展思考配合使用？

如何啟用提示快取？

我可以將提示快取與其他 API 功能一起使用嗎？

提示快取如何影響定價？

我可以手動清除快取嗎？

如何追蹤我的快取策略的有效性？

什麼會破壞快取？

提示快取如何處理隱私和資料分離？

我可以將提示快取與批次 API 一起使用嗎？

為什麼我在 Python 中看到錯誤 `AttributeError: 'Beta' object has no attribute 'prompt_caching'`？

這個錯誤通常在您升級了 SDK 或使用過時的程式碼範例時出現。提示快取現在已普遍可用，所以您不再需要 beta 前綴。而不是：

python client.beta.prompt_caching.messages.create(...)

只需使用：

python client.messages.create(...)

為什麼我看到 'TypeError: Cannot read properties of undefined (reading 'messages')'？

這個錯誤通常在您升級了 SDK 或使用過時的程式碼範例時出現。提示快取現在已普遍可用，所以您不再需要 beta 前綴。而不是：

TypeScript
client.beta.promptCaching.messages.create(...)

只需使用：

client.messages.create(...)

詞彙表延伸思考

On this page

提示快取的工作原理
定價
如何實現提示快取
支援的模型
構建您的提示
自動前綴檢查的工作原理
何時使用多個斷點
快取限制
理解快取斷點成本
可以快取的內容
無法快取的內容
什麼會使快取失效
追蹤快取效能
有效快取的最佳實踐
針對不同使用案例進行優化
常見問題疑難排解
使用思考區塊進行快取
快取儲存和共享
1 小時快取持續時間
何時使用 1 小時快取
混合不同的 TTL
提示快取範例
常見問題

入門步驟

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

提示快取的工作原理

定價

如何實現提示快取

支援的模型

構建您的提示

自動前綴檢查的工作原理

何時使用多個斷點

快取限制

理解快取斷點成本

可以快取的內容

無法快取的內容

什麼會使快取失效

追蹤快取效能

有效快取的最佳實踐

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

常見問題疑難排解

使用思考區塊進行快取

快取儲存和共享

1 小時快取持續時間

何時使用 1 小時快取

混合不同的 TTL

提示快取範例

常見問題

入門步驟

模型與定價

了解 Claude

功能

工具

模型上下文協定 (MCP)

使用案例

提示工程

測試與評估

加強防護機制

法律中心

​提示快取的工作原理

​定價

​如何實現提示快取

​支援的模型

​構建您的提示

​自動前綴檢查的工作原理

​何時使用多個斷點

​快取限制

​理解快取斷點成本

​可以快取的內容

​無法快取的內容

​什麼會使快取失效

​追蹤快取效能

​有效快取的最佳實踐

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

​常見問題疑難排解

​使用思考區塊進行快取

​快取儲存和共享

​1 小時快取持續時間

​何時使用 1 小時快取

​混合不同的 TTL

​提示快取範例

​常見問題

提示快取的工作原理

定價

如何實現提示快取

支援的模型

構建您的提示

自動前綴檢查的工作原理

何時使用多個斷點

快取限制

理解快取斷點成本

可以快取的內容

無法快取的內容

什麼會使快取失效

追蹤快取效能

有效快取的最佳實踐

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

常見問題疑難排解

使用思考區塊進行快取

快取儲存和共享

1 小時快取持續時間

何時使用 1 小時快取

混合不同的 TTL

提示快取範例

常見問題