Skip to content
生成测试额度与原子预留

生成测试额度与原子预留

本文属于“当前架构”,描述 P6 / C12 已落地的测试预算控制。 它是开发/验收预算,不是生产用户终身额度。

1. 范围

V2 累计测试预算(P9-C 已按用户批准翻倍):

  • 图片 40 张
  • 视频 8 次供应商生成请求
  • 音频 1000 字

默认 scope:v2-acceptance。

运行时是否启用由设置控制:

  • generation_test_quota_enabled(默认 false)
  • generation_test_quota_scope(默认 v2-acceptance)

生产环境应保持关闭,或使用独立的生产预算配置;不得把验收 scope 当作生产用户配额。

2. 数据模型

generation_quotas:

  • scope / media_type
  • limit_amount
  • consumed_amount
  • reserved_amount
  • unique(scope, media_type)

generation_usage_reservations:

  • scope / media_type / amount
  • status:reserved / committed / released
  • task_id / provider / model
  • note / settled_at

迁移:044-add-generation-usage-quota.sql 初始化 20/4/500;049-raise-v2-acceptance-quota.sql 将 v2-acceptance 上限提升为 40/8/1000,不重置已消耗。

3. 原子预留

reserve() 使用单条 SQL 原子更新:

UPDATE generation_quotas
SET reserved_amount = reserved_amount + amount
WHERE id = ?
  AND consumed_amount + reserved_amount + amount <= limit_amount

rowcount=0 即额度不足。两个并发请求只有一个能抢到最后一份额度。

4. 结算语义

  • 成功:reserved → committed,consumed 增加,reserved 减少;
  • 请求未发送/明确释放:reserved → released;
  • 已发送但失败、超时、取消:保守按 committed;
  • 任务重试/执行层重复调用通过 (task_id, media_type) 查已有 reservation,避免重复扣减。

5. 执行层覆盖

共享真实供应商执行层:

  • image_task_runner:按 input.n 预留图片额度;
  • video_generation runner:每任务预留 1 次;
  • audio_task_runner:按文本字符数预留。

额度检查在 task.run() 之前;服务端内部执行,不依赖前端按钮。

Mock/本地测试不经过真实供应商 runner,不消耗额度。

6. API

方法路径说明
GET/api/v1/studio/generation-quota查询 scope 额度
GET/api/v1/studio/generation-quota/reservations使用记录
POST/api/v1/studio/generation-quota/reserve显式原子预留
POST/api/v1/studio/generation-quota/settle结算预留

7. 当前边界

  • 默认关闭,真实调用必须在启用的测试环境中进行;
  • 不把本地 Mock 计入预算;
  • 当前隔离验收库状态:图片 0/40、视频 3/8(含 1 次失败协议探测)、音频 0/1000,视频剩余 5 次;
  • 提升上限只改 limit_amount,不重置 consumed_amount / reserved_amount;
  • 生产预算与验收预算继续分离,不把 v2-acceptance 当作生产用户配额。