Claude 提示詞緩存（Prompt Caching）入門：緩存時間、價格倍率與命中率

本文根據 Claude API 官方文檔《Prompt caching》整理，核對日期 2026-10-07。價格以倍率說明為主，各模型的具體單價見官方定價頁。

適用於誰

• 用 Claude API 做客服機器人、文檔問答、代碼助手，每次請求都帶着一大段相同的系統提示或資料，想省錢提速的開發者；
• 搜「claude prompt caching」「claude 緩存時間」「緩存命中率低」「緩存價格」的人；
• 想看懂 API 返回裏 cache_read_input_tokens 這些字段的人。

結論先說

1. 緩存的是「前綴」：按 tools → system → messages 的順序，從開頭一直到你標記 cache_control 的那個內容塊為止。下次請求的這段前綴一字不差，就能直接讀緩存。
2. 兩種開法：在請求頂層加一個 "cache_control": {"type": "ephemeral"} 就是自動緩存（多輪對話最省事）；也可以在具體內容塊上打斷點精細控制，一次請求最多 4 個斷點。
3. 時長：預設 5 分鐘，每次命中會免費續期；也可以選 1 小時（"ttl": "1h"）。
4. 價格倍率（官方）：5 分鐘緩存寫入 = 基礎輸入價 × 1.25；1 小時緩存寫入 = × 2；讀緩存 = × 0.1（個別模型更低：Opus 5.5 為 × 0.05，Fable 5.1 為 × 0.025）。斷點本身不收費。
5. 太短不緩存：不同模型有最短可緩存長度（512～4096 token 不等），不夠長時靜默不緩存、也不報錯——這是「命中率為 0」最常見的原因。

一、它是怎麼省錢的

發送帶緩存設定的請求時：

1. 系統先檢查這段前綴最近是否緩存過；
2. 緩存過就直接用，處理更快、費用更低；
3. 沒緩存過就完整處理一遍，並在回覆開始時把前綴寫進緩存。

適合的場景：提示詞裏有大量示例、很長的背景資料、重複執行的固定指令、長篇多輪對話、帶很多工具的智能體。官方還提到一個用法：有了緩存，可以在提示詞裏放 20 個以上高質素示例，而不用擔心每次都付全價。

緩存不影響輸出：用不用緩存，模型給出的回答是一樣的；緩存只作用於輸入部分。

二、最簡單的寫法：自動緩存

在請求頂層加 cache_control，系統會自動把斷點放在最後一個可緩存的內容塊上，對話變長時斷點也會自動後移：

python
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},          # 開啟自動緩存
    system="你是公司的客服助手。以下是完整的產品手冊：……（很長的內容）",
    messages=[
        {"role": "user", "content": "退貨流程是什麼？"},
    ],
)
print(response.usage)

多輪對話時的效果（官方示意）：

想用 1 小時緩存：cache_control={"type": "ephemeral", "ttl": "1h"}。

三、精細控制：在內容塊上打斷點

當不同部分變化頻率不同（比如工具定義幾乎不變、產品手冊每天變、對話每輪都變），可以在具體內容塊上放 cache_control：

python
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {"type": "text", "text": "你是公司的客服助手。"},
        {
            "type": "text",
            "text": "（很長的產品手冊全文……）",
            "cache_control": {"type": "ephemeral"},   # 緩存到這裏為止
        },
    ],
    messages=[{"role": "user", "content": "保修期多久？"}],
)

要點：

• 把不變的內容放前面：工具定義、系統指令、背景資料、示例在前，每次都變的內容（時間戳、用戶問題）在後；
• 斷點要放在「每次都相同」的最後一個塊上，而不是放在會變的塊上——官方特別指出，斷點放在含時間戳或用戶新消息的塊上，前綴永遠對不上，緩存永遠寫不進去也讀不出來；
• 一次請求最多 4 個斷點（自動緩存會佔用其中 1 個）；斷點多不會多收錢，你只為實際寫入和讀取的內容付費。

四、價格倍率

這些倍率會和批量處理（Batch API）折扣等其他價格因素疊加。各模型的基礎單價見官方定價頁。簡單理解：同一段前綴只要被讀取一次以上，通常就比不緩存划算。

