Runbook：用量与计费异常
计费异常包括请求成功但没有记录、重复记录、Token 不对、模型价格不对、用户扣费与账号成本不一致，以及统计报表延迟。
先固定一条请求
准备：Request ID、用户、Sub2API Key、Group、Account、时间、入口模型、上游模型、是否流式。不要先看整天总额，因为多个问题可能叠加。
三个模型名
| 字段 | 含义 |
|---|---|
| requested model | 用户请求的名字 |
| upstream model | 实际发给供应商的名字 |
| billing model | 查价格并计费的名字 |
映射错误可能让请求成功但使用错误价格。每次修改模型映射都要同时验证这三个字段。
排查顺序
- Usage Log 是否存在且 Request ID 唯一。
- 请求最终状态是否成功，流是否完整结束。
- 输入、输出、cache read/create、图片/视频用量是否被解析。
- billing model 是否存在价格。
- Group、用户、账号倍率是否符合配置。
- 用户实际费用、账号成本和上游账单单位是否一致。
- usage worker、聚合任务 heartbeat 和队列是否正常。
- 时区和报表时间范围是否一致。
常见情况
请求成功但 usage 为零
- 第三方上游未返回 usage。
- SSE 结束前客户端或上游断开。
- 兼容转换没有识别供应商字段。
- 特殊端点使用不同用量字段。
不要在未知 usage 时静默按零收费。应隔离该上游，明确估算/拒绝策略后再上线。
价格缺失
先停止扩大影响，补充价格前确认币种、单位、输入/输出/缓存和服务等级。不要仅按模型名称相似复制价格。
重复或缺失记录
检查客户端重试、网关重试、Request ID、支付/usage 幂等和异步写入失败。区分“请求发送两次”和“同一请求记账两次”。
报表与实时日志不同
聚合有刷新窗口；先比较相同时间范围、时区、过滤条件和数据源。检查 aggregation heartbeat 和 raw/preagg 查询模式。
处置原则
- 先暂停错误价格的 Group、模型或账号，不要删除历史。
- 导出受影响 Request ID、用户和金额。
- 修复后用固定 prompt 做可重复验证。
- 调账必须记录原因、原值、新值、操作者和审批。
- 涉及用户余额时先确定影响范围，再统一沟通。
恢复验收
同一测试请求只产生预期记录；requested/upstream/billing model 正确；Token 与上游响应相符；用户费用、账号成本和倍率可解释；原始与聚合报表最终一致。