Claude API Prompt Caching 教學：大幅降低 Anthropic API 費用

在 AI 應用開發中，Claude Prompt Caching 是降低 Anthropic API 費用最有效的手段之一。截至 2026 年 10 月，快取命中時的輸入費用只有原價的 10%，在 Claude Sonnet 5.5 與 Opus 5.5 上更只要 5%。

查看相關日報

長上下文處理在企業級 AI 應用中已是常態。問題在於，每次請求都要重新處理龐大的系統提示詞、工具定義與歷史對話，API 費用因此快速攀升。Anthropic 的 Prompt Caching 功能直接解決這個痛點：把重複使用的提示詞前段快取起來，後續請求直接沿用，成本與延遲同步下降。本文從運作原理到進階技巧，提供完整的實作指南。

什麼是 Claude Prompt Caching？核心概念與優勢

Claude Prompt Caching 讓 API 可以從提示詞中某個「前綴（prefix）」接續處理。官方文件說明的運作方式是：

1. 系統檢查到快取斷點（cache breakpoint）為止的提示詞前綴，是否已經被最近的請求快取過。
2. 如果有，就直接使用快取版本，減少處理時間與費用。
3. 如果沒有，就處理完整提示詞，並在回應開始時把這段前綴寫入快取。

費用因此分成三種：寫入快取時比一般輸入貴 25%（5 分鐘快取），讀取快取時只要一般輸入的 10%，Claude Sonnet 5.5 與 Opus 5.5 是 5%，Claude Fable 5.1 是 2.5%；斷點以外沒被快取的內容照一般輸入計價。

官方列出最適合使用快取的情境包括：含有大量範例的提示詞、大量背景資料、指示固定的重複性任務，以及很長的多輪對話。對客服機器人、程式碼助手或文件問答而言，只要前段內容不變，快取命中後的每次請求輸入成本都會大幅下降。

事前準備：環境設定與 API 基礎

取得 API 金鑰

你需要有效的 Anthropic API 帳號與金鑰。請用環境變數 ANTHROPIC_API_KEY 儲存，避免硬編碼進程式碼導致外洩。

安裝 Python SDK

pip install anthropic

使用 Node.js、Java 或 Go 的開發者，請確認使用新版的官方 SDK，才能正確傳入 cache_control 參數。

確認模型支援

官方文件寫明，Prompt Caching（自動與手動兩種）支援所有現行的 Claude 模型。截至 2026 年 10 月，主力模型是 Claude Fable 5.1、Opus 5.5、Sonnet 5.5 與 Haiku 5.5，API 模型 ID 分別為 claude-fable-5-1、claude-opus-5-5、claude-sonnet-5-5、claude-haiku-5-5。舊文章常見的 claude-sonnet-4-20250514 已於 2026 年 6 月 15 日退役，Claude 3.5 Sonnet 與 Claude 3.5 Haiku 也都已退役，程式碼裡如果還寫著這些 ID，要換成現行模型。

Step 1：啟用 Prompt Caching 的兩種方式

方式一：自動快取（最簡單）

在請求最外層加一個 cache_control，系統會自動把斷點放在最後一個可快取的區塊，對話越長，斷點就自動往後移：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="你是一位專業的程式設計助手，請一律使用繁體中文回答，並在程式碼中加上詳細註解。",
    messages=[
        {"role": "user", "content": "請解釋 Python 中的裝飾器是什麼？"}
    ],
)

print(response.content[0].text)
print(response.usage)

官方建議多輪對話先從自動快取開始，因為不必自己管理斷點位置。

方式二：手動指定斷點

想精確控制哪些內容被快取，就把 cache_control 放在個別區塊上。快取前綴的順序固定是 tools → system → messages，靜態內容（工具定義、系統指示、背景資料、範例）要放在最前面：

system_prompt = """你是一位專業的程式設計助手。
請始終使用繁體中文回答。
請在回答程式碼時，加上詳細的註解。"""

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": system_prompt, "cache_control": {"type": "ephemeral"}}
    ],
    messages=[
        {"role": "user", "content": "請解釋 Python 中的裝飾器是什麼？"}
    ],
)

一個請求最多可以設 4 個斷點。"ephemeral" 是目前唯一的快取類型，預設存活 5 分鐘，每次被讀取時會免費重新計時。

哪些內容適合放入快取

• 工具定義：tools 陣列裡的定義
• 系統提示詞：角色、行為規範、輸出格式
• 參考資料：產品手冊、程式碼庫摘要、長文件，也包括使用者訊息中的圖片與文件
• 前段對話歷史：多輪對話中已經固定的部分

使用者當下的輸入、時間戳記這類每次都會變的內容，不要放在斷點之前。

Step 2：實作範例與費用對比分析

完整範例：長上下文場景

以程式碼助手為例：專案結構說明是靜態的，使用者問題是動態的。斷點要放在「最後一個每次都相同的區塊」上，也就是專案說明，而不是使用者問題：

import anthropic

client = anthropic.Anthropic()

# 靜態的專案結構說明（適合快取）
project_context = """
專案結構：
- src/
  - main.py
  - utils.py
- tests/
  - test_main.py
...（假設這裡有數千字的專案說明）
"""

# 動態的使用者問題
user_question = "請幫我修改 main.py 中的 login 函數，增加錯誤處理機制。"

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    system=[{"type": "text", "text": "你是一位資深後端工程師。"}],
    messages=[
        {"role": "user", "content": [
            {"type": "text", "text": project_context, "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": user_question}
        ]}
    ],
)

print(message.content[0].text)

這裡斷點放在 project_context 上，快取的範圍就涵蓋 system 加上專案說明。