5 分鐘還是 1 小時？官方建議：如果這段提示詞使用頻率高於每 5 分鐘一次，用 5 分鐘緩存就行（每次命中免費續期）；1 小時緩存適合「隔幾分鐘到一小時才會再用一次」的情況，比如子任務運行超過 5 分鐘、用戶可能過一會兒才回復。另外，緩存命中不計入速率限制，長緩存也有助於提高速率限制的利用率。同一請求裏混用兩種時，1 小時的緩存條目必須排在 5 分鐘的前面。

注意計時方式：有效期從寫入或讀取緩存的那次請求開始時算起，生成回覆的時間也計入。比如一次回覆流式輸出了 4 分鐘，下一次複用請求要在回覆結束後約 1 分鐘內發出，才趕得上 5 分鐘的有效期。

五、怎麼看有沒有命中

看響應裏的 usage（流式輸出時在 message_start 事件裏）：

總輸入 = cache_read + cache_creation + input_tokens。所以開了緩存後 input_tokens 往往很小，這不是少算了，而是大部分輸入走了緩存。

如果 cache_creation_input_tokens 和 cache_read_input_tokens 都是 0，說明這次根本沒緩存——最可能是沒達到最短長度。

六、最短可緩存長度（Claude API）

不夠長時，官方建議：如果只差一點，把可緩存的內容補到門檻以上通常是值得的，因為讀緩存比普通輸入便宜得多。

七、命中率低的原因排查

官方清單：

1. 前綴不完全一致：哪怕差一個字、一張圖都不行；用顯式斷點時，cache_control 的位置每次也要相同；
2. 超過有效期：兩次請求間隔超過 5 分鐘（或 1 小時）；
3. 改了會讓緩存失效的參數：

• 修改工具定義 → 整個緩存失效；
• 開關網頁搜尋、引用功能、fast 模式 → system 和 messages 緩存失效；
• 修改 tool_choice、增刪圖片、修改思考（thinking）配置、修改 effort → messages 緩存失效；

1. 沒達到最短長度；
2. 斷點放在了會變的塊上（見第三節）；
3. JSON 鍵順序不穩定：某些語言（如 Swift、Go）把對象轉 JSON 時會打亂鍵順序，導致工具調用塊每次都不一樣；
4. 並發請求：緩存條目要等第一個請求的回覆開始後才可用，並行發出的請求拿不到；需要命中就等第一個請求開始返回後再發後續請求；
5. 跨工作區：在 Claude API 上緩存按工作區隔離，不同工作區之間不共享。

官方還提供了「緩存診斷（Cache diagnostics）」功能，讓 API 對比連續兩次請求，告訴你前綴從哪裏開始不一致。

另外，在部分新模型上，想在對話中途追加系統指令又不破壞緩存，可以在 messages 末尾追加一條 role: "system" 消息，而不是修改頂層 system 字段（具體支持哪些模型見官方文檔）。

常見問題

Q：緩存會不會泄露給別人？

不會。官方說明緩存在組織之間完全隔離，即使提示詞一模一樣也不共享；在 Claude API 上還按工作區隔離。

Q：哪些內容能緩存？

工具定義、system 內容塊、用戶和助手的文本消息、用戶消息裏的圖片和文檔、工具調用和工具結果都可以。思考塊不能直接打 cache_control，但可以隨之前的助手消息一起被緩存；空文本塊不能緩存。

Q：Claude Code 也用提示詞緩存嗎？

用，而且是自動的。Claude Code 的緩存機制（訂閱用戶的緩存時長、什麼操作會讓緩存失效）見官方《How Claude Code uses prompt caching》，省 token 的做法詳見本站《Claude Code 上下文滿了怎麼辦：/compact、/clear 與省 token 技巧》。

Q：Python SDK 怎麼寫多輪對話？

詳見本站《Claude API Python 入門：安裝 SDK、第一個請求、流式輸出與多輪對話》，在 messages.create 裏加上 cache_control 即可。

參考資料

• Prompt caching（官方）：https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Cache diagnostics（官方）：https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics
• Pricing（官方）：https://platform.claude.com/docs/en/about-claude/pricing
• How Claude Code uses prompt caching（官方）：https://code.claude.com/docs/en/prompt-caching