feat: stream chat and settle metered CNY usage atomically
This commit is contained in:
1 parent
7360cf3ebe
commit
b46ee72f2d
28 files changed
+1098
-86
No files matched your search
@@ -0,0 +1,50 @@
|
||||
# 流式聊天与人民币计费
|
||||
|
||||
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、浏览器断开后结算、过期恢复、事务回滚及余额欠款拦截。浏览器界面验收使用本机模拟响应,不连接中转站。
|
||||
Reference in new issue
Block a user