用量上报
使用 Usage 视图比较各 AISIX 网关环境和模型的请求量、Token 消耗与支出。该视图还汇总组织范围内的语义缓存节省量，可用于调查异常支出或确认用量记录已到达控制面。
用量如何上报
AISIX 网关在你的运行环境中承载 AI 流量，并将用量事件上报到控制面。它会根据控制面 URL 推导遥测端点，并将用量数据发送到固定的 /dp/telemetry 路径。运维人员无需为控制面用量上报单独配置目标。
每个事件可以包含请求状态、延迟、Token 用量和成本。事件还会区分调用方请求的模型别名与实际处理某次尝试的解析模型，这有助于理解路由流量和合议模型流量。流式聊天请求也可以上报首 Token 时间。
当模型服务提供方上报非零 Token 数时，AISIX 会采用该数据。对于流式请求，AISIX 还会要求 OpenAI 兼容上游在最后一个流式数据块中包含用量数据。
Chat Completions、Completions、Messages、Responses 和 Embeddings 端点返回的响应可能会省略部分或全部用量数据。例如，OpenAI 兼容中继从不上报用量、客户端在流式传输中途断开，或上游在返回部分响应后发生错误。此时，AISIX 会使用本地分词器估算缺失或为零的 Token 字段。输入 Token 按发送给上游的请求估算，输出 Token 按传递给调用方的内容估算，同时保留模型服务提供方上报的非零值。
AISIX 会使用估算值发送用量事件，因此请求仍会计入遥测、支出、预算和 Token 限流统计。本地计算的事件会标记为估算值，请求日志视图会在对应行显示 estimated 标记。估算值与 OpenAI 系列模型高度接近；对于使用专有分词器的模型，该值为近似值。估算不适用于其他端点类型。
调用方响应中的估算计数
在由 AISIX 自己序列化响应体的路径上，估算计数也会写入调用方读到的 usage 块，使客户端与控制面上报同一组数字。这包括缓冲式 /v1/chat/completions 响应（含语义缓存命中）， 以及桥接的 /v1/messages 和 /v1/responses 路径。逐字转发服务提供方字节的路由不会改动响应体。上述范围中有一个例外：流式 /v1/chat/completions 返回给调用方的用量就是上游发送的内容，因此上游省略时它可能缺失或为零，而用量记录仍会携带本地估算值。
填充按计数逐项进行：上游已上报的计数保持不变，缺失或为零的计数会被填入；当相邻计数被填入时，total_tokens 会按输入加输出重新计算。计费结果不受影响。响应中没有任何标识说明某个计数是估算出来的，用量记录上的 usage_estimated 字段（在请求日志中表现为 estimated 标记）仍是判断依据。
按上报原样记录计数
用量记录按上游上报的原样保存 Token 计数，控制面存储时不会校验它们彼此之间的关系。各上游对 completion_tokens 是否包含推理、prompt_tokens 是否包含缓存输入的口径不同，因此一条记录可能出现 reasoning_tokens 大于 completion_tokens，或 cached_prompt_tokens 大于 prompt_tokens。这样的记录会像其他记录一样被保存和计价。1.4.0 及更早版本的控制面会拒绝这类记录，导致该请求在请求日志、Usage 和支出中缺失。
记录还携带 total_tokens，即上游自己上报的总数，按收到的原样保存。它从不由计算得出；上游没有上报总数时为 null。例如 Anthropic 从不上报总数，1.4.0 及更 早版本的网关也不上报，因此较早的记录同样没有总数。这个总数不一定等于其他计数之和，因为各上游计入总数的 Token 类别不同。控制面也依据它决定如何为推理 Token 计价，详见推理 Token 如何计费。
这些是记录下来的计数，而不是调用方读到的计数。响应中的 usage 块按调用方使用的协议适配，这一点没有变化：Vertex AI 上 Gemini 思考模型返回的 OpenAI 形态响应，仍会把思考 Token 计入 completion_tokens。详见记录的 Token 计数。
解读用量
Usage 视图按滚动 30 天窗口汇总各环境中的 AISIX 网关流量，所有总计和表格都使用同一时间窗口。
| 信号 | 可帮助解释的内容 |
|---|---|
| 请求数 | 流量规模和需求变化。 |
| Token 总量 | Token 消耗，按每条记录自身的总数累加：有上游上报的总数时取该值，否则取输入 + 输出 + 缓存创建 + 缓存读取 Token 之和。其下方一行仍分别汇总输入和输出。 |
| 支出 | 将匹配的模型费率应用于 Token 数，以及按时长计费的转录或翻译请求所测得的音频时长，由此计算的成本。 |
| 缓存节省 | 语义缓存命中避免的 上游输入和输出 Token 消耗。 |
| 按环境统计的用量 | 哪个部署环境产生了流量和支出。 |
| 热门模型 | 按支出排序的前 10 个环境与调用方请求模型别名组合；缺少请求模型值的旧记录回退到解析后的模型。 |
| 热门 API Key | 按支出排序的前 10 个环境与调用方 API Key 组合。 |
在支持本地 Token 估算的情况下，缺失或为零的 Token 数由网关估算。音频端点不会估算缺失的 Token 数；转录和翻译请求可以改为产生基于时长的支出。支出还需要与事件的 (provider, model name) 匹配的价格，并且适用计费依据的费率不为零。Usage 会把支出四舍五入到两位小数，因此即使存在匹配价格，低流量也可能显示 $0.00。
使用模型定价添加或检查价格，并在请求日志中以六位小数检查事件或尝试成本。价格变更只影响变更后记录的事件。
用量与预算执行
控制面使用 AISIX 网关用量记录评估预算。每个预算都定义作用范围、支出上限、周期和执行模式。
滚动 30 天的 Usage 窗口与预算所配置的周期彼此独立，因此两者的总额可能覆盖不同时间范围。
当硬停止预算被超出时，AISIX 网关可以对匹配的请求返回 HTTP 429。仅告警预算会显示预算超支状态，但不会阻断流量。
如果预算拒绝不符合预期，请检查返回的预算作用域、配置上限，以及决定团队或成员预算适用范围的调用方 API Key 绑定。完整执行路径请参见预算。
排查缺失或异常用量
按以下顺序检查上报路径：
- 确认请求经过连接到预期环境的 AISIX 网关。同一组织中经过其他环境的流量会显示在对应环境下；其他组织中的流量会显示在该组织自己的 Usage 视图中。
- 确认请求已完成并出现在 Request Logs 中。网关会批量刷新遥测，新完成的请求可能需要几秒才会出现。
- 确认 AISIX 网关有最新心跳。
- 确认网关能够访问控制面遥测端点。
- 如果支出为零或不符合预期，请检查 Model Pricing 是否与模型服务提供方和模型名称精确匹配，再确认适用的 Token 费率或 Audio per minute 费率不为零。
如果网关处理过的某个请求始终没有出现在请求日志中，请检查网关上的 aisix_usage_events_rejected_total。它统计控制面在一个已接受的批次中拒绝的用量事件，例如 ID 格式错误或状态码超出 HTTP 范围的事件。这些事件会被丢弃，不会重新发送；每个这样的批次都会记录日志 control plane rejected usage events in an accepted telemetry batch (events dropped)。详见用量事件如何送达控制面。
在控制面短暂失联期间，实时流量可以继续使用最近投射的配置。只要控制面最近一次应答表明它会对 批次去重，失联期间发送失败的遥测批次就会被网关重发，重发间隔从 1 秒退避到最长 30 秒。批次在其最早一条事件发生 30 分钟后会被放弃，因此超过这个时长的失联，或者把网关内存队列填满的失联，仍会导致用量记录缺失，这些丢失由 aisix_usage_event_drops_total 统计。详见用量事件如何送达控制面。导出器健康、心跳和新的预算决策也依赖控制面连接。预算检查可暂时复用缓存决策，之后再应用配置的失败模式；详见可用性与缓存。