注册配置治理智能路由

操作场景
智能路由策略是 AI 网关在多模型服务场景下的流量分发能力。通过配置智能路由策略，您可以：
实现多模型服务的负载均衡和流量分配
根据模型名称自动匹配对应的后端服务
基于权重配置灵活控制流量比例
支持 A/B 测试、灰度发布等场景
配合 Fallback 机制实现高可用
本文档指导您如何在 AI 网关控制台配置和使用智能路由策略。
前置条件
已创建 AI 网关实例
已创建至少一个模型服务(内置供应商或自定义模型服务)
已创建模型 API
路由策略概述
 AI 网关支持多种智能路由策略：
路由策略
使用场景
决策依据
适用范围
按模型名称路由
多模型服务精确匹配
请求中的model字段与模型服务配置的模型名称匹配
单模型 API 需访问不同供应商的相同模型
权重路由
负载均衡、A/B 测试、灰度发布
按配置的权重比例随机分配流量
同一模型的多实例部署或多供应商混合部署
策略一：按模型名称路由
功能说明
按模型名称路由会根据客户端请求中的model字段自动匹配对应的模型服务。这种路由策略适用于以下场景：
同一个 API 需要支持多个不同的模型(如gpt-4o、gpt-4o-mini、claude-3-5-sonnet)
不同模型由不同的供应商或服务实例提供
需要精确控制每个模型的路由目标
需要使用通配符匹配一组模型(如gpt-4-*匹配所有 gpt-4系列模型)
配置步骤
步骤1：创建模型服务
在配置路由策略前，需要先创建模型服务：
1. 进入 网关管理 > 服务管理 > 模型服务
2. 单击 创建模型服务，配置供应商、访问凭证等信息
3. 保存模型服务
步骤2：在模型 API 中配置模型名称路由
1. 进入 网关管理 > 模型管理 > 模型 API，选择或创建 API
2. 在 第二步：选择模型服务 页面，配置服务类型和路由策略
3. 选择 服务类型 为 多模型服务
4. 选择 路由策略 为 模型名称路由
5. 在模型服务表格中添加服务并配置路由规则
配置参数说明：
参数
说明
示例
是否必填
模型服务
从已创建的模型服务列表中选择
gpt-4o-openai
是
匹配模型名
客户端请求的 model 参数匹配规则，支持精确匹配和通配符匹配(*)
gpt-4o 或 gpt-4-*
是
重写模型名
转发到后端服务时，将请求中的 model 参数重写为指定值。留空则透传原始值
gpt-4o 或留空
否
步骤3：保存并发布
配置完成后，单击 确定 保存配置。路由规则会立即生效。
配置示例
示例1：精确匹配多个模型
场景：单个 API 需要支持3个不同的模型，分别由不同的服务提供
配置：
模型服务
匹配模型名
重写模型名
gpt-4o-openai
gpt-4o
(留空)
gpt-4o-mini-openai
gpt-4o-mini
(留空)
claude-3-5-sonnet-anthropic
claude-3-5-sonnet
(留空)
测试请求：
# 请求1:路由到 gpt-4o-openai
curl -X POST https://{网关域名}/ai/llm/v1/chat/completions \\
  -H "Authorization:Bearer {API_Key}" \\
  -H "Content-Type:application/json" \\
  -d '{"model":"gpt-4o", "messages":[{"role":"user", "content":"你好"}]}'
﻿
# 请求2:路由到 claude-3-5-sonnet-anthropic
curl -X POST https://{网关域名}/ai/llm/v1/chat/completions \\
  -H "Authorization:Bearer {API_Key}" \\
  -H "Content-Type:application/json" \\
  -d '{"model":"claude-3-5-sonnet", "messages": [{"role": "user", "content": "你好"}]}'
示例2：通配符匹配模型系列
场景：希望所有gpt-4-*系列的模型都路由到同一个服务
配置：
模型服务
匹配模型名
重写模型名
gpt-4-family-openai
gpt-4-*
(留空)
gpt-3.5-turbo-openai
gpt-3.5-turbo
(留空)
测试请求：
# 请求1:匹配通配符规则,路由到 gpt-4-family-openai,透传model=gpt-4o
curl -X POST https://{网关域名}/ai/llm/v1/chat/completions \\
  -H "Authorization: Bearer {API_Key}" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]}'
