Files
moyi-model-intelligence-hub/docs/06-d4-integration-plan.md
T
2026-08-25 17:04:37 +08:00

102 lines
5.3 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.
# D4 密钥与模型目录实施计划
## 一、节点目标
D4 不先追求接入很多供应商,而是建立一条可替换的“MOYI Key → 统一模型目录 → Provider Adapter → Otari/异步任务适配器”链路。
首轮采用 Mock 完成控制面闭环,再选择一个文本/多模态模型和一个异步 3D 模型做真实联调。
开发管理员账号使用用户名 `adimin`;普通用户注册仍使用邀请码 + 邮箱或手机号。管理员密码只在本地 `control-plane/.env` 中配置。
## 二、首批供应商分层
### A. 文本/编码/多模态候选
智谱、阿里、Kimi 等国内模型供应商列为候选,不在代码中写死。真正进入联调前,需要从其中选择至少一个能够提供测试 Key、API 文档和限流说明的供应商。
### B. 3D 候选
VAST 合作方向作为 3D 优先候选;现有信息表明可以通过开发者 API Key/API 文档方式接入,后续再评估 SDK 接入。Tripo 官方 Key 页面说明 API Key 创建后仅展示一次,并建议使用环境变量保存,不要提交到版本控制:[Tripo API 密钥](https://developers.tripo3d.com/zh/keys)。
适配层必须把用户侧协议与上游实现隔离:
```text
用户应用
→ MOYI API Key
→ MOYI 统一模型 ID
→ VAST/3D Provider Adapter
→ 上游 HTTP API 或 SDK
```
SDK 不直接暴露给 MOYI 用户。后续如果上游从 HTTP API 切换为 SDK,只替换 Provider Adapter,不修改用户的 Base URL、MOYI Key 和统一模型名。
## 三、D4 先做 Mock 的内容
- MOYI Key 创建、只显示一次、停用和权限范围;同时支持个人 Key 与工作区/项目 Key。
- 额度按人民币 `¥` 计价展示,管理员可发放等值内测额度,支付、提现和退款后置。
- 模型目录:文本、代码、多模态、3D 类型和模型能力 Schema。
- 用户/项目/Key 到模型的访问权限。
- 供应商模型 ID 到统一模型 ID 的映射。
- 同步模型和异步模型的调用模式标记。
- 模型上下线和管理端基础页面。
- Otari 模型列表适配接口的 Mock 响应。
## 四、真实联调前的最小资料
### 文本/多模态模型
- 供应商名称和正式 API 文档。
- 测试 Base URL、API Key 和模型 ID。
- 请求/响应样例,是否支持流式。
- 上下文、输入文件、输出长度、超时、速率和并发限制。
- 供应商错误码、余额/额度查询方式和数据使用条款。
### 3D 模型
- VAST 或 AI SoulMate 的 API/SDK 文档。
- 测试 API Key 和测试环境。
- 文生 3D、图生 3D 的任务参数。
- 任务创建、进度查询、Webhook/轮询和取消方式。
- 输出文件格式、文件下载授权、保存周期和大小限制。
- 计费单位、失败/超时/取消规则和重试建议。
## 五、首轮验收建议
按 4—5 人、3—4 个项目的内部测试规模,先验收:
1. 管理员创建 MOYI Key 并限制模型范围。
2. 普通用户使用 MOYI Key 查看可用模型。
3. Mock 文本模型完成一次同步或流式调用。
4. Mock 3D 模型完成任务创建、排队、进度和结果状态闭环。
5. 管理员分配一笔额度或金额预算,并能查看用量。
6. 停用 Key 后调用被拒绝,且产生审计记录。
7. 将 Mock Provider 替换为一个真实供应商时,用户侧配置不变。
## 六、暂不进入 D4
- 真实支付、充值、退款和发票。
- 多供应商智能路由和复杂降级。
- 企业认证、团队审批和 BYOK。
- 正式公网开放、生产 SLA 和大规模并发承诺。
- 自托管模型和 GPU 调度。
## 七、D4 Mock 已实现接口
当前 Control Plane 已提供一套可供前端控制台联调的内存 Mock:
- `GET /api/models`:登录用户读取统一模型与供应商目录,目录中包含一个同步多模态模型和一个异步 3D 模型。
- `GET|POST /api/projects`:用户查看或创建工作区/项目,项目 Key 与个人 Key 并列存在。
- `GET|POST /api/keys`:用户查看或创建 MOYI Key;明文只在创建响应返回一次,服务端只保存 SHA-256 摘要。
- `POST /api/keys/:id/revoke`:用户撤销自己的 Key。
- `GET /v1/models`:使用 `Authorization: Bearer <MOYI_KEY>` 查询可调用模型。
- `POST /v1/chat/completions`:兼容 OpenAI 风格的 Mock 同步文本/多模态调用。
- `POST /v1/3d/tasks`、`GET /v1/tasks/:id`:Mock 异步 3D 任务创建与查询。
- `GET|POST /api/admin/providers`:管理员查看或登记供应商适配位。
- `GET|POST /api/admin/models`:管理员查看或登记统一模型目录。
Mock 目录使用内存仓库,重启会重置,适合原型与接口联调;`migrations/002_catalog_keys.sql` 已准备 PostgreSQL 表结构,后续接持久化仓库时保持 API 不变。
Tripo Provider Adapter 已按官方 v3 文档实现:服务端从 `TRIPO_API_KEY` 读取密钥,调用 `POST /generation/text-to-model` 创建异步任务,再通过 `GET /tasks/{task_id}` 查询状态、进度、消耗额度和模型下载地址。适配器不会把上游密钥返回给用户端。
2026-08-25 已完成首次真实文生 3D 验收:使用 `v3.1-20260211` 和 standard 质量生成低面数木质凳子,任务状态为 `success`、进度 100%,Tripo 记录消耗 20.0 积分,并返回 GLB 模型与 WebP 预览地址。验收记录不保存 API Key 和带签名的临时下载 URL。