Files
moyi-model-intelligence-hub/docs/17-catalog-and-key-selection.md
T

9.9 KiB
Raw Blame History

模型目录与多模型 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. 上游分组并发:可限制同一个渠道分组向中转站发出的同时请求数量,供使用该分组的多个用户共享。管理员在模型与分组中填写“MOYI 分组并发上限”;填 0 表示不设置 MOYI 分组上限,直接观察渠道方的真实限制;只有渠道明确给出共享上限时才填写正整数,1 才表示串行。

注意:这个数字来自 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 配置的保护上限,不是性能压测上限,也不是中转站承诺的账号额度。默认值为 0(不限制模型分组);上游账号仍可能有跨模型共享的并发/RPM/TPM 限制,达到时会返回上游限流错误。API Key 并发和请求频率仍然生效,方便先测渠道能力,再按渠道方确认的额度设置保护值。

渠道最大并发的实测方法

  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 <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。
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 页、筛选重置、待上线详情、跨页选两个模型共三个分组、保存重开、撤掉单个分组、管理端末页。

上线后刷新浏览器,在模型广场查看新目录。待上线条目需要管理员完成渠道凭据、分组人民币售价和启用配置后才能用于真实调用。