79 lines
7.8 KiB
Markdown
79 lines
7.8 KiB
Markdown
# 模型目录与多模型 Key 授权
|
||
|
||
用户端此前只使用 `/api/models` 的 `models` 字段(可用分组),未使用 `logicalModels`(已发布模型)。因此已导入但分组未启用的模型只出现在管理端。
|
||
|
||
现在模型广场按已发布模型展示,每个模型只显示一张卡片,详情中列出可调用分组、调用 ID 和价格。无可用分组的模型显示“待上线”,试用按钮禁用。管理员停用或删除的模型不会显示。模型列表和权限授予仍使用原有的渠道、模型、分组状态检查,本次没有新增数据库迁移,也没有批量启用或调整价格。
|
||
|
||
API Key 权限窗口支持同时勾选多个模型,再选择各自的分组;只有一个分组时自动选中。顶部显示全部已选分组,搜索与翻页不清空授权,可以逐项移除或清空。保存的是原有分组 ID 数组,旧 Key 无需重新创建。
|
||
|
||
模型广场、管理端模型/渠道和 API Key 列表默认每页 12 项,可选 24/48 项。权限列表默认每页 8 个模型,可选 16/32 项。筛选或每页数量改变时回到首页;删除导致页数减少时自动回到有效页。
|
||
|
||
## 两层并发限制
|
||
|
||
一次同步模型调用要同时通过两层并发保护:
|
||
|
||
1. **平台 API Key 并发**:限制同一个用户 Key 同时进行中的请求数量。默认值为 4,可在服务端环境变量 `GATEWAY_DEFAULT_KEY_CONCURRENCY` 调整;每个 Key 独立计数,不会因为其他用户占满而互相阻塞。
|
||
2. **上游分组并发**:限制同一个渠道分组向中转站发出的同时请求数量,供使用该分组的多个用户共享。管理员在模型与分组中填写“上游分组并发上限”;1 表示串行,4 表示最多同时处理 4 个请求。
|
||
|
||
两层限制会同时生效。同步/流式请求先尝试原子取得“模型分组 + 平台 Key”两个并发槽;若任一层满额,则在平台内进行有界等待,默认最多 30 秒(`GATEWAY_QUEUE_WAIT_MS`),每 100 毫秒重试一次(`GATEWAY_QUEUE_POLL_MS`)。等待时不会占着另一层资源;获得两个槽后才向上游发起请求,超时才返回 429 和 `Retry-After`。API Key 的每分钟请求频率和并发数是不同设置;异步任务另受任务队列上限控制。
|
||
|
||
这里的数值是 MOYI 配置的保护上限,不是性能压测上限,也不是中转站承诺的账号额度。上游账号可能还有跨模型共享的并发/RPM/TPM限制;需要用有效上游密钥做阶梯压测或由渠道方确认后,再提高 MOYI 分组上限。
|
||
|
||
## 用户操作指南
|
||
|
||
1. 在模型广场先按模型厂商筛选,再打开模型详情选择渠道分组;复制详情中的“调用模型 ID”。
|
||
2. 在 API Keys 创建密钥时,可以一次勾选多个模型和多个分组。完整密钥只显示一次,请立即保存;停用的密钥可以重新启用。
|
||
3. 在线调试选择已有的启用 API Key、模型和分组即可,不需要为每次测试重新创建密钥;请求和响应会保留到使用记录。
|
||
4. 外部应用使用用户端显示的统一 Base URL,路径为 `/v1`,聊天接口为 `/v1/chat/completions`,通过 `Authorization: Bearer <API_KEY>` 认证。
|
||
5. 使用记录查看模型、厂商、渠道分组、Token、费用、耗时和时间;任务中心查看异步任务进度与结果。余额、权限或并发不足时,按错误提示处理后再重试。
|
||
|
||
## 两种接入路径
|
||
|
||
### 路径 A:用户自己的系统接入
|
||
|
||
1. 在模型广场按模型厂商筛选,打开模型详情,选择已上线的渠道分组并复制“调用模型 ID”。模型厂商是实际研发方,渠道分组是请求经过的中转站或官方接口,两者不是同一个字段。
|
||
2. 在 API Keys 创建用户 Key,同时勾选要使用的模型和分组。完整 Key 只在创建后显示一次,必须放在服务端环境变量或密钥管理器中,不能写入浏览器代码、Git 仓库或日志。
|
||
3. 使用用户端显示的统一 Base URL。当前聊天接口是 `POST {BASE_URL}/chat/completions`,认证头是 `Authorization: Bearer {MOYI_API_KEY}`,请求体中的 `model` 使用调用模型 ID。
|
||
|
||
```bash
|
||
curl "$MOYI_BASE_URL/chat/completions" \
|
||
-H "Authorization: Bearer $MOYI_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"model":"<model-id>","messages":[{"role":"user","content":"你好"}]}'
|
||
```
|
||
|
||
常见 OpenAI SDK 只需指定 `base_url` / `baseURL` 和 API Key;流式聊天在请求中增加 `stream: true`。调用前可用 `GET {BASE_URL}/models` 检查当前 Key 已授权的模型。3D 和视频模型使用 `/3d/tasks`、`/video/tasks` 提交异步任务,再通过 `/tasks/{id}` 查询结果,不能发送到聊天接口。
|
||
|
||
### 路径 B:Cherry Studio、OpenCode、Codex 等客户端
|
||
|
||
这些客户端必须选择 **OpenAI-compatible / Chat Completions** 类型,并填写三项:
|
||
|
||
| 字段 | 填写内容 |
|
||
| --- | --- |
|
||
| API URL / Base URL | 用户端显示的统一 Base URL,例如 `https://你的域名/v1` |
|
||
| API Key | 用户在 MOYI 创建的 API Key |
|
||
| Model | 模型详情中的调用模型 ID |
|
||
|
||
- **Cherry Studio**:添加自定义 OpenAI 兼容服务商,填 Base URL、Key,手动添加模型 ID。若客户端会自动补 `/v1`,不要重复填写,最终请求应落到 `{BASE_URL}/chat/completions`。
|
||
- **OpenCode**:新版可在 `opencode.jsonc` 的 `providers` 中使用 `@opencode/ai/providers/openai-compatible`,设置 `settings.baseURL` 和模型 ID;运行 `/models` 后选择该模型。旧版配置键可能显示为 `provider`,以本地版本示例为准。
|
||
- **Codex**:只有能切换到 Chat Completions/OpenAI-compatible 后端的客户端形态可以直接使用 `openai_base_url` 和 `OPENAI_API_KEY`。部分新版 Codex 工作流默认请求 `/v1/responses` 或专用工具接口,当前 MOYI 尚未承诺兼容这些接口;若不能切换协议,会出现 404 或参数错误,应暂时使用 Cherry Studio、OpenCode 的兼容模式。
|
||
|
||
第三方客户端只保存用户自己的 MOYI Key;中转站账号、上游 API Key 和供应商凭据始终只配置在管理端渠道,不能发给用户。
|
||
|
||
## 接入前检查清单
|
||
|
||
- 模型详情存在至少一个“已启用”的渠道分组,并且分组有上游模型 ID、渠道凭据和人民币价格。
|
||
- API Key 已授权目标模型和目标分组,Key 状态为正常;不需要为每个客户端重新创建 Key,可以复用同一个 Key 或按应用分别创建多个 Key。
|
||
- Base URL 只保留平台域名和 `/v1`,不要填完整的 `/chat/completions`;模型 ID 不要使用模型展示名称。
|
||
- 先用短文本请求测试,再启用流式;3D/视频先提交异步任务并轮询状态。
|
||
- 401 检查 Key,403 检查模型授权,404 检查模型 ID 或接口路径,429 检查 API Key 并发和上游分组共享并发,余额或渠道错误交给管理员检查。
|
||
|
||
## 验证
|
||
|
||
- `cd prototype; npm test`:目录合并、无可用分组的模型、多模型授权集合和分页边界,以及既有流式响应测试。
|
||
- `PlatformAdminPostgresTest#publicCatalogIncludesPendingModelsAndKeyCanKeepMultipleModelGrants`:隔离 PostgreSQL 上读取用户目录,通过 HTTP 保存两个不同模型的授权、重新读取,再撤掉其中一个;确认不能授权未上线的模型定义 ID。
|
||
- `cd prototype; npm run dev -- --host 127.0.0.1 --port 4178` 后打开 `/tests/catalog-preview.html`:本地测试页提供 315 个模型、10 个有上线分组的模型和 14 个 Key。所有 fetch 请求由页面内存响应,不使用真实凭据、不调用中转站。测试页不进入生产构建。
|
||
- 页面回归:模型目录第 27 页、筛选重置、待上线详情、跨页选两个模型共三个分组、保存重开、撤掉单个分组、管理端末页。
|
||
|
||
上线后刷新浏览器,在模型广场查看新目录。待上线条目需要管理员完成渠道凭据、分组人民币售价和启用配置后才能用于真实调用。
|