﻿
# 请求2:匹配通配符规则,路由到 gpt-4-family-openai,透传model=gpt-4-turbo
curl -X POST https://{网关域名}/ai/llm/v1/chat/completions \\
  -H "Authorization: Bearer {API_Key}" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "gpt-4-turbo", "messages": [{"role": "user", "content": "你好"}]}'
﻿
# 请求3:精确匹配,路由到 gpt-3.5-turbo-openai
curl -X POST https://{网关域名}/ai/llm/v1/chat/completions \\
  -H "Authorization: Bearer {API_Key}" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "你好"}]}'
﻿
示例3：模型名称重写
场景：客户端使用自定义模型名称，但后端服务只识别标准模型名
配置：
模型服务
匹配模型名
重写模型名
gpt-4o-openai
my-custom-gpt4
gpt-4o
claude-3-5-sonnet-anthropic
my-custom-claude
claude-3-5-sonnet-20241022
测试请求：
# 客户端请求model=my-custom-gpt4,网关转发时重写为model=gpt-4o
curl -X POST https://{网关域名}/ai/llm/v1/chat/completions \\
  -H "Authorization: Bearer {API_Key}" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "my-custom-gpt4", "messages": [{"role": "user", "content": "你好"}]}'
﻿
# 转发到后端OpenAI服务的请求body:
# {"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]
路由匹配规则
匹配优先级
当同一个请求可以匹配多个路由规则时，按以下优先级匹配：
1. 精确匹配优先于通配符匹配
如果配置了gpt-4o(精确)和gpt-4-*(通配符)，请求model=gpt-4o会匹配精确规则
2. 匹配顺序按配置顺序
当多个通配符规则都匹配时，选择配置表格中最先添加的规则
3. 未匹配时返回404
如果请求的 model 参数无法匹配任何规则，返回错误响应
通配符规则
支持的通配符：
通配符
说明
示例
匹配结果
*
匹配任意字符(0个或多个)
gpt-4-*
匹配gpt-4-turbo、gpt-4o、gpt-4-0125-preview
gpt-*
前缀匹配
gpt-*
匹配所有以gpt-开头的模型
注意事项：
通配符*只能在匹配模型名字段使用，不支持在重写模型名字段使用
单个匹配规则只能包含一个通配符*
通配符大小写敏感，GPT-*不会匹配gpt-4o
模型名称重写逻辑
重写时机：
网关在转发请求到后端模型服务之前，会将请求 body 中的model字段替换为"重写模型名"配置的值
如果"重写模型名"留空，则透传客户端请求中的原始 model 值
典型场景：
场景
匹配模型名
重写模型名
客户端请求 model
转发到后端的 model
透传原始 model
gpt-4o
(留空)
gpt-4o
gpt-4o
统一模型标识
gpt-4-*
gpt-4-turbo-2024-04-09
gpt-4-turbo
gpt-4-turbo-2024-04-09
自定义别名
my-gpt4
gpt-4o
my-gpt4
gpt-4o
未匹配处理
如果请求的模型名称无法匹配任何路由规则，网关会返回：
{
  "error": {
    "code": "model_not_found",
    "message": "模型 'gpt-5' 不存在,请检查模型名称是否正确。可用模型: gpt-4o, gpt-4-*, claude-3-5-sonnet",
    "type": "invalid_request_error"
  }
}
错误信息中会列出当前 API 支持的所有匹配规则，方便客户端排查问题。
策略二：权重路由
功能说明
权重路由按照配置的权重比例将流量分配到多个模型服务。这种路由策略适用于以下场景：
负载均衡：为同一模型的多个实例分配流量，避免单点过载
A/B 测试：按比例测试不同供应商或模型版本的效果
灰度发布：小流量验证新服务，逐步放大流量比例
成本优化：将大部分流量导向成本更低的服务，保留少量高质量服务作为补充
配置步骤
步骤1：在模型 API 中配置权重路由
1. 进入 网关管理 > 模型管理 > 模型 API，选择或创建 API
2. 在 第二步：选择模型服务与路由策略 页面
3. 选择路由策略为 权重路由
4. 为每个模型服务配置权重。
配置参数：
参数
说明
示例
约束
模型服务
从已创建的模型服务列表中选择
qwen-plus-aliyun
-
权重
该服务的流量权重，范围1-100
70
必填，整数
流量占比
自动计算的流量百分比
70%
只读
步骤2：保存并发布
配置完成后，单击 确定 保存配置。权重路由策略会立即生效。
权重分配逻辑
权重总和不限制：
权重总和不要求等于100，网关会自动按比例计算：
服务A权重50,服务B权重30:
- 服务A流量占比 = 50 / (50+30) = 62.5%
- 服务B流量占比 = 30 / (50+30) = 37.5%
动态调整权重：
您可以随时编辑模型 API，调整权重配置，变更会在保存后立即生效(无需重启服务)。
典型场景示例
场景1：负载均衡 - 多实例部署
需求：自建了3个 vLLM 实例，希望均匀分配流量
配置：
模型服务
权重
流量占比
vllm-instance-1
33
33%
vllm-instance-2
33
33%
vllm-instance-3
34
34%
效果：每个实例接收约1/3的流量，实现负载均衡。
场景2：A/B 测试 - 新旧服务对比
需求：测试新部署的 qwen-max-2.5模型，与现有 qwen-max 对比效果
配置：
模型服务
权重
流量占比
说明
qwen-max(旧版本)
80
80%
主流量
qwen-max-2.5(新版本)
20
20%
测试流量
效果：20%流量路由到新版本，收集效果数据后决定是否全量切换。
场景3：灰度发布 - 逐步放量
需求：新模型服务需要灰度发布，从5%流量逐步放大到100%
阶段1：初始灰度(5%流量)
模型服务
权重
旧服务
95
新服务
5
阶段2：扩大灰度(30%流量)
模型服务
权重
旧服务
70
新服务
30
阶段3：全量切换(100%流量)
模型服务
权重
新服务
100
(删除旧服务或权重设为0)
场景4：成本优化 - 混合供应商
需求：大部分流量使用成本较低的国产模型，保留少量 Open AI 服务作为备份
配置：
模型服务
权重
流量占比
成本
qwen-max-aliyun
85
85%
低
gpt-4o-openai
15
15%
高
效果：85%流量使用成本更低的 qwen-max，15%流量使用 gpt-4o 保障质量。
注意事项
模型名称匹配规则：按模型名称路由时，需要确保客户端请求的model字段与模型服务配置的模型名称完全一致(大小写敏感)
权重调整生效时间：权重配置修改后，会在5-10秒内生效(无需重启服务)，但统计数据会有一定延迟
多模型服务权重相同：如果多个服务支持同一模型且权重相同(如都为1)，网关会随机选择其中一个
统计样本不足：当请求量较少时(<100次/小时)，选中率可能与配置权重有偏差，属于正常波动
常见问题
配置使用类
Q1：按模型名称路由和权重路由如何选择?
   根据您的需求选择：
