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

51 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 流式聊天与人民币计费
2026-09-20 新增,数据库迁移 V13。代码和本机测试完成不代表服务器已升级;ApiHub/APIPro 的线上同步联调证据见 [渠道清单](15-relay-onboarding.md)。
## 管理端配置
在“模型与分组 → 编辑分组”填写输入、输出人民币售价,单位必须为 `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、浏览器断开后结算、过期恢复、事务回滚及余额欠款拦截。浏览器界面验收使用本机模拟响应,不连接中转站。