Open4X Docs

简体中文

English

简体中文

English

Appearance

平台托管 AI：上游、价格与客户折扣 ​

平台托管模式由 Open4X 配置上游凭据、模型和价格。商户仅使用自己的 Open4X API Key，不需要取得上游 Key。原有 BYOK 服务配置和计费保持不变。

发布前提

此功能需要网关、运营后台、商户控制台同步更新，并应用 0057_managed_ai.sql。代码和文档不代表某个线上环境已开通模型；应以该环境的模型目录为准。首版仅支持 OpenAI-compatible 文本聊天、SSE 聊天流和文本 embeddings，不包含 Jev、图片、音频、tools 或任意请求转换脚本。

运营配置 ​

入口：Open4X 运营后台 → AI services。只有 platform_admin 可以修改；finance 只能查看。普通商户管理员不能访问平台定价和上游成本。

  1. Upstreams：新增上游，填写唯一 ID、名称、直接 HTTPS Base URL、Bearer 或 X-API-Key 密钥、超时和并发。API 路径会追加 /chat/completions、/embeddings 或 /models。自建 Qwen 的地址应指向真实推理服务，不能填 Open4X 网关以免循环转发。
  2. Models & prices：新增草稿，指定对外 alias、上游模型 ID、支持能力和输入/输出 Token 上限。
  3. Publish price：发布 USD 价格，分别填写每百万输入、输出、缓存输入 Token 和每请求的销售价及上游成本价。零价格必须显式填写。低于成本需勾选确认，操作有审计记录。
  4. 价格发布后将模型设为 Active，商户模型目录才会显示；暂停模型或上游后停止接受新调用，不强行中断已开始请求。
  5. Customer offers：指定商户所属账户的数字 ID 和模型，配置折扣或合同价、UTC 起止时间。80% 表示支付原价的 80%，即八折。使用团队工作区时，该 ID 是计费归属账户，不是客服坐席 ID。

密钥以 AES-GCM 加密保存，列表和审计不返回明文或密文。编辑上游时，空的 replacement key 保留原密钥；修改地址必须重新输入密钥。Test connection 只检查 /models 的连接与 HTTP 状态，不生成内容，不等价于完成模型推理验收。真实请求开关关闭时，此检查也会拒绝执行。

模型更换上游或上游模型名时，须先保存为 draft/inactive，重新确认并发布成本和售价后再启用。历史价格和已开始请求的计费快照不变。

商户选用 ​

入口：商户控制台 → AI Model Gateway → 创建服务 → Billing Mode 选择 Open4X managed。

选模型时会显示当前商户的成交单价。后台保存的服务配置示例：

json
{
  "service_id": "ai-model",
  "alias": "assistant",
  "config": {
    "mode": "managed",
    "model_alias": "standard-chat",
    "max_cost_per_request": 0.05
  }
}

通过 POST /console/services 创建或更新以上配置。此接口需要商户登录身份及 service:manage 权限。model_alias 必须是已启用、有价格的模型。客户端提交的上游地址、密钥等字段不会进入托管配置。

业务服务端持有 scope 为 ai:invoke 的 Open4X Key，并限制到 ai-model:assistant。不要在浏览器或 Widget 中存储它。

bash
curl https://api.open4x.com/v1/apps/ai/assistant/v1/chat/completions \
  -H "Authorization: Bearer $OPEN4X_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-request-id" \
  -d '{"model":"standard-chat","messages":[{"role":"user","content":"你好"}],"max_tokens":512}'

model 可省略；提供时必须与服务配置的对外 alias 一致，不能指定任意上游模型。响应中的模型名也是对外 alias。流式调用加 "stream":true，embeddings 使用 /v1/apps/ai/assistant/v1/embeddings 并传 input 文本。

价格合同 ​

  • 币种固定 USD。输入单价针对非缓存输入；缓存输入是输入 Token 的子集，不重复收费。
  • 每商户、每模型仅一个当前优惠。合同价直接替换公开价格；百分比折扣应用于四项销售费用。二者互斥，不叠加。
  • 过期、未开始或停用的优惠不参与新请求。修改优惠会增加版本。
  • 每次发布价格生成不可变版本；请求开始时保存价格、成本价、折扣及其版本快照，进行中的请求不受后续改价影响。
  • 计算使用整数精度，最终客户单次费用向上取整到现有账本最小单位 0.0001 USD。因此极低单价请求仍可能收取 0.0001 USD；明确零费率或 0% 成交比例的请求为零。账单精度不是上游成本计量精度。
