# 模型目录与多模型 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 个请求。 > **注意:这个数字来自 MOYI,不是渠道商返回值。** 早期目录迁移为了防止未经验证的路由压垮上游,把新建分组的 `max_concurrency` 初始写成了 `1`;因此管理端看到的 `1` 不能证明 ApiHub、APIPro、TokenFoundryX 或 Tripo 只允许一个并发。渠道商的账户并发、RPM、TPM 和跨模型共享额度必须通过渠道文档或实测确认。若要做渠道容量压测,先为目标分组临时设置足够大的 MOYI 上限,并同步提高测试 API Key 的并发和 RPM,避免平台自身的保护层先返回 `MODEL_BUSY`、`KEY_BUSY` 或 `RATE_LIMITED`。 两层限制会同时生效。同步/流式请求先尝试原子取得“模型分组 + 平台 Key”两个并发槽;若任一层满额,则在平台内进行有界等待,默认最多 30 秒(`GATEWAY_QUEUE_WAIT_MS`),每 100 毫秒重试一次(`GATEWAY_QUEUE_POLL_MS`)。等待时不会占着另一层资源;获得两个槽后才向上游发起请求,超时才返回 429 和 `Retry-After`。API Key 的每分钟请求频率和并发数是不同设置;异步任务另受任务队列上限控制。 这里的数值是 MOYI 配置的保护上限,不是性能压测上限,也不是中转站承诺的账号额度。上游账号可能还有跨模型共享的并发/RPM/TPM限制;需要用有效上游密钥做阶梯压测或由渠道方确认后,再提高 MOYI 分组上限。 ### 渠道最大并发的实测方法 1. 选定一个已授权、已计价且能稳定返回内容的模型分组,记录当前 `maxConcurrency`、测试 Key 的 `GATEWAY_DEFAULT_KEY_CONCURRENCY` 和 `GATEWAY_REQUESTS_PER_MINUTE`。 2. 暂时将该分组的 MOYI 并发上限设为高于预计阶梯的值(例如 100),并将测试 Key 的并发/RPM 设为高于测试阶梯;每次变更后重新读取管理端模型详情确认保存成功。 3. 用 `scripts/live-gateway-smoke.py --run-calls --max-concurrency N` 或等效压测脚本按 1、2、4、8、16…逐级发起短请求。每个阶梯应使用独立测试 Key,或在阶梯之间等待 RPM 窗口清空;否则累计请求会把平台自身的 RPM 限制误判为渠道限制。 4. 对每个阶梯记录成功数、HTTP 状态、错误码、首字节/总耗时,并区分 `MODEL_BUSY`/`KEY_BUSY`/`RATE_LIMITED`(MOYI 层)与上游返回的 429、限流或余额错误。第一个稳定出现的上游 429/限流阶梯才是该 Key/模型在当前账户和时段的观测上限。 5. 压测结束后恢复面向客户的并发、RPM 和 Key 限制。报告必须同时列出“观测上限”和“当前生产保护上限”,不能把任一数字写成渠道商的正式承诺。 ## 用户操作指南 1. 在模型广场先按模型厂商筛选,再打开模型详情选择渠道分组;复制详情中的“调用模型 ID”。 2. 在 API Keys 创建密钥时,可以一次勾选多个模型和多个分组。完整密钥只显示一次,请立即保存;停用的密钥可以重新启用。 3. 在线调试选择已有的启用 API Key、模型和分组即可,不需要为每次测试重新创建密钥;请求和响应会保留到使用记录。 4. 外部应用使用用户端显示的统一 Base URL,路径为 `/v1`,聊天接口为 `/v1/chat/completions`,通过 `Authorization: Bearer ` 认证。 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":"","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 页、筛选重置、待上线详情、跨页选两个模型共三个分组、保存重开、撤掉单个分组、管理端末页。 上线后刷新浏览器,在模型广场查看新目录。待上线条目需要管理员完成渠道凭据、分组人民币售价和启用配置后才能用于真实调用。