云原生智能网关 模型名称路由

一、功能说明

·同一个 API 需要支持多个不同的模型(如gpt-4o、gpt-4o-mini、claude-3-5-sonnet)

·不同模型由不同的供应商或服务实例提供

·需要精确控制每个模型的路由目标

·需要使用通配符匹配一组模型(如gpt-4-*匹配所有 gpt-4系列模型)

二、步骤1：创建模型服务

在配置路由策略前，需要先创建模型服务：

1. 登录 微服务平台控制台，在左侧导航栏单击 AI 网关 > 实例列表；

2. 在实例列表页面，单击需要配置的网关实例的“ID”，进入该网关实例的基本信息页面；

3. 在左侧导航栏单击模型管理，然后单击模型服务页签；

4. 在服务列表中单击新建，配置供应商、访问凭证等信息；

5. 保存模型服务。

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

1. 在模型管理 > 模型 API 页签单击新建；

2. 完成基本信息配置后，在第二步：选择模型服务 页面，配置服务类型和路由策略；

3. 选择服务类型为多模型服务；

4. 选择路由策略为模型名称路由；

5. 在模型服务表格中添加服务并配置路由规则。

配置参数说明：

四、步骤3：保存并发布

配置完成后，单击 确定 保存配置。路由规则会立即生效。

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

·场景：单个 API 需要支持3个不同的模型，分别由不同的服务提供

·配置：

·测试请求：

# 请求1:路由到 gpt-4o-openaicurl -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-anthropiccurl -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-*系列的模型都路由到同一个服务

·配置：

·测试请求：

# 请求1:匹配通配符规则,路由到 gpt-4-family-openai,透传model=gpt-4ocurl -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-turbocurl -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-openaicurl -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：模型名称重写

·场景：客户端使用自定义模型名称，但后端服务只识别标准模型名

·配置：

·测试请求：

# 客户端请求model=my-custom-gpt4,网关转发时重写为model=gpt-4ocurl -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": "你好"}]}

八、匹配优先级

启用 model_name_route 路由策略后，网关从配置列表的第一条规则开始，按从上到下的顺序匹配请求中的 model 参数，首个命中的规则生效。

九、1. 按配置顺序匹配

精确匹配和通配符匹配没有内置的优先级差异。只要一条规则匹配成功，网关便停止继续匹配后续规则。

因此，建议将范围更小、更精确的规则配置在范围更大的通配符规则之前。

例如，按以下顺序配置：

请求 model=gpt-4o 时，命中第一条规则并路由到服务 A；请求 model=gpt-4-turbo 时，命中第二条规则并路由到服务 B。

如果将 gpt-4* 配置在 gpt-4o 之前，则请求 model=gpt-4o 会优先命中 gpt-4*，并路由到服务 B。

注意：gpt-4-* 中的连字符是普通字符，该规则可以匹配 gpt-4-turbo，但不能匹配 gpt-4o。

十、2. 多个通配符规则同时匹配

当多个通配符规则都能匹配同一个模型名称时，选择配置列表中顺序最靠前的规则。

例如，gpt-* 和 gpt-4* 都能匹配 gpt-4o。哪条规则排在前面，就使用哪条规则对应的模型服务。

十一、当请求携带有效的字符串类型 model 参数，但无法匹配任何已配置规则时，网关返回 HTTP 404。

响应格式示例：

{ "error": { "message": "model 'unknown-model' is not supported by any configured model_name_route rule" }}

缺少 model、model 为空字符串或不是字符串时，属于请求参数异常，不属于“模型名称未匹配”场景。

十二、通配符规则

支持的通配符：

十三、模型名称重写逻辑

重写时机：

·网关在转发请求到后端模型服务之前，会将请求 body 中的model字段替换为"重写模型名"配置的值

·如果"重写模型名"留空，则透传客户端请求中的原始 model 值

典型场景：

未匹配处理

如果请求的模型名称无法匹配任何路由规则，网关会返回：

{ "error": { "code": "model_not_found", "message": "模型 'gpt-5' 不存在,请检查模型名称是否正确。可用模型: gpt-4o, gpt-4-*, claude-3-5-sonnet", "type": "invalid_request_error" }}

错误信息中会列出当前 API 支持的所有匹配规则，方便客户端排查问题。