Token Stats：成本視角的統計口徑與圖表解讀
你已經把客戶端接進 Antigravity Tools 了，但「到底誰在燒錢、貴在哪、是不是某個模型突然飆了」通常很難靠直覺判斷。這一課只做一件事：把 Token Stats 頁裡的資料口徑講清楚，並教你用圖表快速定位成本問題。
學完你能做什麼
- 說清楚 Token Stats 的資料來自哪裡（什麼時候會記錄、什麼情況下會缺失）
- 按小時/日/週切換觀察視窗，避免「只看一天」導致誤判
- 在「按模型/按帳號」兩種視圖下，用趨勢圖找異常峰值
- 用 Top 列表鎖定最貴模型/帳號，再回到請求日誌追根因
你現在的困境
- 你感覺調用變貴了，但不知道是模型變了、帳號變了，還是某天突然量大
- 你看到了
X-Mapped-Model，但不確定統計到底按哪個模型口徑算 - Token Stats 裡偶爾是 0 或「暫無資料」，不知道是沒流量還是沒統計到
什麼時候用這一招
- 你要做成本優化：先把「誰最貴」量化出來
- 你在排查突發限流/異常：用峰值時間點去對照請求日誌
- 你在做模型路由/配額治理配置變動後，想驗證成本是否按預期下降
什麼是 Token Stats？
Token Stats是 Antigravity Tools 的本地用量統計頁：代理在轉發請求後，會嘗試從響應 JSON 或流式資料中提取 usage/usageMetadata 裡的 token 數，並把每次請求按帳號與模型寫入本機 SQLite（token_stats.db），最後在 UI 裡按時間/模型/帳號彙總展示。
先說明一個容易踩的點
Token Stats 的「模型」口徑來自你請求裡的 model 欄位（或 Gemini 的 /v1beta/models/<model> 路徑解析），不等於路由後的 X-Mapped-Model。
🎒 開始前的準備
- 你已經跑通過一次代理調用（不會只停留在
/healthz探活） - 你的上游響應會返回可解析的 token 用量欄位（否則統計會缺失）
推薦搭配閱讀
如果你正在用模型映射把 model 路由到別的物理模型，建議先看 模型路由：自訂映射、萬用字元優先順序與預設策略，再回來看「統計口徑」會更直觀。
核心思路
Token Stats 的資料鏈路可以拆成三段：
- 代理中介軟體嘗試從響應裡提取 token 用量（相容
usage/usageMetadata，流式也會解析） - 如果同時拿到了
account_email + input_tokens + output_tokens，就寫入本機 SQLite（token_stats.db） - UI 透過 Tauri
invoke(get_token_stats_*)拉取聚合資料，按小時/日/週展示
跟我做
第 1 步：先確認你「有流量」
為什麼 Token Stats 統計來自真實請求。只啟動代理但沒發過一次模型請求，頁面就會顯示「暫無資料」。
做法：複用你在 啟動本地反代並接入第一個客戶端 裡已經驗證成功的那種調用方式，發 1-2 次請求。
你應該看到：Token Stats 頁面從「載入中/暫無資料」變成有圖表或列表。
第 2 步：選對時間視窗（小時/日/週）
為什麼 同一份資料在不同視窗下看到的「峰值/趨勢」完全不一樣。UI 裡三種視窗對應的取數範圍也不同：
- 小時：最近 24 小時
- 日：最近 7 天
- 週：最近 4 週（趨勢視圖會按最近 30 天聚合）
你應該看到：切換後，趨勢圖橫軸粒度變化（小時顯示到「時」，日顯示到「月/日」，週顯示到「年-W週號」）。
第 3 步：先看頂部總覽，確定「成本規模」
為什麼 總覽卡片能先回答 3 個問題：總量大不大、輸入/輸出佔比是否異常、參與的帳號/模型是不是突然變多。
重點看這幾項：
- 總 Token（
total_tokens） - 輸入/輸出 Token（
total_input_tokens/total_output_tokens） - 活躍帳號數（
unique_accounts） - 使用模型數（UI 直接用「分模型統計列表」的長度）
你應該看到：如果「活躍帳號數」突然飆高，通常意味著你在短時間內跑了更多帳號（例如切換到輪換策略）。
第 4 步：用「分模型/分帳號使用趨勢」抓異常峰值
為什麼 趨勢圖是最適合抓「突然變貴」的入口。你不用先知道原因，先把「哪天/哪小時飆了」圈出來。
做法：
- 在趨勢圖右上角切換「按模型 / 按帳號」
- 滑鼠懸停（Tooltip）看 Top 值，優先關注「突然衝到第一的那條」
你應該看到：
- 按模型：某個模型在某個時間段突然抬升
- 按帳號：某個帳號在某個時間段突然抬升
第 5 步：用 Top 列表把「最貴目標」鎖死
為什麼 趨勢圖告訴你「什麼時候異常」，Top 列表告訴你「誰最貴」。把這兩個交叉，就能快速定位排障範圍。
做法：
- 在「按模型」視圖下，看「分模型詳細統計」表格的
total_tokens / request_count / 佔比 - 在「按帳號」視圖下，看「帳號詳細統計」表格的
total_tokens / request_count
你應該看到：最貴模型/帳號排在前面，且 request_count 能幫你區分「單次特別貴」還是「次數特別多」。
第 6 步（可選）：找到 token_stats.db，做備份/核對
為什麼 當你懷疑「統計缺失」或想做離線分析時，直接拿 SQLite 檔案最靠譜。
做法：進入 Settings 的 Advanced 區域，點擊「打開資料目錄」，你會在資料目錄裡找到 token_stats.db。
你應該看到：檔案列表裡有 token_stats.db（檔名由後端寫死）。
檢查點 ✅
- 你能說清楚 Token Stats 統計是「從響應裡的 usage/usageMetadata 提取後落到本地 SQLite」，不是雲端計費
- 你能在「按模型/按帳號」兩種趨勢視圖下，指出一個具體的峰值時間段
- 你能用 Top 列表給出一個可執行的排查結論：先查哪個模型或帳號
踩坑提醒
| 現象 | 常見原因 | 你可以怎麼做 |
|---|---|---|
| Token Stats 顯示"暫無資料" | 你確實沒產生模型請求；或上游響應沒帶可解析的 token 欄位 | 先複用已驗證可用的客戶端發請求；再看響應裡是否包含 usage/usageMetadata |
| 統計按"模型"看起來不對 | 統計口徑使用請求裡的 model，不是 X-Mapped-Model | 把模型路由當成"請求模型 -> 映射模型"；統計看的是"請求模型" |
| 帳號維度缺失 | 只有拿到 X-Account-Email 且解析到 token 用量時才會寫入 | 確認請求確實走到了帳號池；再對照請求日誌/響應標頭 |
| 啟用 Proxy Monitor 後統計資料偏大 | 當 Proxy Monitor 啟用時，每次請求的 token 會被記錄兩次 | 這已知的實作細節，不影響相對趨勢分析；如果需要精確值，可以暫時停用 Monitor 後重測 |
本課小結
- Token Stats 的核心價值是「把成本問題量化」，先定位，再優化
- 統計寫入時，帳號和 token 用量是必須的；模型缺失時會被記錄為
"unknown"（不會阻止寫入） - 想做更精細的成本控制，下一步通常會回到模型路由或配額治理
下一課預告
下一課我們解決長會話裡的「隱性穩定性問題」：長會話穩定性：上下文壓縮、簽名快取與工具結果壓縮。
你會學到：
- 三層漸進式上下文壓縮分別在做什麼
- 為什麼「簽名快取」能減少 400 簽名錯誤
- 工具結果壓縮會刪掉什麼、保留什麼
附錄：原始碼參考
點擊展開查看原始碼位置
更新時間：2026-01-23
| 功能 | 檔案路徑 | 行號 |
|---|---|---|
| --- | --- | --- |
| Token Stats UI：時間視窗/視圖切換與取數 | src/pages/TokenStats.tsx | 49-166 |
| Token Stats UI：空資料提示（"暫無資料"） | src/pages/TokenStats.tsx | 458-507 |
| Token 用量提取：從請求解析 model、從響應解析 usage/usageMetadata | src-tauri/src/proxy/middleware/monitor.rs | 32-120 |
| Token 用量提取：流式與 JSON 響應解析 usage 欄位 | src-tauri/src/proxy/middleware/monitor.rs | 122-336 |
| Token Stats 寫入點：拿到帳號+token 後寫入 SQLite | src-tauri/src/proxy/monitor.rs | 79-136 |
資料庫檔名與表結構：token_stats.db / token_usage / token_stats_hourly | src-tauri/src/modules/token_stats.rs | 58-126 |
寫入邏輯：record_usage(account_email, model, input, output) | src-tauri/src/modules/token_stats.rs | 128-159 |
| 查詢邏輯：小時/日/週、按帳號/按模型、趨勢與總覽 | src-tauri/src/modules/token_stats.rs | 161-555 |
Tauri 命令：get_token_stats_* 對前端暴露 | src-tauri/src/commands/mod.rs | 791-847 |
| 應用啟動時初始化 Token Stats DB | src-tauri/src/lib.rs | 50-56 |
設定頁：取得/打開資料目錄（用於找到 token_stats.db） | src/pages/Settings.tsx | 76-143 |