用量、计费与配额

计费链路回答三个问题：请求能不能开始、请求实际花了多少、费用应该从哪里扣。

请求前资格检查

取得用户并发槽位后，系统检查：

1. 用户、API Key 和分组状态。
2. 是否有有效订阅。
3. 订阅日/周/月窗口是否还有额度。
4. 没有可用订阅时，余额是否高于最低保留值。
5. API Key 总 quota 和 5h/1d/7d 窗口。
6. 用户 × 平台配额。

检查通过不代表预先知道最终费用。文本请求通常只能在上游返回 usage 后精确计算。

价格来源

价格服务支持：

• 远程 price JSON。
• 对应 hash 文件校验。
• 本地 fallback 文件。
• 部分模型硬编码回退。

后台会定期检查更新。生产环境要确保定价下载失败时仍有可用 fallback，并对新模型执行价格测试。

Token 费用

常见费用项：

input_tokens              × input price
output_tokens             × output price
cache_creation_tokens     × cache creation price
cache_read_tokens         × cache read price
cache_creation_5m / 1h    × 对应缓存价格
image_input/output_tokens × 图片 Token 价格

长上下文和 service tier 可能额外应用倍率。不能用简单的 (input + output) × 单价 验证所有请求。

用户费用与账号成本

系统同时关注：

• 用户实际费用：用于扣余额、订阅和 API Key quota。
• 账号实际成本：用于运营者分析账号池成本。

分组和用户倍率主要影响用户费用；账号倍率用于账号维度成本。Usage Log 会保存多个费用字段和模型上下文，便于后续对账。

余额模式

余额模式下：

1. Preflight 检查余额是否足够开始请求。
2. 请求完成后计算实际费用。
3. 数据库原子更新余额和用量。
4. 失效或更新 Redis 余额缓存。

最低余额 reserve 是保守门槛，不是预估整次请求的最大费用。极端并发下仍要依靠并发限制、事务和后续异常处理降低超扣风险。

订阅模式

订阅绑定用户和分组，包含：

• starts_at / expires_at。
• status。
• daily/weekly/monthly window start。
• daily/weekly/monthly usage。
• 分配人、分配时间和备注。

订阅额度通常来自分组配置。窗口达到上限后，用户不能继续通过该订阅调用，直到窗口重置或使用其他符合规则的权益。

API Key quota

API Key quota 是附加控制：

• quota=0 表示无总额度限制。
• quota_used 累计费用。
• 5h/1d/7d 独立窗口。

它适合给单个项目、设备或合作方设置预算，不适合替代用户余额。

用户平台配额

平台配额用来防止一个用户把全部费用集中在某个平台。由于请求高频，Redis 保存窗口缓存，后台可以批量刷回数据库。

启用配额 flusher 后重点监控：

• dirty set 大小。
• flush latency。
• readd 数量。
• dirty lost。
• FK violation。
• Redis 与 PostgreSQL窗口值差异。

图片与批量图片

同步图片可以按 Token、图片规格或渠道定价结算。批量图片是异步任务，通常需要：

1. 按最大可能成本冻结余额。
2. worker 提交并轮询上游任务。
3. 根据实际完成项目结算。
4. 释放未使用冻结金额。
5. 处理失败、取消和恢复。

分组的 batch_image_hold_multiplier 决定预占比例，batch_image_discount_multiplier 决定最终折扣。冻结过低可能执行后余额不足，过高会让用户长时间无法使用余额。

视频计费

视频可能根据分辨率、秒数、请求或上游返回元数据计算。Usage Log 必须保存足够的 billing metadata，才能重现费用。

新增视频模型时，应同时测试：

• 提交请求。
• 状态轮询。
• 成功与失败任务。
• 不同分辨率和时长。
• 重复状态回调是否重复扣费。

用量去重

网络重试、WebSocket turn、previous response 恢复和异步任务可能多次触达记录逻辑。系统使用 billing dedup 防止同一计费单元重复扣费。

对账时要区分：

• HTTP 请求 ID。
• 上游 response/turn ID。
• Usage Log ID。
• billing dedup key。
• 支付订单号。

它们不是同一个标识。

异步 worker

默认用量 worker 配置具有：

• 128 个初始 worker。
• 16384 有界队列。
• 自动扩展到更高 worker 数。
• 任务超时。
• 队列满时默认同步 fallback。

这些是高吞吐默认值，不代表所有服务器都适合。数据库较小而 worker 太多时，可能让连接池和写 IOPS 突然饱和。

计费验收

上线新模型或倍率前，准备已知 Token 的请求，核对：

1. requested/upstream/billing model。
2. 输入、输出和缓存 Token。
3. 基础单价。
4. 分组、用户、高峰和服务等级倍率。
5. user cost 与 account cost。
6. 余额、订阅、Key quota 和平台配额变化。
7. 重复 RecordUsage 不会二次扣费。

异常信号

信号	风险
pricing not found	请求可能失败或无法结算
usage worker dropped	计费记录可能缺失
sync fallback 持续增加	数据库或 worker 已拥塞
balance cache 与 DB 不一致	资格判断可能漂移
billing dedup 冲突激增	上游/客户端重复或 key 设计异常
用量成功但费用为 0	模型价格、倍率或 usage 解析问题