用积分对用量计费
完成后,用户通过方案或手动发放获得积分余额,AI 任务等按量计费的工作从余额中扣除。
积分是产品对按量计费的工作收费的单位。用户通过付费方案、运营人员发放或注册奖励获得积分。每个任务在运行前先冻结价格,工作成功后才扣除。积分不需要服务商和环境变量,除非开启注册奖励,新用户余额为零;积分不会过期。
准备工作
- 拥有
credits.read和credits.write的管理员账号。要在方案上设置积分还需要products.write;内置的 Commerce Manager 角色已包含产品和积分相关权限。 - 如果希望买家付款后拿到方案积分,需要先接入支付服务商,见 接入支付服务商。
给用户积分
设置工作的价格
AI 任务的积分价格在 设置 → AI 配置 中设置:每个任务固定价格、按请求参数定价,或按 Token 用量计费。操作见 设置场景路由和定价。任务价格高于可用余额时,在调用服务商之前就会被拒绝。
为自己的功能收取积分
工作开始前先冻结价格,然后对这笔预留只结算一次:成功时扣除,失败时退还。先解析出用户,再在服务端代码中调用。
import {
captureAiTaskCredits,
refundAiTaskCredits,
reserveAiTaskCredits,
} from "@/server/services/credits-ledger.service";
const { reservationId } = await reserveAiTaskCredits({
userId,
taskId: `export_${jobId}`,
amount: 5,
});
try {
await runExport(jobId);
await captureAiTaskCredits({ reservationId, userId });
} catch (error) {
await refundAiTaskCredits({ reservationId, userId });
throw error;
}可用余额不足时预留会失败,错误信息包含 /system/insufficient-credits,界面可以据此跳转。把 reservationId 与任务一起保存,让重试或轮询程序结算同一笔预留。
不要让用户直接改动余额
不要新增可由用户调用的发放、预留、扣除、退还或修复积分的 server function。面向用户的函数只读并绑定当前会话用户,否则 pnpm validate:session-owner 会失败。
查看或修复余额
打开用户
在 概览 → 用户 的用户行点击 详情。积分 卡片显示当前余额和最近的账本记录。
必要时修复
如果余额和账本对不上(例如有人直接改过数据库),点击 修复余额快照。系统会根据账本重建余额,并把修复前后的数值写入审计日志。
验证
给测试用户发放 10 积分
手动发放 10 积分,以该用户登录并打开 /app/credits。可用余额显示 10,账本里能看到这次发放。
购买方案
在服务商测试模式下购买一个设置了 包含积分 的方案,刷新 /app/credits。方案积分以一条购买记录出现。
注册新用户
开启注册奖励后注册一个新账号并打开 /app/credits。账本中有一条数量等于设置值的 signup.bonus 发放记录。
用完积分
发起一个价格高于剩余余额的 AI 任务。任务不会被创建,用户会被带到 /system/insufficient-credits。
用户在 /app/credits/ledger 查看完整账本和余额是否一致的标识,在 /app/credits/reservations 查看预留和退还记录。pnpm validate:credits 会检查积分不足的处理、余额偏差修复和页面接线。
常见问题
任务因积分不足失败
可用余额低于任务价格。仍在运行的任务所冻结的积分不计入可用余额。发放积分或购买设置了 包含积分 的方案,然后重试。
Reservation is already settled.
该预留已被扣除或退还。每笔预留只结算一次,重试扣除或退还前先检查它的状态。
账本页面显示余额不一致
存储的余额不再等于账本之和,通常是直接修改了数据库。在后台打开该用户,点击 修复余额快照。
付费方案没有增加积分
确认方案 en 那一行的 包含积分 大于零,并在 商业化 → 订单 中确认订单已付款。如果订单仍为待付款,参考 接入支付服务商。