用 cache_control 做好 Claude prompt caching：5 分鐘與 1 小時快取成本怎麼算

Claude prompt caching 有一個漂亮的數字，也有一個很容易踩的坑：快取讀取只要正常輸入成本的 0.1×，但快取寫入比正常輸入更貴。Anthropic 目前文件列出的價格是：5 分鐘快取寫入為輸入價格的 1.25×，1 小時寫入為 2×，而所有啟用中的 Claude 模型，快取命中都是 0.1×（Anthropic prompt caching docs）。

這代表快取不只是延遲優化，而是定價功能。如果你的 app 會重複使用很長的 system prompt、工具 schema、範例包、政策包、檢索到的文件，或多輪狀態，你就該像衡量輸出 tokens 一樣，衡量快取寫入和讀取。

截至今天，2026 年 6 月 14 日，有個小波折：Anthropic 在 6 月 9 日推出 Claude Fable 5，接著在 6 月 12 日更新公告，表示 Fable 5 和 Mythos 5 的存取已暫停，他們正在努力恢復（Anthropic）。OneHop 也列出 anthropic/claude-fable-5，並標示支援 prompt cache，但目前在模型頁面上標為暫時無法使用（OneHop）。現在先把整合做好，讓 model id 可設定，等存取恢復時再切上去。

開發者真正需要的快取算術

Anthropic 的 prompt cache 會儲存 prompt 前綴。可重複使用的部分必須完全相同：tools、system content、messages 會依序被考慮，而快取會套用到標記了 cache_control 的區塊為止（Anthropic prompt caching docs）。

有用的定價模型其實很簡單。假設你的可重用前綴是 100,000 個輸入 tokens。

以 Claude Fable 5 來說，Anthropic 在發布文章中列出每百萬輸入 tokens 10 美元、每百萬輸出 tokens 50 美元，而 prompt caching 文件列出的 Fable 5 快取價格是：5 分鐘寫入 $12.50/M、1 小時寫入 $20/M、快取命中 $1/M（Anthropic，prompt caching docs）。

用 Anthropic 官方標價來算，那段 100k-token 前綴成本是：

• 正常輸入：$1.00
• 5 分鐘寫入：$1.25
• 1 小時寫入：$2.00
• 快取讀取：$0.10

所以如果同一段 100k-token 前綴在 TTL 內使用兩次，5 分鐘快取成本是 $1.25 + $0.10 = $1.35，不用快取則是 $2.00。1 小時快取兩次使用的成本是 $2.10，所以兩次呼叫會輸，但只要有第三次呼叫，或避免較長暫停後的冷寫入，就會贏。

這就是我在 production 採用的規則：熱迴圈預設 5 分鐘；當人會停頓、agents 會等工具，或 workflow 會在幾分鐘後恢復，就用 1 小時。

開啟快取的兩種方式

Anthropic 現在記錄了兩種做法。最快的路徑是自動快取：加上頂層 cache_control 欄位，Claude 會隨著對話成長，把中斷點往前推。更可控的路徑是明確中斷點：把 cache_control 放在穩定前綴的最後一個 content block 上（Anthropic prompt caching docs）。

自動快取很適合聊天歷史和 agent 狀態：

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url=os.getenv("ANTHROPIC_BASE_URL", "https://api.onehop.ai/v1"),
)

message = client.messages.create(
    model=os.getenv("CLAUDE_MODEL", "anthropic/claude-fable-5"),
    max_tokens=700,
    cache_control={"type": "ephemeral"},
    system="You are a senior backend engineer. Be concise and specific.",
    messages=[
        {"role": "user", "content": "My app uses FastAPI, Postgres, and Redis."},
        {"role": "assistant", "content": "Got it. What do you want to change?"},
        {"role": "user", "content": "Design a cache key strategy for user dashboards."},
    ],
)

print(message.content[0].text)
print(message.usage.model_dump())

這就是 OneHop 的轉換路徑：保留你的 Anthropic 風格請求，讓 base URL 可設定，然後指向 https://api.onehop.ai/v1。OneHop 的模型頁面也顯示 anthropic/claude-fable-5 作為 model id，並表示新使用者可獲得 10 美元免費額度，且不需要信用卡（OneHop）。如果你想走捷徑，打開 OneHop 上的 Claude Fable 5，然後用 10 美元免費額度開始。

當前綴穩定、但使用者訊息每次請求都會改變時，明確快取更好。把中斷點放在會變動的部分之前：

from anthropic import Anthropic
import os

