Files
moyi-model-intelligence-hub/docs/17-catalog-and-key-selection.md
T
2026-09-24 14:30:20 +08:00

77 lines
7.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.
# 模型目录与多模型 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 个请求。
两层限制会同时生效,任一层达到上限都会返回 429,并带有短暂重试提示。API Key 的每分钟请求频率和并发数是不同设置;异步任务另受任务队列上限控制。
## 用户操作指南
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 页、筛选重置、待上线详情、跨页选两个模型共三个分组、保存重开、撤掉单个分组、管理端末页。
上线后刷新浏览器,在模型广场查看新目录。待上线条目需要管理员完成渠道凭据、分组人民币售价和启用配置后才能用于真实调用。