---
title: "用量分析"
description: "pirouter 控制台的用量页按 UTC 时间、模型和 API key 汇总工作区的 token、花费、请求数和耗时，通常几分钟内更新；请求数按尝试计，发生过回退时失败占比会偏高。"
canonical: "https://pirouter.ai/zh/docs/guides/usage"
last-updated: "2026-10-17"
lang: "zh"
source: "content/docs/zh/guides/usage.mdx"
---

# 用量分析

pirouter 控制台的用量页按 UTC 时间、模型和 API key 汇总工作区的 token、花费、请求数和耗时，通常几分钟内更新；请求数按尝试计，发生过回退时失败占比会偏高。

想知道钱花在哪个模型、哪个 API key 上，看控制台的 **用量** 页；想看某一次请求的细节，看[请求日志](https://pirouter.ai/zh/docs/guides/logs.md)。

## 打开用量页

在[控制台](https://app.pirouter.ai)侧栏点 **用量**。页面上的时间都是 UTC。

工作区的所有成员都能看用量页，没有更细的角色限制。每个工作区只看到自己的数据。

![最近 7 天的用量页：Token 活动热力图，Tokens、花费、请求数、耗时四张卡，以及按模型堆叠的趋势图](/docs/shots/usage-overview.zh.webp)

## 选择时间范围

在工具栏的 **时间段** 里选预设：**今天**、**24 小时**、**7 天**、**30 天** 或 **90 天**，默认是 **今天**。也可以选 **自定义时间段**，最长 90 天，结束日不能晚于今天（UTC）。

| 时间范围                                 | 图表粒度                     |
| ------------------------------------ | ------------------------ |
| **今天**                               | 按 UTC 小时，从今天 00:00 到当前小时 |
| **24 小时**                            | 按 UTC 小时，最近 24 个整点       |
| **7 天**、**30 天**、**90 天**、**自定义时间段** | 按 UTC 日                  |

按小时出图时，最后一根柱子是当前小时，仍在累计，用斜纹标出。

### 数据多久更新

页头右侧的 **数据截至 UTC HH:MM** 是数据实际覆盖到的时刻。

今天的数字每 5 分钟刷新一次，所以一笔请求通常几分钟内出现在用量页，以 **数据截至** 的时刻为准。当天第一次刷新之前，页面显示「今天的用量仍在同步中」，这不表示没有请求。

某段时间还没汇总完时显示「用量仍在汇总中」。这时不显示任何数字，不给部分和。

## 读懂四张卡

| 卡片         | 大数字                         | 下方                                           |
| ---------- | --------------------------- | -------------------------------------------- |
| **Tokens** | 输入加输出的 token 总数，缓存命中的输入只算一次 | **输入**、**输出**、**缓存**，以及 **命中** 率：缓存输入 ÷ 全部输入 |
| **花费**     | 所选时间段内请求的花费，按每次请求当时的价格计     | **每百万 tokens** 与 **每次请求** 的平均花费              |
| **请求数**    | 请求次数                        | **成功** 与 **失败** 两部分，以及失败占比。失败包括所有没有正常完成的请求   |
| **耗时**     | 首 token 时间加生成时间的合计          | **平均首 token** 与 **平均生成** 时间。平均值包含失败请求        |

花费的单位是美元，显示为 `$`。不低于 $0.01 的金额保留两位小数，更小的金额保留 4 位或 6 位。

> **注意：** **请求数** 按尝试计，不按请求计。请求在返回第一个字节之前失败、由 pirouter 换到另一个部署或模型重试时，每次尝试各记一次：被接替的那次计为一次失败，金额为 0。所以发生过故障切换或回退时，失败占比会高于按请求计算的比例。见[模型回退](https://pirouter.ai/zh/docs/guides/fallbacks.md#计费)。

网关在转发之前就拒绝的请求（例如 key 无效、余额不足）不计入用量，也不计费，见[失败的请求](https://pirouter.ai/zh/docs/guides/billing.md#失败的请求)。

## 看趋势和排行

- **趋势** 图按模型堆叠：用量最多的 5 个模型各占一层，其余合并为 **其他**。可以在 Tokens 与花费之间切换。
- **模型** 排行列出本工作区在该时间段调用过的模型，可按 Tokens 或花费排序。默认显示 10 行，最多展开到 20 行。

* **工具** 排行列出发出请求的应用和客户端，最多 20 行。选 **24 小时** 时，工具排行按整个 UTC 日统计，页面会注明日期范围。

- 识别出的应用和客户端显示名字（例如 OpenAI Python SDK、curl），其余归入 **其它应用（未识别）**、**其他客户端** 或 **直接调用 API**。

![模型与工具两张排行按 Tokens 排序，工具排行最后一行是直接调用 API](/docs/shots/usage-rankings.zh.webp)

## 按模型和 API key 筛选

工具栏的 **模型** 可以多选，最多 50 个；**API 密钥** 一次选一个 key。筛选同时作用于热力图、四张卡、趋势和两张排行。

时间段和筛选都写在地址栏里（`range` 或 `from` 与 `to`，以及 `model`、`key`）。复制链接发给同事，就能看到同一个视图。

## 从某一天跳到日志

**Token 活动** 热力图的每一格是一个 UTC 日的请求数，覆盖过去 12 个月。点某一天会打开当天的[请求日志](https://pirouter.ai/zh/docs/guides/logs.md)，并带上当前的模型和 key 筛选。

## 目前没有的能力

- **导出。** 用量页没有导出或下载 CSV 的功能。
- **读取用量的 API。** 公开 API 只有推理与模型目录的端点，没有读取用量或日志的端点。

* **更细的小时粒度。** 只有 **今天** 和 **24 小时** 按小时出图；自定义时间段只能按日选。

## 下一步

- [请求日志](https://pirouter.ai/zh/docs/guides/logs.md): 逐条查看请求，用 trace ID 找到某一次调用。
- [模型回退](https://pirouter.ai/zh/docs/guides/fallbacks.md): 请求的模型不可用时，自动改用另一个模型。