模型级别的 Token 计费、用户钱包余额管理及管理员充值操作指南

模型计费与钱包

ResearchX 支持为模型开启按 Token 使用量计费，结合用户钱包系统实现费用管控。

整体架构

模型计费配置 → Token 使用产生费用 → 从用户钱包扣款 → 管理员可充值 / 调整余额

每个模型可独立开启或关闭计费
每个用户拥有独立钱包，记录余额、信用额度和账变明细
管理员可为用户充值、调整信用额度、禁用钱包
余额不足时用户无法发起新的模型调用

模型计费配置

在 /workspace/admin/models（系统模型）或 /workspace/models（个人模型）的编辑表单底部，找到 计费设置 区域。

配置项

字段	说明
启用计费	开启后，该模型每次调用都会按 Token 量计费
计费货币	当前仅支持 `CNY`（人民币）
输入价格（每千 Token）	输入 Token 的单价，单位为微元（μCNY，即 1/1,000,000 元）
输出价格（每千 Token）	输出 Token 的单价，单位为微元
最低收费	单次调用的最低扣费金额（微元），不足时按此金额收取

计费公式

单次费用（微元） = ⌈(输入 Token × 输入单价 + 输出 Token × 输出单价) / 1000⌉
实际扣费 = max(单次费用, 最低收费)

其中 ⌈...⌉ 表示向上取整。

价格换算参考

微元与元之间的换算关系：1 元 = 1,000,000 微元

场景	输入单价（微元/千Token）	换算
¥0.01 / 千 Token	10000	0.01 元
¥0.05 / 千 Token	50000	0.05 元
¥0.10 / 千 Token	100000	0.10 元

示例

假设模型配置：

输入价格：50,000 微元/千 Token（即 ¥0.05/千 Token）
输出价格：150,000 微元/千 Token（即 ¥0.15/千 Token）
最低收费：1,000 微元（即 ¥0.001）

一次调用消耗 2,000 输入 Token + 500 输出 Token：

费用 = ⌈(2000 × 50000 + 500 × 150000) / 1000⌉ = ⌈(100000000 + 75000000) / 1000⌉ = 175000 微元 = ¥0.175

用户钱包

每个用户在首次使用计费功能时自动创建钱包。钱包状态包括：

属性	说明
余额	当前剩余金额（可为负数，但不能低于 `-信用额度`）
信用额度	允许的透支上限，余额低于 `-信用额度` 时拒绝新的模型调用
累计充值	历史充值总额
累计消费	历史扣费总额
状态	`active`（正常）或 `disabled`（禁用，禁用后无法发起调用）

余额不足保护

当用户钱包余额低于 -信用额度 时，系统会返回 402 Payment Required 错误，用户无法继续发起模型调用，直到管理员充值或将余额调整到允许范围。

查看个人钱包与消费

访问 /workspace/token-usage 页面可查看：

钱包概览：余额、信用额度、累计消费、扣费次数
Token 用量统计：最近 30 天的 Token 消耗，支持按日期/月份/项目/模型/供应商/来源分组
用量趋势图：以柱状图展示输入/输出 Token 的分布
最近扣费记录：每笔扣费的时间、金额、扣后余额和描述

管理员操作

查看平台级消费汇总

访问 /workspace/admin/token-usage 页面可查看：

平台级 Token 用量总计
全平台累计消费和扣费笔数
用户消费排行：按用户展示 Token 用量、消费金额和当前余额
模型消费排行：按模型展示消费金额和扣费笔数

管理用户钱包

通过 /api/admin/users/{userId}/wallet 接口，管理员可：

查看钱包

GET /api/admin/users/{userId}/wallet

返回用户钱包信息和最近 50 条账变明细。

调整信用额度和状态

PATCH /api/admin/users/{userId}/wallet

{
  "credit_limit_micros": "5000000",
  "status": "active"
}

credit_limit_micros：新的信用额度（微元），不传则保持不变
status：active 或 disabled，不传则保持不变

充值 / 调整 / 退款

POST /api/admin/users/{userId}/wallet

{
  "amount_micros": "15000000",
  "entry_type": "recharge",
  "description": "月度充值"
}

字段	说明
`amount_micros`	金额（微元），正数
`entry_type`	`recharge`（充值）、`adjustment`（调整）或 `refund`（退款）
`description`	可选描述

充值和退款会增加用户余额，扣费会减少余额。所有操作都会记录到账变明细中。

费用自动扣款流程

用户发起聊天或 Agent 调用
系统检查用户钱包状态和余额（assertUserWalletCanStartUsage）
- 钱包被禁用 → 返回 402 错误
- 余额 < -信用额度 → 返回 402 错误
模型调用完成后，系统计算本次 Token 消耗对应的费用
如果模型开启了计费且费用 > 0，自动创建扣费记录并更新钱包余额
扣费记录包含当时的定价快照（pricing_snapshot_json），确保历史可追溯

常见操作

给用户充值

进入 /workspace/admin/users，找到目标用户
复制用户 ID
通过 API 或管理界面向用户钱包充值

为模型开启计费

进入 /workspace/admin/models（系统模型）或 /workspace/models（个人模型）
编辑目标模型
在计费设置区域勾选「启用计费」
填写输入价格、输出价格和最低收费
保存模型配置

禁用用户钱包

通过 PATCH /api/admin/users/{userId}/wallet 将状态设为 disabled，用户将无法使用任何计费模型。

注意事项

当前仅支持 CNY（人民币）计费货币
未开启计费的模型不会产生费用，也不会检查钱包余额
费用计算使用微元精度，避免浮点误差
管理员可在用户管理页面查看每个用户的钱包状态
Token 用量统计和计费是独立但关联的系统：用量统计始终记录，计费仅在模型启用时触发

模型计费与钱包

On this page