按模型名称路由：适用于单个 API 需要支持多个不同模型的场景，每个模型对应不同的后端服务
权重路由：适用于同一模型有多个服务实例，需要负载均衡或 A/B 测试的场景
Q2：权重路由的权重总和必须等于100吗?
   不需要。网关会自动按比例计算流量分配。例如：
权重50：30：20，总和100 → 流量50%：30%：20%
权重5：3：2，总和10 → 流量50%：30%：20%
两种配置的效果完全相同。
Q3：如何动态调整权重配置?
1. 进入模型 API 详情页，单击 编辑
2. 在第二步路由配置页面，修改权重值
3. 单击 确定 保存
配置会在5-10秒内生效，无需重启服务。建议在低峰期调整，避免影响线上流量。
错误处理类
Q1 ：请求的模型名称无法匹配任何服务，会返回什么错误?
网关会返回404错误。错误信息中会列出当前 API 支持的所有模型名称，方便客户端排查问题。
Q2：权重路由的选中率与配置权重偏差较大怎么办?
请检查：
1. 统计样本是否充足：请求量<100次/小时时，选中率会有较大波动
2. 配置是否生效：修改权重后等待5-10分钟，确认配置已生效
3. 是否触发 Fallback：如果某个服务频繁触发 Fallback，实际选中率会低于配置权重
4. 统计周期：在控制台切换统计周期(1小时/24小时/7天)，查看长期趋势
如果长期(24小时以上)偏差>10%，请联系技术支持。
最佳实践类
Q1：如何设计高可用的权重路由策略?
建议采用以下架构：
1. 主服务高权重：将稳定性高的服务设为主服务，配置70-80%权重
2. 备用服务低权重：将备用服务配置20-30%权重，持续接收少量流量(保持服务热备)
3. 配置 Fallback：为主服务和备用服务都配置跨服务 Fallback，避免单点故障
4. 监控告警：配置路由统计监控，当某个服务的成功率<95%时触发告警
Q2：A/B 测试时如何评估新旧服务的效果?
建议的评估流程：
1. 配置权重：新服务10-20%权重，旧服务80-90%权重
2. 监控指标：在路由统计页面对比两个服务的成功率、平均延迟、错误率
3. 收集反馈：在调用日志中筛选新服务的请求，人工评估响应质量
4. 逐步放量：如果新服务效果好，逐步提高权重(20% → 50% → 100%)
5. 回滚机制：如果新服务出现问题，立即将权重调为0，切回旧服务
﻿
﻿