最小快取長度

太短的提示詞即使加了 cache_control 也不會被快取，而且不會回傳錯誤。截至 2026 年 10 月，官方列出的最小可快取長度：Fable 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5 為 512 tokens；Opus 4.8、Sonnet 4.6 為 1,024 tokens；Opus 4.7 為 2,048 tokens；Haiku 4.5 為 4,096 tokens。

解讀 usage 欄位

回應的 usage 欄位（串流模式則在 message_start 事件中）有三個欄位要看：

• cache_creation_input_tokens：這次寫入快取的 token 數
• cache_read_input_tokens：這次從快取讀取的 token 數
• input_tokens：沒有讀取快取、也沒有寫入快取的 token 數，也就是最後一個斷點之後的內容

如果 cache_creation_input_tokens 和 cache_read_input_tokens 都是 0，代表這次沒有快取，最常見的原因是內容沒達到最小長度。

費用對比

以 Claude Sonnet 5.5 為例，官方定價為一般輸入每百萬 tokens 2 美元、5 分鐘快取寫入 2.50 美元、快取讀取 0.10 美元。假設系統提示詞加專案上下文共 10,000 tokens：

如果每天 10,000 次請求、流量穩定讓快取持續命中，30 天下來這段固定內容的輸入費用約從 6,000 美元降到 300 美元左右。第一次寫入比不用快取貴 25%，所以只會用一次的內容不值得快取。

Step 3：進階技巧與最佳實踐

最大化快取命中率

快取命中的前提是斷點之前的內容完全一致，包含所有文字與圖片。核心策略只有一個：嚴格分離靜態與動態內容。把角色定義、格式規則、靜態知識放在前面並設斷點；使用者輸入、即時資料一律放在斷點之後。在程式碼中把系統提示詞定義為常數，避免每次重新組字串。

官方文件也點出另一個容易漏掉的地方：Swift、Go 等語言在轉 JSON 時可能打亂 key 的順序，tool_use 區塊的 key 順序不固定也會讓快取失效。

避免常見陷阱

斷點放在每次都會變的區塊上：官方文件特別舉了這個例子。如果最後一個區塊含有時間戳記或使用者訊息，你又把斷點設在這裡，每次請求都會寫入新的快取，卻永遠讀不到，等於白付寫入費。正確做法是把斷點移到最後一個不變的區塊。

對話太長超出回溯範圍：系統只會從斷點往回找 20 個區塊。對話每輪新增的區塊太多時，可以在前面再加一個斷點。

改了會讓快取失效的設定：修改工具定義會讓整個快取失效；開關網頁搜尋或引用功能會讓系統與訊息的快取失效；改變 tool_choice、增減圖片、調整思考設定或 effort 參數，則會讓訊息部分的快取失效。

5 分鐘不夠用：1 小時快取

如果兩次請求的間隔可能超過 5 分鐘（例如使用者回覆比較慢，或代理任務要跑比較久），可以改用 1 小時快取：

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

1 小時快取的寫入費用是一般輸入的 2 倍。官方建議，如果同一段提示詞使用頻率高於每 5 分鐘一次，繼續用 5 分鐘快取即可，因為每次讀取都會免費續期。

預熱快取，降低首字延遲

對延遲敏感的應用，可以在使用者真正發問之前先送一個 max_tokens: 0 的請求，把系統提示詞或工具定義寫進快取，API 會在寫完快取後立即回傳、不產生任何輸出。這種預熱請求要用手動斷點，不能同時開啟 stream: true。

搭配串流模式

需要即時回饋的應用可以同時使用串流與 Prompt Caching，快取用量會出現在 message_start 事件的 usage 欄位中。要注意快取的存活時間從請求開始時起算，回應串流本身花掉的時間也算在內：如果一次回應花了 4 分鐘，下一次請求必須在約 1 分鐘內送出，才能命中 5 分鐘快取。

常見問題 FAQ

Prompt Caching 支援哪些 Claude 模型？

官方文件寫明支援所有現行的 Claude 模型。截至 2026 年 10 月，主力為 Claude Fable 5.1、Opus 5.5、Sonnet 5.5 與 Haiku 5.5。Claude 3.5 Sonnet、Claude 3.5 Haiku 與 Claude Sonnet 4（claude-sonnet-4-20250514）都已在 Claude API 上退役，舊程式碼要換成現行模型 ID。

快取會保留多久？

預設 5 分鐘，每次被讀取時會免費重新計時；如果需要更長，可以設定 "ttl": "1h" 改用 1 小時快取，寫入費用是一般輸入的 2 倍。時間從寫入或讀取快取的那個請求開始時起算。快取過期後，下次請求會重新寫入，再付一次寫入費用。

如何監控快取命中率？

解析 API 回應的 usage 欄位即可計算：快取命中率＝cache_read_input_tokens ÷（cache_read_input_tokens＋cache_creation_input_tokens＋input_tokens）。如果 cache_creation_input_tokens 與 cache_read_input_tokens 都是 0，代表沒有快取，先確認內容是否達到最小長度。官方也提供快取診斷（cache diagnostics）功能，可以讓 API 比對連續兩次請求，指出提示詞是從哪個部分開始不同。

下一步

Claude Prompt Caching 是控制 AI 應用成本的基礎工具。掌握之後，可以進一步研究 1 小時快取與快取預熱的搭配，或結合批次處理（Batch API）降低非即時任務的成本。模型定價與功能會隨新模型推出而調整，上線前記得對照 Anthropic 官方的定價頁與 Prompt Caching 文件，確認使用中的模型 ID 與費率。