Claude prompt caching 損益平衡怎麼算？

Prompt caching 尚未節省成本前的費用

Prompt caching 可讓 Claude 重複使用 prompt 的前段內容，而不必在每次呼叫時重新讀取。整體判斷取決於模型基本輸入價格的兩個倍數。截至 August 2026，5 minute lifetime 的 cache write 費用是基本輸入價格的 1.25x，1 hour lifetime 則是 2x。cache read 的費用是 0.1x。這些倍數適用於所有模型，因此即使每個 token 的價格變動，下方的損益平衡點也不會改變。

這項取捨是現在支付附加費，以換取之後的折扣。你只需支付一次額外費用來儲存 prefix。之後每個以完全相同 bytes 開頭的請求，該部分只需支付正常輸入價格的十分之一。如果 prefix 在其 lifetime 內從未重複使用，就會白白多支付 25 percent 的費用。

只用一行代數式求損益平衡點

將未使用快取時，前綴的基本輸入成本記為 B。未使用快取時，N 次請求的成本為 N 乘以 B。使用 5 分鐘快取時，第一個請求會以 1.25B 寫入前綴，其餘 N 減 1 次請求則以 0.1B 讀取該前綴。令兩者相等，可得 0.9N = 1.15，因此 N = 1.28。第二個請求的成本就已低於完全不使用快取的情況。

以 1 小時快取的 2 倍寫入成本重複計算，可得 0.9N = 1.9，因此 N = 2.11。長時間快取需要 2 次讀取才會達到損益平衡，因此不是預設選項。

下圖以 Claude Opus 5 的 20,000 token 前綴計算成本。Claude Opus 5 截至 August 2026 的基本輸入費率為每百萬 token $5。若使用每百萬 token $3 的模型，請將所有數值乘以 0.6。曲線形狀不會改變。

