tencent cloud

云原生智能网关

Documentation云原生智能网关AI 网关操作指南智能路由模型名称路由

模型名称路由

Download
Focus Mode
Font Size
Last updated: 2026-09-22 18:43:15

功能说明

按模型名称路由会根据客户端请求中的model字段自动匹配对应的模型服务。这种路由策略适用于以下场景：
同一个 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. 在模型服务表格中添加服务并配置路由规则。
配置参数说明：
参数
说明
示例
是否必填
模型服务
从已创建的模型服务列表中选择
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": "你好"}]}

路由匹配规则

匹配优先级

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

1. 按配置顺序匹配

精确匹配和通配符匹配没有内置的优先级差异。只要一条规则匹配成功，网关便停止继续匹配后续规则。
因此，建议将范围更小、更精确的规则配置在范围更大的通配符规则之前。
例如，按以下顺序配置：
顺序
模型名称规则
匹配类型
目标模型服务
1
gpt-4o
精确匹配
服务 A
2
gpt-4*
通配符匹配
服务 B
请求 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。哪条规则排在前面，就使用哪条规则对应的模型服务。

3. 未匹配任何规则

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

响应格式示例：
{
  "error": {
    "message": "model 'unknown-model' is not supported by any configured model_name_route rule"
  }
}
缺少 model、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 支持的所有匹配规则，方便客户端排查问题。
Previous Topic: 概述Next Topic: 权重路由

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation