Claude 提示詞快取

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [此处放置完整文本内容]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

提示词缓存的工作原理

1. 系统会检查是否已经缓存了最近查询中指定缓存断点之前的提示词前缀
2. 如果找到，就使用缓存版本，减少处理时间和成本
3. 否则，系统会处理完整提示词，并在开始响应时缓存前缀部分

• 包含大量示例的提示词
• 大量的上下文或背景信息
• 具有一致指令的重复任务
• 长时间的多轮对话

​

常見錯誤：寫了緩存卻「只寫不讀」

​

❌ 錯誤寫法：把每輪會變的問題放在斷點前面

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ 正確寫法：大文件放最前 + 斷點 + 問題放最後

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

實測對照（claude-opus-4-6，固定同一渠道，兩次調用間隔數秒）

1. 固定不變的大塊（參考文件、長上下文）放在 messages 用戶消息的最前面，cache_control 打在它末尾，這段內容一個字都不能動；
2. 每輪變化的問題/指令放到斷點之後（同一條 user 消息裡大文件之後，或後續消息）；多輪對話只往後追加，不要回頭修改歷史消息；
3. 開啟 thinking 時，歷史助手輪裡的思考塊要原樣回傳，否則前綴同樣會斷（見下文「無法緩存的內容」）；
4. 若塊小於最小緩存門檻（Opus 4.5/4.6、Haiku 4.5 為 4096 Token），即使標了 cache_control 也不會寫入緩存——這是預期行為，見下文「緩存限制」。

​

緩存定價

• 5 分鐘緩存寫入 Token 價格為基礎輸入 Token 價格的 1.25 倍
• 1 小時緩存寫入 Token 價格為基礎輸入 Token 價格的 2 倍
• 緩存讀取 Token 價格為基礎輸入 Token 價格的 0.1 倍
• 常規輸入和輸出 Token 按平台標準費率計價

​

如何實現提示詞緩存

​

支持的模型

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

構建提示詞結構

​

緩存限制

• Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5 和 Claude Opus 3 為 1024 個 Token
• Claude Haiku 3.5 和 Claude Haiku 3 為 2048 個 Token

• “ephemeral”：默認 5 分鐘生存期
• 1 小時緩存（Beta）：適用於需要更長緩存時間的場景

​

1 小時緩存持續時間（Beta）

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: extended-cache-ttl-2025-04-11" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

何時使用 1 小時緩存

• 批處理作業：處理大量具有共同前綴的請求
• 長時間會話：需要在較長時間內保持上下文的對話
• 大型文件分析：對同一文件進行多次不同類型的分析
• 代碼庫問答：在較長時間內對同一代碼庫進行多次查詢

​

混合不同的 TTL

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

可以緩存的内容

• 工具：tools 數組中的工具定義
• 系統消息：system 數組中的內容塊
• 消息：messages.content 數組中的內容塊，包括用戶和助手的對話輪次
• 圖片和文件：用戶對話輪次中 messages.content 數組的內容塊
• 工具使用和工具結果：用戶和助手對話輪次中 messages.content 數組的內容塊

​

無法緩存的内容

• 思考塊無法直接使用 cache_control 緩存。但是，當思考塊出現在之前的助手回合中時，可以與其他內容一起緩存。以這種方式緩存時，從緩存讀取時它們確實計為輸入 Token。
• 子內容塊（如引用）本身無法直接緩存。相反，緩存頂級塊。
• 空文本塊無法緩存。

​

跟踪緩存性能

• cache_creation_input_tokens: 創建新緩存條目時寫入緩存的 Token 數
• cache_read_input_tokens: 從緩存中檢索的 Token 數
• input_tokens: 未從緩存讀取或用於創建緩存的輸入 Token 數

​

有效緩存的最佳實踐

• 緩存穩定的、可用重用的內容，如系統指令、背景信息、大型上下文或常用工具定義
• 將緩存內容放在提示詞前面以獲得最佳性能
• 策略性地使用緩存斷點來分隔不同的可用前綴部分
• 定期分析緩存命中率並根據需要調整策略
• 對於長期使用的内容，考慮使用 1 小時緩存以獲得更好的成本效益

​

針對不同用例的優化

• 對話代理：減少長時間對話的成本和延遲，特別是那些有長指令或上傳文件的對話
• 編程助手：通過在提示詞中保留相關部分或代碼庫的摘要版本，改善自動完成和代碼庫問答
• 大文件處理：在提示詞中包含完整長篇材料 (包括圖片)，而不增加響應延遲
• 詳細指令集：共享廣泛的指令、程序和示例列表來微調 Claude 的響應。開發者通常在提示詞中包含一兩個示例，但使用提示詞緩存，你可以通過包含 20+ 個高質量答案的多元化示例獲得更好的性能
• 代理工具使用：提升涉及多個工具調用和迭代代碼更改的場景性能，每個步驟通常需要新的 API 調用
• 與書籍、論文、文件、播客記錄和其他長篇內容對話：通過在提示詞中嵌入整個文件，讓用戶能夠提問

