配置智能路由

功能与适用范围

智能路由是一种文本生成 Model API 服务类型。您在网关中维护一个候选模型池，应用只需在请求的 model 字段声明本次调用的优化目标，AI 网关会结合请求特征、目标和候选模型的可用能力，选择合适的候选模型执行请求。

当前智能路由支持OpenAI 兼容和Anthropic 兼容的文本生成 Model API。应用仍使用原有协议和对应路径调用，例如 OpenAI 兼容的 Chat Completions 或 Responses 路径，以及 Anthropic 兼容的 Messages 路径；无需为智能路由接入新的应用协议。

智能路由适合简单问答、内容生成、代码辅助和 Agent 等请求类型混合的业务。您可以在不修改应用中具体模型名称的前提下，集中调整候选模型池，并按成本、质量或响应速度选择不同的优化目标。

智能路由的工作方式

1. 在 Model API 中配置候选来源：可以使用系统内置模型、您自定义的模型服务（包括 BYOK 模型），也可以同时使用两种来源。

2. 调用方在请求的 model 字段中填写 auto/<目标>，表达本次调用更重视成本、质量、速度还是综合均衡。

3. 网关只会在满足当前协议、请求路径、输入输出类型、Token 上限和能力要求的候选模型中进行选择。

4. 选中的模型通过其关联的 AI 服务执行请求，响应仍按照您选择的 OpenAI 兼容或 Anthropic 兼容协议返回。

优化目标表达的是业务偏好，而不是固定模型名称或强制规则。例如，auto/cheap 会在可用候选中优先考虑成本更低的模型，但不会绕过协议、能力或输入限制；它也不承诺每次都调用同一具体模型或绝对价格最低的模型。

前提条件

• 已创建 AI 网关实例，并具备该实例的 Model API、AI 服务和模型元信息配置权限。

• 智能路由需要单独开通。在创建 Model API 时选择智能路由后，如果页面显示请开通智能路由，请单击前往开通并按页面指引完成开通。功能未开通时，无法完成智能路由配置。

• 已为自定义模型创建可用的 AI 服务，并完成服务的访问凭据、网络和连通性配置。

• 已维护模型元信息，并确保模型元信息中的协议路径和能力与上游模型实际能力一致。

• 智能路由 Model API 默认启用消费者鉴权，且在服务类型为智能路由时不能关闭。已为调用方创建消费者、配置认证凭据，并向该消费者授予目标 Model API 的调用权限。

准备候选模型

候选模型由“模型元信息 + 模型供应商 + 已关联的 AI 服务”共同确定。智能路由不会把名称相同但未关联服务、协议不匹配或元信息缺失的模型作为可用候选。

创建智能路由 Model API

1. 登录AI 网关控制台，进入目标 AI 网关实例。

2. 在左侧导航栏选择Model API，然后单击创建 Model API。

3. 在文本生成场景中，选择应用所使用的OpenAI 兼容或Anthropic 兼容协议。控制台会按协议生成相应的默认路由；请保留业务需要的路径。

4. 填写 API 名称、域名和 Base Path。API 名称仅用于管理和标识接口，不决定请求中的智能路由模型名。

5. 在大模型服务区域的服务类型中选择智能路由。如果出现请开通智能路由提示，请单击前往开通，完成开通后返回此页面继续配置。

6. 按业务需要启用系统内置模型、添加自定义候选模型，或同时配置两者。添加自定义候选时，选择已关联供应商的 AI 服务及其具体模型。

7. 确认默认开启的消费者鉴权配置，为调用方创建消费者、配置凭据并完成授权后，再完成域名和其他 API 配置，单击确定保存。若控制台提示发布或生效操作，请按提示完成发布。

调用智能路由

智能路由不使用 API 名称作为请求模型名。调用方必须在请求体的 model 字段中显式传入 auto/<目标>。例如，即使您的 Model API 名称为 my-router，请求模型名仍应为 auto/balanced。

curl https://<your-domain>/<base-path>/v1/chat/completions \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto/balanced",
    "messages": [
      {"role": "user", "content": "请帮我总结这段内容。"}
    ]
  }'

POST /v1/messages

{
  "model": "auto/quality",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "请为以下需求生成实现方案。"
    }
  ]
}

验证与日常维护

1. 在Model API列表中找到目标 API，使用控制台调试功能，分别以 auto/balanced 和业务需要的其他目标发送测试请求。

2. 验证 OpenAI 兼容或 Anthropic 兼容的实际调用路径、消费者认证凭据和请求格式与应用保持一致。

3. 新增模型、调整候选模型、修改 AI 服务或服务关联后，按控制台提示保存并发布配置，再通过业务请求验证。

4. 当上游模型升级、下线、变更协议能力、调整上下文长度或修改价格时，同步更新模型元信息和候选配置。

常见问题