Claude prompt caching——費率、usage 物件，以及為何閘道後方的命中率會下降

提示快取是代理程式帳單中最大的單一槓桿，也是最可能在無聲無息中未正常運作的項目。 正確標記後，請求中重複的部分會按輸入費率的十分之一計費。標記錯誤——或透過會重寫前綴的服務路由——則會按高於一般費率計費，因為你付費寫入了完全沒有人讀取的快取項目。

相關機制已在其他地方有完整文件。沒有任何地方說明的是，當請求經過閘道時會發生什麼變化，而這正是大多數讀者的情況。以下分別說明兩者。

機制簡述

你會標記穩定前綴——系統提示、工具結構描述或文件——提供者會儲存其處理結果。下一個前綴完全相同的請求會讀取它，而不是重新處理。

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

兩項特性完成所有工作，也造成所有麻煩。比對依據是前綴，因此任何前段變更都會使後續全部內容失效。項目也有存留時間，因此回合之間間隔很長的對話會重新建立，而不是讀取。

費用

第三欄是標準比例：讀取成本為輸入的十分之一。第四欄也同樣標準——快取寫入成本為輸入的 1.25×，也就是 Anthropic 為五分鐘項目列出的倍數；由於兩種比例都套用到 Kunavo 的輸入價格，因此相對 Anthropic 牌價的折扣都與模型輸入相同。Kunavo 與 Anthropic 不同之處在於一小時項目：Anthropic 將該寫入列為輸入的 2×，而 Kunavo 則按相同的 1.25× 計費。這對經常重建的工作負載尤其重要——長時間執行的代理程式、緩慢的對話，以及前綴頻繁變動的任何工作負載——因為在這些工作負載中，主導快取帳單明細的是寫入，而不是讀取。

兩個數值都會在呈現時從目錄讀取；相同來源定價表與Claude 計算器也會讀取這些數值——此頁沒有任何手動輸入的費率。

讀取使用量物件

不要從帳單推測快取行為；每個回應都會直接告訴你，三個權杖計數就是完整診斷結果。

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

為什麼經過閘道後命中率會下降

快取存在於建立它的上游端，而且前綴比對是精確的。這兩項事實結合後，會產生三種直接呼叫單一供應商時不會發生的失敗模式：

路由發生變更。 如果連續請求落在不同的上游端，第二個請求就找不到快取——第一個請求寫入的項目，從第二個請求執行的位置不可見。這在你自己的日誌中不明顯，只有當本應是讀取的請求顯示為快取建立計數時才會出現。這是最常見的單一原因，也就是為什麼能在上游端之間自由重新路由的閘道，可能每個權杖更便宜、每個工作階段卻更昂貴。

你的前綴之前被插入了某些內容。 重寫系統訊息、正規化工具定義或重新排序欄位的層會產生不同的前綴，而不同的前綴就會造成未命中。不會發生錯誤；帳單只會上升。

間隔時間超過了項目的存續時間。 如果代理程式在回合之間思考數分鐘，每次都可能重新建立。這是你的工作負載特性，而非閘道特性，但它會與第一種情況產生不良交互作用：重新建立也代表一次重新路由的機會。

三種情況的診斷方式相同——在一個工作階段中觀察cache_creation_input_tokens。數值平坦且很大，表示你正在重建。第一次很大、之後為零，表示運作正常。在 Kunavo 中，請求層級的成本與快取權杖計數位於使用量檢視中，而快取參考提供端點層級的詳細資訊。

如何處理

讓快取前綴真正保持穩定——每個請求中會變動的內容都放在標記區塊之後，絕不要放在之前。在可行的情況下，讓代理程式的回合更接近地批次處理，因為閒置時間是短生命週期項目的敵人。請以完整工作階段而非單一請求進行端到端測量：快取是序列的特性，單一請求估算無法看見它。Claude 權杖成本計算器設有快取權杖欄位正是這個原因——將其設為提示中真正重複部分的比例，月度數值才不會流於虛構。

常見問題