场景	匹配模型名	重写模型名	客户端请求 model	转发到后端的 model
透传原始 model	`gpt-4o`	(留空)	`gpt-4o`	`gpt-4o`
统一模型标识	`gpt-4-*`	`gpt-4-turbo-2024-04-09`	`gpt-4-turbo`	`gpt-4-turbo-2024-04-09`
自定义别名	`my-gpt4`	`gpt-4o`	`my-gpt4`	`gpt-4o`

路由策略	使用场景	决策依据	适用范围
按模型名称路由	多模型服务精确匹配	请求中的`model`字段与模型服务配置的模型名称匹配	单模型 API 需访问不同供应商的相同模型
权重路由	负载均衡、A/B 测试、灰度发布	按配置的权重比例随机分配流量	同一模型的多实例部署或多供应商混合部署

参数	说明	示例	是否必填
模型服务	从已创建的模型服务列表中选择	`gpt-4o-openai`	是
匹配模型名	客户端请求的 model 参数匹配规则，支持精确匹配和通配符匹配(`*`)	`gpt-4o` 或 `gpt-4-*`	是
重写模型名	转发到后端服务时，将请求中的 model 参数重写为指定值。留空则透传原始值	`gpt-4o` 或留空	否

通配符	说明	示例	匹配结果
`*`	匹配任意字符(0个或多个)	`gpt-4-*`	匹配`gpt-4-turbo`、`gpt-4o`、`gpt-4-0125-preview`
`gpt-*`	前缀匹配	`gpt-*`	匹配所有以`gpt-`开头的模型

模型服务	权重	流量占比
vllm-instance-1	33	33%
vllm-instance-2	33	33%
vllm-instance-3	34	34%

智能路由

本页目录：

操作场景

前置条件

路由策略概述

策略一：按模型名称路由

功能说明

配置步骤

步骤1：创建模型服务

步骤2：在模型 API 中配置模型名称路由

步骤3：保存并发布

配置示例

示例1：精确匹配多个模型

示例2：通配符匹配模型系列

示例3：模型名称重写

路由匹配规则

匹配优先级

通配符规则

模型名称重写逻辑

未匹配处理

策略二：权重路由

功能说明

配置步骤

步骤1：在模型 API 中配置权重路由

步骤2：保存并发布

权重分配逻辑

典型场景示例

场景1：负载均衡 - 多实例部署

场景2：A/B 测试 - 新旧服务对比

场景3：灰度发布 - 逐步放量

场景4：成本优化 - 混合供应商

注意事项

常见问题

配置使用类

错误处理类

最佳实践类