​

常見問題解決

• 確保緩存部分在不同調用之間完全相同，並在相同位置標記了 cache_control
• 檢查調用是否在緩存生存期內（5 分鐘或 1 小時）
• 驗證 tool_choice 和圖片使用在調用之間保持一致
• 確認你緩存的 Token 數至少達到最小要求
• 雖然系統會嘗試使用緩存斷點之前位置的已緩存內容，但你可以使用額外的 cache_control 參數來保證查找提示詞前面部分的緩存，這對於包含很長內容塊列表的查詢可能很有用

​

緩存儲存和共享

• 組織隔離： 緩存在組織之間是隔離的。不同組織永遠不會共享緩存，即使它們使用相同的提示詞。
• 精確匹配： 緩存命中需要 100% 相同的提示詞段，包括標記有 cache control 的塊之前及其本身的所有文本和圖片。在緩存讀取和創建期間必須用 cache_control 標記相同的塊。
• 輸出 Token 生成： 提示詞緩存不會影響輸出 Token 生成。你收到的響應將與不使用提示詞緩存時完全相同。

​

在客戶端 / 平台中啟用 Claude 緩存

​

Dify（通過 Aihubmix 外掛）

1. 用 <cache>…</cache> 包裹要緩存的提示詞（固定不變的系統提示詞 / 長上下文），外掛會在該處自動轉換成 cache_control 斷點；
2. 在模型參數裡把「大消息自動緩存閾值」設為一個正整數：內容達到該 Token 閾值才會真正寫緩存（仍受下文「緩存限制」的最小緩存約束，Opus 4.5/4.6、Haiku 4.5 為 4096 Token），設 0 或留空則關閉。

​

Cherry Studio

1. 點擊 Aihubmix 供應商名稱右側的齒輪，打開「API 設定」（API Settings）：

2. 配置以下三項，客戶端會據此為 Claude 自動注入 cache_control：

• 緩存 Token 閾值（Cache Token Threshold）：內容超過該 Token 數才注入緩存斷點（設正數開啟，0 或留空關閉）；
• 緩存系統消息（Cache System Message）：開啟後給 system 消息打緩存斷點（適合緩存固定的長系統提示詞）；
• 緩存最後 N 條消息（Cache Last N Messages）：給最近 N 條消息打緩存斷點（適合多輪對話滾動緩存）。

​

常見問題（FAQ）

​

為什麼寫了緩存（cache_creation_input_tokens 很大）卻一直讀不到（cache_read_input_tokens 為 0）？

​

緩存最少需要多少 Token？

​

緩存有效期多久？能改成 1 小時嗎？

​

在 Dify / Cherry Studio 裡怎麼開緩存？

​

不同模型的支持情況

• 是否支持 Prompt Caching 賴於模型本身。
• 如果模型本身支持，並且不需要顯式聲明的參數，則通過 opanai 兼容格式轉發可以支持。
• Openai 默認支持 Prompt Caching，緩存不計費，緩存 Tokens 讀取費用減半，處於未復用狀態 5-10 分鐘之後會自動清除。文件
• Claude 需要原生的 cache_control: { type: "ephemeral" } 聲明，緩存費率為常規輸入的 1.25 倍（5 分鐘）或 2 倍（1 小時），緩存 Tokens 讀取費用為 0.1 倍，生命周期 5 分鐘或 1 小時。文件
• Deepseek V3 和 R1 原生支持，緩存費率為常規輸入的 1 倍，緩存 Tokens 讀取費用為 0.1 倍。文件
• Gemini 模型支持隱式緩存：
  • 隱式緩存：默認情況下為所有 Gemini 2.5 模型啟用。如果你的請求命中緩存，會自動傳遞成本節省。此功能自 2025 年 5 月 8 日起生效。上下文緩存的最低輸入 Token 數：Gemini 2.5 Flash 為 1,024，Gemini 2.5 Pro 為 2,048。
    • 提高隱式緩存命中率的技巧：
      • 將大塊的常見內容放在提示的前面。
      • 嘗試在短時間內發送前綴相似的請求。
    • 你可以在響應對象的 usage_metadata 字段中查看緩存命中的 Token 數量。
    • 成本節省是根據預填充緩存命中次數衡量的。只有預填充緩存和 YouTube 視頻預處理緩存支持隱式緩存。