用量统计
一、用量统计是什么
用量统计用于查看 AI Gateway 的实际调用情况。
它帮助用户回答：
- 使用了多少模型资源；
- 哪些模型和 API Key 使用最多；
- 请求是否成功；
- 错误率是否发生变化；
- 响应是否变慢；
- 当前使用是否符合预期。
用量统计既用于查看资源消耗，也用于排查调用异常。
二、用量统计可以观察什么
调用数据汇总
汇总卡片展示当前筛选范围内最重要的用量指标，适合快速判断整体调用和费用是否发生明显变化。
| 指标 | 说明 |
|---|---|
| 总 Token 消耗 | 当前范围内所有文本类模型的计费 Token 总量 |
| 总请求数 | 当前范围内发起的请求总数，并区分成功请求与失败请求 |
| 总费用 | 当前范围内产生的模型调用费用 |
| 平均费用 / 百万 Token | Token 类模型总费用 ÷ Token 总量 × 1,000,000，用于比较不同时间段的平均调用成本 |
页面中的环比数据，默认与所选时间范围之前、长度相同的一段时间进行比较。例如选择最近 7 天时，环比对象为再之前的 7 天。
图 1：汇总卡片用于快速回答“调用了多少、请求是否成功、产生了多少费用、平均成本是否变化”等问题。
用量趋势与 Top 消耗
用量趋势
趋势图用于查看费用、Token 和请求数随时间的变化。
- 切换 费用 / Token / 请求数，观察不同指标的变化趋势。
- 可选择具体模型进行对比，建议一次不超过 5 个模型，以保证图表清晰。
- 拖动图表底部的时间轴，可以缩小范围并定位异常时段。
- 当费用突然上升时，可依次对比请求数和 Token：请求数同步上升通常代表调用量增加；请求数变化不大但 Token 上升，通常代表单次请求内容或响应变长。
Top 消耗
Top 消耗用于识别当前范围内最主要的用量来源。
- 按模型：查看费用或调用量最高的模型。
- 按 API Key：查看费用或调用量最高的业务、项目或应用。
- 点击排行项可继续查看对应对象的趋势和明细。
对于图片、视频等非 Token 计费模型，Top 消耗能够帮助您快速发现高分辨率、多张图片、长视频或高频任务带来的费用增长。
图 2：趋势图负责定位“什么时候发生变化”，Top 消耗负责定位“哪些模型或 API Key 贡献了主要用量”。
明细表格
页面下方的明细表格用于查看汇总指标背后的具体构成。
| 明细维度 | 适用场景 |
|---|---|
| 按模型 | 对比不同模型的请求数、计费用量和费用 |
| 按 API Key | 将用量归因到不同项目、应用或业务 |
| 账户明细 | 查看账户层面的调用记录及费用构成 |
按模型查看时，常见字段如下：
| 字段 | 说明 |
|---|---|
| 模型 | 实际调用的模型名称 |
| 服务档位 | 本次调用使用的经济型、标准型或高质量型 |
| 请求数 | 当前范围内的调用次数 |
| 计费用量 | 按模型计费方式展示 Token、张数、秒数或任务数 |
| Input | 输入 Token 或输入侧计费用量 |
| Output | 输出 Token 或输出侧计费用量 |
| 缓存创建 | 支持显式缓存模型的缓存创建用量 |
| 缓存命中 | 支持缓存计费模型的缓存命中用量 |
| 费用 | 当前模型在所选范围内产生的费用 |
| 操作 | 进入该模型的用量详情 |
不同模型的计费单位可能不同。文本模型通常按 Token 计费，图片模型可能按张数或分辨率计费，视频模型可能按秒数或任务规格计费；不适用的字段会显示为“—”。
图 3：明细表格会根据模型的实际计费方式展示 Token、张数、秒数或任务数，避免使用单一计费字段解释所有模型。
下钻详情
点击模型或 API Key 的详情入口，可以进一步查看单个对象的用量构成。
| 内容 | 说明 |
|---|---|
| 汇总指标 | 查看该对象的 Token、请求数、成功率和费用 |
| 趋势图 | 定位该对象用量上升或异常发生的具体时间 |
| 费用构成 | 查看输入、输出、缓存或媒体任务规格对应的费用 |
| 调用分布 | 查看不同服务档位、模型或业务来源的占比 |
| 计费明细 | 核对图片张数、视频时长、分辨率、任务规格等实际计费信息 |
下钻详情适合回答以下问题：
- 某个模型为什么成为 Top 消耗；
- 某个 API Key 的费用从什么时候开始上升；
- 图片或视频任务的规格是否导致费用增加；
- 请求失败是否集中在某个时间段或某个模型。
图 4：从排行或明细进入下钻页后，可以将整体费用变化进一步定位到具体模型、API Key、时间段和计费项。
导出数据
点击页面右上角的 导出，系统会按照当前筛选条件生成明细文件。
导出前建议确认：
- 日期范围是否正确；
- 是否只选择了某个服务档位；
- 当前查看的是按模型还是按 API Key；
- 是否已经筛选了特定模型。
导出文件适合用于内部成本分析、项目分摊和账单核对。页面统计和导出数据用于辅助分析，最终结算金额仍以账单为准。
七、用量统计与费用理解
用量统计用于观察资源使用，模型广场用于查看价格。
两者需要结合使用：
只有当账号没有任何生效的专属折扣时，所有模型都可以按刊例价使用并展示为“全价”。账号已经配置过任意模型折扣时，当前模型在当前 API Key 档位没有折扣就不可用，也不会产生调用用量；其他档位的折扣不能复用。
不同模型的计费方式可能不同，例如文本、图片和视频模型可能使用不同计量单位。模型详情页和用量统计会展示对应的计量方式。
用量统计中的成本用于使用分析和费用参考，不等同于最终结算账单。实际结算以平台最终账单口径为准。
八、异常排查流程
当业务反馈“调用变慢”或“调用失败”时，建议按以下顺序排查：
如果错误率上升
先确认 API Key 状态、调用限制、模型标识和请求参数。
如果延迟上升
确认是否集中发生在某个模型、某个 API Key 或某段时间。
如果用量突然增加
确认是否存在重复调用、自动重试、循环调用或 Key 泄露。
如果模型服务异常
当前 API Key 对应档位没有可用服务时，请求会失败，不会切换到其他档位。
正式业务建议使用高质量型 API Key，但高质量型也不代表可以忽略监控和错误排查。
九、与其他产品配合使用
Data Analytics Agent、Engineering Agent、CZ-CLI 和 Lakehouse AI Function 建议分别使用独立 API Key。
这样可以单独观察每个产品的：
- Token 使用量；
- 请求次数；
- 错误率；
- 延迟；
- 使用趋势。
十、用量统计的日常使用建议
日常查看
每周查看一次主要产品和 API Key 的用量趋势。
上线观察
新业务上线初期，重点观察请求量、错误率和延迟。
异常检查
发现用量或错误率异常时，缩小时间范围并按模型、API Key 分别查看。
成本复盘
将用量统计与模型广场的刊例价、折后价结合，复盘业务实际消耗。