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 |