client = Anthropic(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

response = client.messages.create(
    model="anthropic/claude-fable-5",
    max_tokens=500,
    system=[
        {
            "type": "text",
            "text": open("system_prompt.md").read(),
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "Review this migration plan for race conditions."}
    ],
)

print(response.usage.model_dump())

使用 1 小時 TTL 的 TypeScript 版本

當 app 有昂貴的靜態 context，而且實際上會出現閒置間隔時，就用 1 小時快取。想像這些情境：等待 CI 的 code review agents、人會暫停的客服 copilots、法律研究 session，或工具會跑好幾分鐘的多步驟資料分析。

Anthropic 文件把 1 小時 TTL 寫成 {"type":"ephemeral","ttl":"1h"}，並說明自動快取預設使用 5 分鐘（Anthropic prompt caching docs）。

import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const client = new Anthropic({
  apiKey: process.env.ONEHOP_API_KEY!,
  baseURL: process.env.ANTHROPIC_BASE_URL ?? "https://api.onehop.ai/v1",
});

const policyPack = fs.readFileSync("policy-pack.md", "utf8");

const msg = await client.messages.create({
  model: process.env.CLAUDE_MODEL ?? "anthropic/claude-fable-5",
  max_tokens: 800,
  system: [
    {
      type: "text",
      text: policyPack,
      cache_control: { type: "ephemeral", ttl: "1h" },
    },
  ],
  messages: [
    {
      role: "user",
      content: "Apply the policy pack to this refund request: customer used 3 of 10 seats.",
    },
  ],
});

console.log(msg.content);
console.log(msg.usage);

重點很無聊：不要把模型和 base URL 深埋在程式碼裡。兩者都放在環境變數。今天 Fable 5 的可用性仍在變動；你的整合應該能在不修改商業邏輯的情況下，fallback 到另一個啟用中的 Claude 模型。

usage 裡該監控什麼

Prompt caching 在你檢查 usage 欄位之前都是隱形的。Anthropic 表示，要驗證快取，可以檢查 cache_creation_input_tokens 和 cache_read_input_tokens 等欄位；如果兩者都是零，代表 prompt 沒有被快取，常見原因是沒有達到該模型的最低可快取長度（Anthropic prompt caching docs）。

每次請求都記錄這些：

const usage = msg.usage;

console.log({
  input: usage.input_tokens,
  output: usage.output_tokens,
  cacheCreate: usage.cache_creation_input_tokens,
  cacheRead: usage.cache_read_input_tokens,
});

對於較新的 usage 物件，Anthropic 文件也顯示快取建立會拆成依 TTL 區分的 buckets，例如 ephemeral_5m_input_tokens 和 ephemeral_1h_input_tokens。一開始先擷取完整 usage 物件。等你確定自己跑的是哪個 gateway 和 SDK 版本後，再做正規化。

好的 dashboard 會回答四個問題：

1. 有多少 tokens 被寫入快取？
2. 有多少 tokens 從快取讀取？
3. 各 route 的快取讀寫比是多少？
4. 哪些 prompts 會在閒置間隔後造成大型冷寫入？

如果 cache_creation_input_tokens 很高，而 cache_read_input_tokens 一直接近零，你的中斷點很可能放在會變動的內容之後。把它往前移。

5 分鐘還是 1 小時：看使用者行為選

緊密請求迴圈用 5 分鐘快取。每 20 秒呼叫工具的 coding agent、使用者很快會送 follow-up 的 chat app，或一批相似的分類工作，都應該從這裡開始。根據 Anthropic 文件，寫入溢價只有 1.25×，而且每次讀取都會免費刷新快取生命週期（Anthropic prompt caching docs）。

當昂貴前綴很可能在超過五分鐘後再次被使用，就用 1 小時快取。Human-in-the-loop workflows 是典型案例。長時間執行的 agents 也是：模型把工作送到外部系統、等待瀏覽器、輪詢 CI，或暫停等待核准。

不要快取很小的 prompts。Anthropic 記錄了依模型和平台不同的最低可快取 prompt 長度；對 Fable 5 來說，Claude API 的最低值列為 512 tokens，而 Bedrock 對某些模型有不同最低值（Anthropic prompt caching docs）。更短的 prompts 可能會直接處理，不會快取。

實用檢查清單：

• 把穩定內容放前面：tools、system prompts、examples、reference docs。
• 把會變動的資料放在快取前綴後面：timestamps、request ids、user text。
• 對話先從自動快取開始。
• 當你的 suffix 每次呼叫都會變，就切到明確中斷點。
• 只有在閒置間隔能合理化 2× 寫入成本時，才使用 1 小時 TTL。
• 先記錄 usage 欄位，再宣布勝利。

透過 OneHop 串起來，然後量測

最乾淨的整合是一行 endpoint 變更，加上用 env 設定模型選擇：

export ONEHOP_API_KEY="..."
export ANTHROPIC_BASE_URL="https://api.onehop.ai/v1"
export CLAUDE_MODEL="anthropic/claude-fable-5"

接著保留你的 Anthropic Messages 程式碼，並加上 cache_control。

OneHop 的 Fable 5 頁面目前宣傳低於官方標價的價格、10 美元免信用卡起始額度，以及該模型的 Anthropic Messages route（OneHop）。由於截至 Anthropic 6 月 12 日更新，Fable 5 存取仍暫時暫停，請把模型 fallback 當成 rollout 的一部分，而不是事後補救。

回報很單純。如果你的 app 會重複大型前綴，0.1× 的快取讀取會把 prompt engineering 變成 cost engineering。先從 5 分鐘快取開始。當 logs 顯示暫停後發生冷重寫，再把特定 workflows 移到 1 小時快取。如果你想在 Claude Fable 5 恢復可用後走捷徑，試試 OneHop 上的 Claude Fable 5，並用 10 美元免費額度開始。