[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

單獨執行 1 次請求時，未使用快取的成本為 $0.10，使用快取則為 $0.125，因此對只執行 1 次的 prompt 使用快取只會增加成本。執行第 2 次請求時，5 分鐘快取的成本為 $0.135，未使用快取則為 $0.20。此時 1 小時快取仍較高，成本為 $0.21，未使用快取則同樣為 $0.20；直到第 3 次請求才低於未使用快取的成本：$0.22，未使用快取則為 $0.30。執行 20 次請求時，成本差距為未使用快取的 $2.00，相較於 5 分鐘快取的 $0.315。

快取命中也會更新項目的有效期間，因此價格表將該欄位稱為 cache hits and refreshes。對於流量繁忙的 endpoint，5 分鐘項目會持續以讀取價格維持有效，不會過期；1 小時有效期間只有在流量確實存在間隔時，才值得其 2 倍的寫入成本。

低命中率的成本

實際流量會出現未命中。請求未命中快取，但仍包含 breakpoint 時，會按照寫入計費。因此，合理的建模方式是將成本表示為命中率的函數。下方圖表以 1,000 個請求為基準，每個請求都包含相同的 20,000 token 前綴。

[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

命中率為 0% 時，費用為 $125.00，而不是 $100.00；1 hour cache 會讓帳單加倍至 $200.00。解方程式 1.25 減去 1.15h 等於 1，可得 5 minute cache 約在命中率 22% 時開始節省費用。這也是為什麼命中率達到 25% 時，費用已是 $96.25。以相同方式計算 2x write，可得 1 hour cache 的門檻約為 53%。因此，命中率 50% 時，費用仍為 $105.00，高於未快取的基準線。命中率 90% 時，兩者分別為 $21.50 和 $29.00。命中率 99% 時，短期快取的費用降至 $11.15，接近未快取價格十分之一的下限。

命中率是應監測的數值，因為前綴大小固定後，這是唯一可控制的輸入。

哪些前綴值得設定快取斷點

一次請求最多可包含 4 個快取斷點，因此問題在於哪些區塊值得設定斷點。候選區塊必須在不同請求間逐位元組相同，且大小足以產生影響。下圖以 5 分鐘快取、90% 命中率為條件，計算 1,000 次請求中 4 種常見結構的成本。

[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

僅含 2,000 個 token 的系統提示，與未快取的 $10.00 相比，每 1,000 次請求可節省 $7.85。大量請求時確實可省下費用，但這還不是快取有趣的原因。加入工具定義後，前綴長度達到 8,000 個 token，可節省 $31.40。每次請求都會針對內容提問的 25,000 token 政策文件，可節省 $98.12。最後一列會改變架構：120,000 個 token 的程式碼庫或對話記錄內容，未快取時成本為 $600.00，快取後為 $129.00，可節省 $471.00。

節省金額只會隨前綴大小與命中率增加，不受其他因素影響。這也改變了哪些內容值得放入提示的判斷：100 萬個 Claude token 的實際成本 對於傳送超過 1 次的內容，成本會降至標價的十分之一。

每月帳單上的呈現方式

下圖採用上文的 8,000 token 前綴、system prompt 及工具定義，設定 90 percent 命中率，再依每月請求量換算。

[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

每月 10,000 次請求可節省 $314.00，也就是 $400.00 與 $86.00 的差額。每月 100,000 次請求可節省 $3,140.00。每月 1 million 次請求的未快取輸入費用為 $40,000.00，快取可從中省下 $31,400.00。以上僅計算輸入 token。輸出會另外計價，快取不會降低輸出費用。在向他人承諾帳單可降低 90 percent 前，應記住這一點。快取也是在 VPS 上控制 AI agent 費用的整體做法之一，詳見 控制 VPS 上 AI agent 的費用。

如何證明快取正在運作

不要只相信設計。請查看回應中的 usage 區塊。每個 Messages API（application programming interface）回應都會回報寫入的快取 token、讀取的快取 token，以及必須處理的新 token 數量。

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

使用相同文件和不同問題執行兩次。第一次呼叫會回報非零的 cache_creation_input_tokens，而 cache_read_input_tokens 為 0。第二次呼叫則相反，因為已找到前綴。input_tokens 只計算最後一個 breakpoint 之後的 token，因此正常的第二次呼叫中，數值通常很小，通常只有新的 user message。

在 shell 中，也可以針對已儲存至 request.json 的 request body 執行相同檢查：

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

正常的第二次呼叫會輸出類似以下內容：

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

其中一行會顯示實際結果。如果 cache_read_input_tokens 在多次呼叫中都維持為 0，表示每次都支付 1.25x 的寫入成本，卻沒有取得任何快取內容。

若要設定 1 hour 的存留時間，breakpoint 會帶有存留時間（time to live，TTL）：

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

也可以使用自動快取：在 request 頂層加入單一 cache_control 欄位，之後由 API 隨著對話增長自動管理 breakpoint。這會占用四個 breakpoint slot 其中之一。請先從這種方式開始。只有在需要精確決定邊界位置時，再改用明確的 breakpoint。

會摧毀命中率的排序規則

快取會從請求開頭逐位元組比對前綴，而請求會依固定順序組成：先是 tools，再來是 system，最後是 messages。任一層發生變更，都會使該層及其後的所有內容失效。即使沒有修改訊息歷程，只要編輯一項工具說明、system prompt 及整個訊息歷程也會一併失效。

因此只有一項規則，沒有例外：每次呼叫都會變動的內容，必須放在所有不會變動的內容之後。

最常見的問題是時間戳記。在 system prompt 頂端加入 Current time: 2026-08-03T14:07:11Z 這一行，會使命中率固定為 0%，因為每次呼叫的前綴雜湊都不同，先前的項目永遠無法與其相符。請將它移到 user message 的末尾。工作階段識別碼或每次請求使用的 nonce 也會以相同方式造成問題，修正方法相同。每次請求不同的擷取文件也應放在快取區塊之後，否則會讓所有穩定內容都位於會移動的邊界之後。

第二個問題是將斷點放在會變動的區塊上。快取會在斷點寫入；因此，如果該區塊每次都不同，就不會儲存任何穩定內容，而回溯查找只會找到先前請求在各自移動斷點寫入的項目。請將 cache_control 放在跨請求內容完全相同的最後一個區塊上。

第三個問題是變更了你未視為 prompt 內容的參數。不同的 model 會使用不同的快取。變更 tool choice 會使 system 層及其後的內容失效。新增或移除 tool 會使所有內容失效。

最短前綴與靜默無操作

短於模型最低要求的前綴不會進入快取，而且不會提供任何提示。沒有錯誤，也沒有警告。請求會成功，兩個計數器都會顯示 0。截至 2026 年 8 月，已公布的最低要求如下：

• Claude Opus 5 和 Claude Fable 5：512 tokens
• Claude Sonnet 5 和 Claude Opus 4.8：1,024 tokens
• Claude Haiku 4.5：4,096 tokens

如果您認為某個請求應已使用快取，但兩個計數器都顯示 0，請先檢查前綴長度。這也是最低成本的模型不一定最適合快取工作負載的原因。Haiku 4.5 需要比 Opus 5 長 8 倍的前綴，快取才會啟用。因此，長度為 2,000 tokens 的系統提示會在其中一個模型上進入快取，卻會在另一個模型上遭到靜默忽略。

Claude Code 會為你快取的內容，以及無法快取的內容

Claude Code 會快取自身的前綴。系統提示與工具定義位於每個請求的最前端，不會移動，因此只會寫入一次，並在工作階段的其餘時間讀取快取內容。這就是為什麼長時間工作階段的每回合成本遠低於內容大小所顯示的數值，也會反映在 Claude Code 如何回報 token 使用量 所述的計數器中。

若要在內容開頭附近編輯，快取就無法提供協助。對話歷程只能附加內容，因此一般的新回合會延長已經快取的前綴。在工作階段早期讀取的檔案若遭到修改，該前綴中間的內容便會變更，變更之後的每個 token 都必須重新寫入。長時間閒置也會產生相同結果，因為快取項目會過期，下一回合必須完整寫入。這兩種情況都不是錯誤，而是前綴規則依照設計運作的結果。

如果你改為撰寫自己的 client，應在第一個請求時就套用正確的配置，而不是事後修改：依照 在 VPS 上建立第一個 Claude API 應用程式 的方式建立呼叫，先放置穩定區塊，最後放置易變區塊。

失敗情況與可觀察到的現象

每次呼叫都是寫入。 每次請求中的 cache_creation_input_tokens 都是非零，而 cache_read_input_tokens 維持 0。斷點前或斷點處的某項內容在各次呼叫之間發生變化。連續發出兩次請求，分別列印組合後前綴的前 200 個字元，並直接比較。

兩個計數器都是 0。 前綴短於模型的最低要求，或 cache_control 欄位未傳送至 API。先計算前綴的 token 數量，再記錄實際送出的請求本文。

讀取先正常，之後停止。 先連續命中，接著發生一次寫入，之後又恢復命中。這表示請求間隔超過了生命週期。接受這次寫入；確認命中率超過 53 percent 後，再改用 1 hour TTL。

部署後命中率下降。 工具說明遭到編輯，或模型有所變更。這兩種情況都會使整個前綴失效。每次部署變更 prompt 後，預期會先出現一輪成本較高的寫入。

啟用快取後帳單金額上升。 命中率低於損益平衡點。在 5 minute cache 中，低於約 22 percent 時，不使用快取傳送前綴反而較省；在 1 hour cache 中，低於約 53 percent 時也是如此。

FAQ

Prompt 必須重複使用幾次，快取才值得？

在 5 minute cache 中，使用 1 次就值得。寫入成本是基本輸入成本的 1.25x，讀取成本是 0.1x。因此，N 次未快取請求的成本為 N；N 次使用快取的請求成本為 1.25 加上 0.1 乘以 N 減 1。兩者在 N = 1.28 時相等，因此第 2 次請求就已經節省成本。1 hour cache 的寫入成本為 2x，兩者在 N = 2.11 時相等，因此需要 2 次讀取。

為什麼 cache_read_input_tokens 一直是 0？

先檢查前綴長度：低於模型最低長度時，系統會略過快取，且兩個計數器都會顯示 0。截至 August 2026，Claude Opus 5 的最低長度為 512 tokens，Claude Haiku 4.5 則為 4,096 tokens。若前綴長度足夠，請檢查斷點所在位置或之前是否有每次呼叫都會變動的內容，例如 system prompt 中的時間戳記或工作階段識別碼。若計數器原本正常，之後停止增加，表示請求之間的間隔超過快取存留時間。

Prompt caching 會改變 Claude 的回答嗎？

不會。快取會儲存你先前傳送之 tokens 的處理結果，模型看到的 prompt 仍然相同。這是計費與延遲功能，不會改變模型行為。因此，你可以在已正常運作的 prompt 上啟用此功能，而不必重新執行評估。

我應該支付 1 hour cache 的費用嗎？

只有在流量間隔會超過 5 minutes，且命中率仍可達到約 53 percent 時，才值得使用。未命中時，2x 的寫入成本是 1.25x 寫入成本的 2 倍。5 minute cache entry 每次命中都會更新，因此穩定的流量可持續維持快取，只需支付讀取價格，不必支付較長存留時間的費用。