# 策展 · X (Twitter) 🔥🔥

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 作者：ClaudeDevs (@ClaudeDevs) · 平台：X (Twitter) · 日期：2026-05-19

> 原始來源：https://x.com/ClaudeDevs/status/2056434422229123106

## 中文摘要

Claude Console 推出快取診斷功能優化成本。

**核心功能與價值**
Anthropic 於 Claude Console 推出 Beta 階段的 Prompt 快取診斷（Prompt cache diagnostics）功能，旨在解決開發者在實作提示詞快取時，因快取未命中（cache miss）導致 Token 成本意外增加卻難以追蹤的問題。該功能透過比較連續請求的結構差異，能精確指出前綴變更的位置與原因，並符合 [Zero Data Retention (ZDR)](https://platform.claude.com/docs/en/build-with-claude/api-and-data-retention) 標準，系統僅建立輕量級指紋（包含雜湊值與 Token 計數估算），絕不儲存原始 Prompt 內容。

**診斷機制與實作方式**
開發者需在 API 請求中加入 Beta header `cache-diagnosis-2026-04-07` 方可啟用。系統會針對每個請求建立指紋並以回應的 `id` 作為鍵值，開發者需在後續請求中透過 `diagnostics` 參數傳入前一次回應的 `id`（首輪請求則傳入 `null`）進行比對。

- 實作流程：
    1. 在第一輪請求中將 `previous_message_id` 設為 `null` 以建立快取。
    2. 後續輪次中，將前一次 API 回應的 `id` 帶入 `diagnostics` 參數。
    3. 透過 SDK 存取回應中的 `diagnostics` 物件以讀取診斷結果。

- cURL 請求範例：
```bash
curl -sS --fail-with-body https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: cache-diagnosis-2026-04-07" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are an AI assistant analyzing a large document. <document>...</document>",
    "messages": [{"role": "user", "content": "Summarize section 1."}],
    "diagnostics": {"previous_message_id": null}
  }'
```

**診斷結果解讀與修正建議**
診斷資訊會隨 `message_start` 事件回傳，開發者可根據 `cache_miss_reason` 的 `type` 欄位進行針對性優化：

- `model_changed`：模型不一致，應確保對話期間模型固定。
- `system_changed`：系統提示詞不一致（如動態時間戳記），應將系統提示詞設為位元組穩定（byte-stable）的常數，動態資料移至首個 `user` 訊息。
- `tools_changed`：工具定義或順序變更，應確保工具列表與序列化格式固定。
- `messages_changed`：訊息歷史被修改，應將歷史視為「僅追加」（append-only），並原樣回傳 `assistant` 內容與工具結果。
- `previous_message_not_found`：找不到指紋，可能因跨工作區請求或間隔過久，應縮短連續請求的時間間隔。
- `unavailable`：診斷資訊不可用，可能因 `tool_choice`、`thinking` 等參數變更或對話過長導致。

**多語言 SDK 支援**
官方提供多種語言的實作支援，開發者可參考以下邏輯：
- **Python**：使用 `client.beta.messages.stream`，並透過 `r2.diagnostics` 存取結果。
- **TypeScript**：透過 `stream.finalMessage()` 取得最終診斷狀態。
- **Go**：使用 `anthropic.BetaDiagnosticsParam` 進行設定。
- **Java**：透過 `BetaDiagnosticsParam.builder()` 傳入 `previousMessageId`。
- **PHP**：使用 `(new BetaDiagnosticsParam)->withPreviousMessageID($prevId)`。
- **Ruby**：直接在 `client.beta.messages.create` 中傳入 `diagnostics` Hash。
- **C#**：透過 `TryPickStart` 事件擷取 `diagnostics`。

**注意事項與限制**
- 該功能目前僅支援 Claude API，不支援 Amazon Bedrock 或 Vertex AI。
- 診斷屬「盡力而為」（best-effort），不會阻塞或導致請求失敗。
- 若 `diagnostics` 為 `null` 但 `cache_read_input_tokens` 數值偏低，建議參考 [1-hour cache TTL](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#1-hour-cache-duration) 縮短請求間隔。
- 詳細技術文件可參閱 [Claude Console 使用說明](https://platform.claude.com/usage/cache) 與 [官方技術文件](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics)。

## 標籤

功能更新, LLM, Anthropic, Claude