Model Groups

你的应用不应该需要知道上一次请求是哪个 Provider 回答的，也不应该每次想换个答案就要重新部署一次。Model Group 就是为此存在的：你的应用发送的 model 值是一个你自己掌控的名称，而不是某个 Provider 具体的 model ID。它把 Provider 账号、具体模型、fallback 和路由规则隐藏在一个稳定别名后面。

为什么需要 Model Group

• 有更好或更便宜的新模型上线了。 在控制台里更新这个 group 的 target 即可——所有发送这个 Model Group 名称的应用会立刻用上新模型，不需要重新部署。
• 主 Provider 出故障了。 配置好 fallback 路由后，网关会自动切到下一个 target；你的应用完全感知不到。
• 想安全地试用一个新模型。 以很小的权重把它加进负载均衡 target，观察效果，再决定调高权重还是移除——同样不需要改代码。
• 产品团队可以使用稳定名称，例如 coding-agent、smart-llm、reasoning 或 vision。
• 运维团队可以调整 Provider 或 fallback 规则，而不需要改业务代码。
• 财务团队可以按业务工作负载查看用量和费用，而不是只看 Provider key。
• 管理员可以把 Coding Plan backend 和按量计费 backend 放在同一个 group 中。

控制台里能看到什么

每一行都会显示 group 名称、健康状态、路由摘要、请求量、token 量、延迟和错误率。打开一个 group 后，可以查看 routing tree 和实时用量。

常见 Group 模式

General Assistant

使用强主模型，并在主模型失败或并发达到上限时切换到备用 Provider。

Coding Agent

优先使用 Coding Plan 容量，额度接近耗尽时 fallback 到按量计费 API 账号。

Fast Cheap

为抽取、分类和短回答等高频场景使用低成本模型池。

Vision

按文件大小、Provider 能力或延迟目标路由多模态请求。

多模态路由

机制说明： 同一个 Model Group 的路由树里可以混合具备不同多模态能力的 backend。当请求包含图片、音频、视频或文件时，网关会检查每个候选 backend 声明的支持情况，并跳过无法处理的 backend——不需要在请求里加任何额外字段，也不需要在客户端做分支判断。

使用方式： 在原有 backend 之外，往同一个 fallback 或负载均衡 group 里加一个支持多模态的 backend 即可。基于 Provider 目录创建的 backend 会自动带上已知的模态支持；自定义 backend 需要显式声明，才会被纳入多模态请求的路由候选。没有声明支持的 backend 会被当作纯文本处理。

使用场景： 一些最强、最便宜或最快的模型其实是纯文本的——例如 DeepSeek-V4 系列完全不支持图片输入。把图片发给这样的模型，要么直接报错，要么更糟——模型悄悄忽略图片、只根据文字回答，这种 bug 你可能要等用户投诉才会发现。与其在"用想用的模型"和"支持图片"之间二选一，不如把这个纯文本模型设为主 backend，再加一个支持视觉的模型作为 fallback，只在真正需要的请求上才会用到它。调用方始终对接同一个 Model Group 名称：纯文本请求依然走你偏好的模型，带图片的请求会自动绕开它，路由到支持图片的 backend，调用方不需要为此增加任何复杂度。如果 group 里所有 backend 都因此被跳过，请求会返回明确的错误，而不是被静默发到无法处理它的 backend 上。

最佳实践

• 按工作负载命名 group，不要按 Provider 命名。
• 每个主要产品场景保留一个生产 group。
• 修改路由后查看健康状态和费用变化。
• 删除共享 backend 前，先查看它被哪些 group 使用。