提示詞快取

提示詞快取是一項強大的功能，透過允許從提示詞中的特定前綴繼續進行，來最佳化您的 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-sonnet-4-5",
    "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."
      }
    ]
  }'

# 使用相同的輸入再次呼叫模型，直到快取檢查點
curl https://api.anthropic.com/v1/messages # rest of input

import anthropic

client = anthropic.Anthropic()

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

# 使用相同的輸入再次呼叫模型，直到快取檢查點
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  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'."
    }
  ]
});
console.log(response.usage);

// 使用相同的輸入再次呼叫模型，直到快取檢查點
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .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")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

{"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 呼叫中重複使用這個大型文本，而無需每次都重新處理。只改變使用者訊息可讓您在利用快取內容的同時提出有關該書的各種問題，從而實現更快的回應和提高的效率。

提示詞快取如何運作

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

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

這特別適用於：

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

預設情況下，快取的生命週期為 5 分鐘。每次使用快取內容時，快取都會以無額外成本的方式進行重新整理。

定價

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

如何實現提示詞快取

支援的模型

提示詞快取目前支援：

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

結構化您的提示詞

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

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

自動前綴檢查如何運作

您可以在靜態內容的末尾使用單一快取中斷點，系統將自動找到最長的匹配前綴。了解這如何運作有助於您最佳化快取策略。

三個核心原則：

1. 快取金鑰是累積的：當您使用 cache_control 明確快取一個區塊時，快取雜湊金鑰是透過依序雜湊對話中所有先前的區塊來生成的。這意味著每個區塊的快取取決於其前面的所有內容。

2. 向後順序檢查：系統透過從您的明確中斷點向後工作，按相反順序檢查每個先前的區塊來檢查快取命中。這確保您獲得最長的可能快取命中。

3. 20 區塊回溯視窗：系統只檢查每個明確 cache_control 中斷點之前最多 20 個區塊。在檢查 20 個區塊後仍未找到匹配項，它會停止檢查並移至下一個明確中斷點（如果有的話）。

範例：了解回溯視窗

考慮一個有 30 個內容區塊的對話，其中您只在區塊 30 上設定 cache_control：

• 如果您傳送區塊 31 且先前區塊沒有變更：系統檢查區塊 30（匹配！）。您在區塊 30 獲得快取命中，只需要處理區塊 31。

• 如果您修改區塊 25 並傳送區塊 31：系統從區塊 30 → 29 → 28... → 25（無匹配）→ 24（匹配！）向後檢查。由於區塊 24 未變更，您在區塊 24 獲得快取命中，只需要重新處理區塊 25-30。

• 如果您修改區塊 5 並傳送區塊 31：系統從區塊 30 → 29 → 28... → 11（檢查 #20）向後檢查。在 20 次檢查後仍未找到匹配項，它會停止查看。由於區塊 5 超出 20 區塊視窗，不會發生快取命中，所有區塊都需要重新處理。但是，如果您在區塊 5 上設定了明確的 cache_control 中斷點，系統會繼續從該中斷點檢查：區塊 5（無匹配）→ 區塊 4（匹配！）。這允許在區塊 4 進行快取命中，說明為什麼您應該在可編輯內容之前放置中斷點。

關鍵要點：始終在對話末尾設定明確的快取中斷點以最大化快取命中的機會。此外，在可能可編輯的內容區塊之前設定中斷點，以確保這些部分可以獨立快取。

何時使用多個中斷點

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

• 快取以不同頻率變更的不同部分（例如，工具很少變更，但背景資訊每天更新）
• 對快取內容有更多控制
• 確保快取最終中斷點之前超過 20 個區塊的內容
• 在可編輯內容之前放置中斷點以保證快取命中，即使在 20 區塊視窗之外發生變更

快取限制

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

• 1024 個權杖，適用於 Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4.5、Claude Sonnet 4、Claude Sonnet 3.7（已棄用）和 Claude Opus 3（已棄用）
• 4096 個權杖，適用於 Claude Haiku 4.5
• 2048 個權杖，適用於 Claude Haiku 3.5 和 Claude Haiku 3

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

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

追蹤快取效能

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

• cache_creation_input_tokens：建立新項目時寫入快取的權杖數。
• cache_read_input_tokens：此請求從快取檢索的權杖數。
• input_tokens：未從快取讀取或用於建立快取的輸入權杖數。

有效快取的最佳實踐

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

• 快取穩定、可重複使用的內容，如系統指令、背景資訊、大型背景資訊或頻繁的工具定義。
• 將快取內容放在提示詞的開頭以獲得最佳效能。
• 策略性地使用快取中斷點來分隔不同的可快取前綴部分。
• 在對話末尾和可編輯內容之前設定快取中斷點以最大化快取命中率，特別是在使用超過 20 個內容區塊的提示詞時。
• 定期分析快取命中率並根據需要調整您的策略。

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

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

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

疑難排解常見問題

如果遇到意外行為：

• 確保快取部分相同，並在呼叫中的相同位置用 cache_control 標記
• 檢查呼叫是否在快取生命週期內進行（預設 5 分鐘）
• 驗證 tool_choice 和影像使用在呼叫之間保持一致
• 驗證您快取的權杖數至少達到最小數量
• 系統自動在先前內容區塊邊界處檢查快取命中（在您的中斷點之前約 20 個區塊）。對於超過 20 個內容區塊的提示詞，您可能需要在提示詞中更早的位置添加額外的 cache_control 參數以確保所有內容都可以快取
• 驗證 tool_use 內容區塊中的金鑰具有穩定的順序，因為某些語言（例如 Swift、Go）在 JSON 轉換期間隨機化金鑰順序，破壞快取

使用思考區塊進行快取

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

與其他內容自動快取：雖然思考區塊無法用 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],
使用者：[Text response, 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 分鐘後傳送時。
• 當您想改進速率限制利用率時，因為快取命中不會從您的速率限制中扣除。

混合不同的 TTL

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

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

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

提示詞快取範例

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

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

常見問題