Files
moyi-model-intelligence-hub/docs/16-streaming-chat-billing.md
T

5.8 KiB
Raw Blame History

流式聊天与人民币计费

2026-09-20 新增,数据库迁移 V13。代码和本机测试完成不代表服务器已升级;ApiHub/APIPro 的线上同步联调证据见 渠道清单。

管理端配置

在“模型与分组 → 编辑分组”填写输入、输出人民币售价,单位必须为 CNY / 1M tokens(人民币 / 百万 Token)。缓存输入价可选,留空沿用输入价。每项最多 8 位小数;明确填写 0 表示免费,留空不是免费。真实模型缺少价格或使用其他币种/单位时返回 MODEL_NOT_PRICED,不会请求上游。

例如本机测试使用输入 2、输出 4、缓存输入 1;这只是测试数据,不是 ApiHub/APIPro 正式售价。输入 100 Token(其中缓存 60)、输出 80 时:

费用 = ((100 - 60) × 2 + 60 × 1 + 80 × 4) / 1,000,000 = 0.00034 元

按实际 usage.prompt_tokens、completion_tokens 和缓存输入统计计算,人民币金额保留 8 位小数、四舍五入。缺少合法用量时不估算收费。Mock 路由明确免费。

调用者账户必须有足够余额,包括超级管理员自己的 API Key;管理端“用户与额度”可发放/调整。用户看到的可用额度等于账面余额减正在调用的预留金额。本月消耗来自扣费流水,不补算旧记录。

一次调用的账务行为

  1. 验证 Key、模型权限、上游配置、请求参数、限流和并发后,锁定用户钱包并预留费用。预留采用文本请求字节数与消息开销的保守输入估计,加最大输出 Token;它不是最终扣款。
  2. 调用开始即记录请求 ID、分组、来源、同步/流式模式和开始时间。价格保存快照,调用期间改价不会影响本次结算。
  3. 上游正常结束且用量完整时,在同一 PostgreSQL 事务中更新余额、写入一条模型扣费流水并完成使用记录。同步和流式使用相同公式。
  4. 上游错误、超时、缺失用量、缺失完成标记时,本平台不扣费并释放预留;中转站是否收费取决于其账单。服务进程崩溃留下的预留在 5 分钟过期后由每分钟运行的恢复任务释放。
  5. 用户关闭页面或停止接收时,服务端会在请求时限内继续读取上游最终用量;正常完成仍按实际量收费。UI 提示到使用记录确认最终状态,“停止接收”不等于取消上游任务。

并发请求共享钱包锁,不能重复花掉已预留金额。管理员减少/设置余额不能侵占预留额度。少数上游若报告超出保守预留的实际用量,仍按真实用量计费;余额可能成为负数,之后阻止新调用,补足后恢复。不会把超额使用悄悄截成免费,也不会自动向用户支付工具扣款。

Idempotency-Key 可选,1–128 字符,同一账号范围内防重。重复编号返回 HTTP 409,不重放响应、不再次请求上游;请按请求 ID 查记录。更换 Key 但属于同一账号也不能重复提交同一编号。在线调试每次点击自动生成新编号。即使客户端未提供此头,单次结算也只写一次流水。

流式接口与限制

  • POST /v1/chat/completions,stream:true 返回标准 SSE,逐段转发,不等待完整文本再展示;启用 stream_options.include_usage 以获得上游用量。
  • 支持文本消息、文本数组、函数工具参数、采样参数、reasoning_effort / thinking 等白名单参数透传。是否被上游接受取决于具体模型。不会执行模型提出的函数调用。
  • 单请求 n=1;max_tokens 或 max_completion_tokens 二选一,1–32768,未填写默认 4096。输出上限也用于预留估计。
  • 请求最大 256 KiB、最多 256 条消息;图片/音频等多模态输入当前拒绝,避免按文本误计。未知参数返回错误,需增加明确适配后开放。
  • 上游最长 90 秒(包含响应体),单帧 256 KiB,总响应有大小限制。对超过此时限的长推理任务需要后续单独设计。JSON 同步响应上限 4 MiB;流式按解析字符量限制。
  • 流式记录首 Token 耗时,保留有限长度的文本、思考和工具调用历史;转发内容不会因历史截断被截短。
  • 上游在开始输出前报错返回非 200;开始输出后发生错误以 SSE error 通知。客户端必须检查错误和 [DONE],不能仅凭 HTTP 200 判定成功。
  • 响应头 X-Request-Id 对应使用记录;同步响应额外提供 X-Moyi-Cost-CNY。流式最终费用到使用记录查询。

本次计费只覆盖文本聊天。真实 Tripo/Seedance 异步执行器、支付充值、跨币种自动换汇、Responses/Anthropic 原生协议均不包含在此版本。

升级与验收

先备份数据库,再解压到新的 release 目录,复制当前 .env.cloud 和证书,保留原有 SMTP/SMS、加密密钥、RDS/Tair 配置。启动前运行 deploy.py check --mode https --network,按正常发布流程构建并启动。数据库迁移由 Flyway 自动执行;不要手工改旧迁移或重复执行 SQL。

升级后执行 deploy.py smoke --mode https --login。然后在测试账号下给指定分组设定已确认售价、发放少量余额,分别发起同步与流式短请求,核对使用记录与余额流水,最后停用测试 Key。无正式售价时保留空值,系统会阻止真实调用。

V13 新增钱包预留、账单请求表并允许已发生用量形成欠款。不能只恢复旧镜像来恢复旧计费行为;回退需要维护窗口并评估数据库备份/新增账务的保留方式。

本机测试覆盖真实 PostgreSQL 迁移、并发预留、缓存价计算、价格快照、重复结算、HTTP 幂等、同步/流式等价、上游错误、缺少 usage、浏览器断开后结算、过期恢复、事务回滚及余额欠款拦截。浏览器界面验收使用本机模拟响应,不连接中转站。