完整記錄 Token 用量、模型版本、任務延遲、重試次數及快取命中，建立成本與效能儀表板，以單次任務成本、P95 延遲及快取命中率找出最佳配置。

讀完能做到：為每次 Agent 執行建立可追溯成本帳本，並在品質、延遲與預算之間做可驗證的選擇。

實作狀態：成本公式、P95 與快取指標為【本機核心已測試】；Gemini Spark 儀表板為【Spark 設計藍圖】。範例單價是虛構測試值，不是 Google 官方價格，正式計算必須保存當日官方 Price Snapshot。

「一個月多少錢」其實回答不了

同樣叫做文件摘要，有的任務讀 2,000 tokens，有的讀完整合約；有的首輪成功，有的重試三次。只看月底帳單，無法知道是哪個模型、Prompt 或 Agent 節點燒掉預算。

每個 Tool Call 至少記錄：

{
  "run_id": "RUN-027",
  "task_id": "TASK-901",
  "agent": "analysis",
  "model_id": "record-the-actual-model-id",
  "prompt_version": "analysis-v7",
  "input_tokens": 10000,
  "cached_tokens": 4000,
  "output_tokens": 1500,
  "latency_ms": 2100,
  "retry_count": 0,
  "price_snapshot": "pricing-2026-09-22"
}

Gemini API 的 usage_metadata 可提供輸入、輸出、思考與快取 Token 數[1]。不要用字數估 Token，也不要只記總量；缺少模型與價格版本，日後無法重算成本。

成本要扣掉快取，再加回快取費率

cost = ((input_tokens - cached_tokens) * input_rate
        + cached_tokens * cached_rate
        + output_tokens * output_rate) / 1_000_000

本機用虛構費率計算單次任務成本為 0.0115 貨幣單位；這只是驗證公式。快取命中率定義為 cached_tokens ÷ input_tokens，範例為 40%。Google 文件說明 context caching 適合重複使用的大型共同內容，實際費率、最低 Token 與支援模型仍應查當下官方文件[2]。

快取不是免費午餐。若文件版本已更新卻沿用舊快取，成本下降、答案反而過期。因此 cache key 要包含資料版本、Prompt 版本、模型 ID 與權限範圍；敏感內容還要設定 TTL 與刪除流程。

平均延遲會把尖峰藏起來

儀表板至少同時顯示 P50、P95、P99、錯誤率與重試率。本機十筆延遲的 P95 為 2100 ms。P95 的意思是約 95% 請求不超過該值，不代表每次都在 2.1 秒內完成。

Task → Agent spans → Token／Latency／Retry events
                  ↓
            Cost Aggregator
                  ↓
     Quality × Cost × P95 Dashboard

不能只追求最便宜。每組配置要同時對照 Day 26 的 F1、任務完成率與安全指標。若小模型成本少 40%，但關鍵條款 Recall 下降 8%，那不是最佳化，而是把成本轉成業務風險。

三種常見最佳化

第一，先檢索再生成，避免把整個資料庫塞進 Prompt。第二，把固定系統指令與共同長文放入可版本化快取。第三，依任務風險路由模型：低風險分類可用較快配置，高風險決策交給能力較高的模型與人工覆核。

任何模型降級、縮短 Context 或調低思考預算，都要重跑 Golden Dataset。品質低於門檻時不得因成本漂亮而放行；更換價格表只重算成本，不應改寫原始 Token 紀錄。

本機測試涵蓋 P95、Token 合法性、成本與快取率：

python outputs/day25_30_metrics.py
python -m unittest work/test_day25_30_metrics.py -v

小摘要

成本最佳化不是「少用 Token」四個字，而是知道哪個任務、哪個 Agent、哪次重試花了多少錢，並把費用與品質、延遲放在同一張圖上判斷。

三個讀者重要帶回重點

1. 每次呼叫都記錄模型、Prompt、Token、快取、延遲、重試與價格版本。
2. 用 P95 看使用者真正遇到的慢請求，不以平均值掩蓋尖峰。
3. 任何降成本方案都要重跑品質與安全評估；高風險配置變更需人工核准。

參考資料

[1] Google AI for Developers：Understand and count tokens

[2] Google AI for Developers：Context caching

[3] Google：Use Gemini Spark to manage tasks and workflows