调用指南与路由说明

适用角色：开发者、主用户、子用户 更新日期：2026-08-06

本页说明 model 字段的两种写法、路由优先级和调用名获取方式。

一、基础路由：模型名称调用

绝大多数场景下，在 model 字段填写模型名称（如 deepseek-v4-flash、kimi-k3），系统会自动为你选择路由分组。

路由解析优先级

模型名称调用先要求 Key 已绑定路由分组，再按以下规则处理：

• 两层默认路由均无可用候选时，调用会被拒绝
• 绑定分组被撤权、禁用或订阅失效时直接报错，不通过回退掩盖权限变化
• 选定的账号不可用时，平台返回错误，不会自动切换或降级

默认路由配置

主用户和子用户可以为每个模型名称指定回退分组。Key 仍必须绑定分组；只有目标模型不在绑定分组内时才会查询默认模型配置。配置入口在控制台中，可逐个模型设置，也可按供应商批量设置。

使用记录中会显示每次调用的来源标识（分组标识 / Key 绑定分组 / 子用户默认 / 主用户默认），方便排查路由走向。

默认模型配置页面：

如果默认路由配置的分组已被下架或不再包含该模型，调用会报错，不会静默回退到其他分组。遇到此情况需重新配置默认路由。

二、进阶路由：分组标识调用（需开启）

启用分组标识路由后，可以在模型名前添加分组标识，例如 5MHXZWKA/deepseek-v4-flash。请求会直接进入该分组，不再使用 Key 绑定和默认路由配置。

开启条件

该功能由主用户在组织设置中启用。开关生效后，组织内用户可以在各自权限范围内使用分组标识调用名。入口未显示或调用被拒绝时，请联系主用户确认组织设置。

分组标识调用名格式

<分组标识>/<模型名称>

示例：5MHXZWKA/deepseek-v4-flash

• 5MHXZWKA 是分组的标识，平台为每个路由分组自动分配的短字符标识，创建后保持不变
• deepseek-v4-flash 是模型名称
• 调用时，请求固定路由到该分组标识对应的分组，与 Key 绑定的分组和默认路由配置无关

「调用指南」页面

控制台左侧菜单的「调用指南」入口始终可见。该页面按分组列出当前可用的调用名；分组标识路由开启后还会额外显示带分组标识的调用名：

• 模型名称按钮：复制模型名称（如 deepseek-v4-flash），走基础路由
• 分组标识按钮：复制带分组标识的调用名（如 5MHXZWKA/deepseek-v4-flash），走分组标识路由

页面支持按平台 Tab 切换、关键词搜索、专属/公开分组筛选。

分组标识路由未开启时，带分组标识前缀的调用会被拒绝。普通模型名称可在「调用指南」页、默认模型配置页或通过 /v1/models API 获取。

三、完整路由解析链路

平台在收到请求时，首先判断 model 字段是否包含分组标识前缀（含 /）：

model 字段含 "/" ?
├── 是（如 5MHXZWKA/deepseek-v4-flash）
│   └── 分组标识路由已开启？
│       ├── 是 → 解析分组标识
│       │   ├── 解析成功 → 路由到对应分组
│       │   └── 解析失败（标识无效或格式不合法）→ 拒绝
│       └── 否 → 拒绝（fingerprint_routing_disabled）
└── 否（如 deepseek-v4-flash）
    └── Key 是否绑定分组？
        ├── 否 → 直接拒绝
        └── 是 → 目标模型是否在绑定分组内？
            ├── 是 → 走绑定分组
            └── 否 → 当前用户默认 → 主用户默认
                ├── 命中可用候选 → 路由到该分组
                └── 均未命中 → 拒绝

四、什么场景用哪种

五、调用示例

模型名称（基础路由）：

curl https://<接口地址>/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'

带分组标识（分组标识路由，需开启）：

curl https://<接口地址>/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "5MHXZWKA/deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'

端点、认证、流式等通用规则见 API 调用基础。

六、常见问题

Q：我必须开启分组标识路由吗？ A：不必须。大多数场景给 Key 绑定分组后使用模型名称即可；目标模型不在绑定分组内时可配置回退分组。分组标识路由是精确点名分组的进阶能力，按需开启。

Q：带分组标识和模型名称，计费有区别吗？ A：计费按实际命中的分组定价，与调用名写法无关，取决于最终走到哪个分组。

Q：同一把 Key 用模型名称和分组标识混着调，可以吗？ A：可以（分组标识路由开启时）。平台按每次请求的 model 是否带分组标识分别判定路由。注意：如果这把 Key 绑的是订阅型分组，用分组标识跨组调用时还需要额外开启「订阅跨组调用」，否则跨组调用会被拒绝。详见 订阅管理与成员分配。

Q：带分组标识调用时报 fingerprint_routing_disabled 或 group_not_allowed 怎么办？ A：fingerprint_routing_disabled 表示分组标识路由未开启，联系主用户在组织设置中启用。group_not_allowed 表示该分组标识对应的分组不在你账户的可用范围内，或该账号当前不可用。确认可用范围或联系平台。

Q：默认路由配置了但调用报错？ A：检查配置的分组是否仍包含该模型，分组下架或模型移除后，对应的默认路由配置会失效，需重新设置。

Q：使用记录里"来源"是什么？ A：标识本次调用是通过分组标识、Key 绑定分组、子用户默认或主用户默认哪一层命中的，方便排查路由走向。

Q：分组标识路由关闭后，已有的带分组标识调用会怎样？ A：会被拒绝。关闭分组标识路由后，所有带分组标识前缀的调用都不再被识别，需改用模型名称。