text
费用 = [(输入 - 缓存输入) × 输入单价 / 1,000,000
      + 缓存输入 × 缓存单价 / 1,000,000
      + 输出 × 输出单价 / 1,000,000
      + 按次费用] × 成交比例

预算、失败与重试 ​

发出上游请求前，按模型配置的整个输入 Token 上限及本次输出上限预留预算，不是按字符粗估直接扣最终费用。服务和请求同时指定 max_cost 限制时取更严格者；这里限制的是预留金额。余额不足返回 402，预留高于限制返回 409，均不调用上游。

模型单次请求的 JSON 字节上限为配置输入 Token 上限的四倍；这不是精确 tokenizer 校验。上游仍可能因上下文超限拒绝请求。

成功后按上游实际 usage 结算并释放余款。上游失败、无效响应或 SSE 中断会释放预留。成功响应缺少 usage，或计算费用超过预留时，不按估算收费：释放全部预留，标记 review。商业启用前必须验证上游能准确提供 usage，包括 SSE 最终 usage 和 [DONE]。

账务结算失败时保留预留并标记复核，不能宣称已经成功扣费。运营可在 Usage & settlement 对复核中或已过期的未结算预留执行 Release reservation，必须填写审计原因。不能释放仍在租约内的运行中请求，重复释放不会重复退款。首版不提供自动补扣。

同一商户重复使用 Idempotency-Key 返回 409，不会再次调用或扣费；不是结果缓存，也不会重放旧回答。网络结果不确定时先查账单，不要立即换新 Key 重试。首版不自动跨 Provider 重试或降级，不会悄悄把客户数据交给其他上游。

总请求超时为上游配置的 timeout_ms（含完整流式请求，1–120 秒）。并发以数据库预留记录原子控制，超过上限返回 429。已有 API Key 的来源限制、速率和每日配额继续生效。测试/staging 环境默认禁止真实 AI 调用；不能把 dry-run 当作真实 Provider 验收。

查询与审计 ​

接口用途
GET /console/services/managed-ai/models当前商户可选模型及成交价格，不含成本或密钥
GET /console/services/managed-ai/usage当前商户最近 100 条请求、价格 ID、预留和结算状态
GET /ops/ai/models/:alias/prices平台查看最近 100 个价格版本
GET /ops/ai/requests平台查看最近 200 条结算记录与配置成本估算
GET /ops/audit-logs查看配置、密钥轮换、价格发布和人工释放记录

reserved_units / final_units 的单位是 0.0001 USD；final_units:null 表示尚未结算。provider_cost 是配置成本价乘实际用量的估算，不是供应商已确认发票。响应带 X-Request-ID、X-Open4X-Price-Version 和 X-OpenEdge-Estimated-Cost。非流式成功响应另带 X-OpenEdge-Final-Cost；SSE 最终费用需查询账单。

首版列表有上述数量上限，尚无大规模历史导出。计费记录不保存消息正文、提示词或回答。自托管推理仍需要从云端 Open4X 传输必要输入到推理服务，不等于数据完全不离开本机。

下载管理接口 OpenAPI

AI 接入检查提示词 ​

text
请检查本项目的 Open4X 平台托管 AI 接入，不要输出任何真实密钥。
确认服务配置 mode=managed，model_alias 来自本租户模型目录；业务 API Key 仅在服务端保存，scope=ai:invoke，service_aliases 限制为 ai-model:<服务别名>。
检查请求 model 使用对外 alias，不使用真实上游模型名；不要发送首版不支持的 tools、图片或任意额外参数。
检查 max_cost 覆盖按模型输入上限计算的预算预留，不能把预留当作最终费用。
核对实际 usage、缓存输入、价格版本、折扣、0.0001 USD 向上取整、SSE 结束和中断退款。
验证 402、409、429 和 5xx；不在结果未知时自动换 Idempotency-Key 重试；缺失 usage 和结算失败要显示复核状态。
AI 不可用时维持人工客服流程。报告证据、未验证项和修复建议，不自行修改线上价格、余额或真实上游配置。