创建ModelAPI
更新时间：2026-09-21
概述
本文介绍如何创建 Model API，包括匹配规则、后端策略、Fallback 与消费者认证的配置说明。
前提条件
- 已创建 Model 服务，详见创建 Model 服务。
- 已在后端管理中添加好 AI 大模型后端。
操作步骤
- 登录 API 网关专享版控制台，在左侧导航选择目标实例。
- 进入 API 管理 > Model API，单击 创建 Model API。
- 选择服务：选择已创建的 Model 服务。
- 配置匹配规则、后端策略与消费者认证（见下文），提交创建。
- 在 API 列表的 匹配规则 中 发布 对应规则，详见发布与管理 Model API。
匹配规则
| 配置项 | 说明 |
|---|---|
| 请求方法 | 自行配置请求方法。 |
| 请求路径 | 自行配置请求路径。 |
| 匹配方式 | 精确匹配 / 前缀匹配 / 正则匹配。 |
| Header 匹配 | （可选）按请求头的键值与匹配方式追加匹配条件。 |
| Query 匹配 | （可选）按请求参数的键值与匹配方式追加匹配条件。 |
| 优先级 | （可选）范围 0-9999，0 为最高优先级，默认为 0。当优先级相同时，按默认路由规则匹配： 1. 匹配方式优先级：精确匹配 > 前缀匹配 > 正则匹配； 2. 路径段数匹配多的优先级高，例如 /a/b 优先级大于 /a；3. Header 匹配数量多的优先级高，Header 优先级大于 Query； 4. Query 匹配数量多的优先级高。 |
后端策略
后端策略（modelBackendStrategy）决定了 API 下自动生成的匹配规则条数与分流方式。
| 策略 | 说明 | 生成的匹配规则 |
|---|---|---|
| 单后端（SINGLE） | 请求全部转发到指定的一个 AI 模型后端。 | 1 条默认匹配规则，匹配条件为 *。 |
| 多后端·按模型名称（MODEL_NAME） | 为每个后端配置模型名称匹配规则，根据请求体中的 model 字段路由到对应后端，例如 deepseek-* 匹配的请求转发到 DeepSeek 后端。未匹配任何规则的模型请求将被拒绝，适用于需要限定可访问模型范围、多模型统一接入的场景。 |
按配置的模型名称规则数量，自动生成对应条数的匹配规则。 |
| 多后端·按比例（WEIGHT） | 为每个后端设置流量权重比例，网关按权重将请求分发到不同后端，适用于灰度发布、A/B 测试场景。 | 1 条默认匹配规则，匹配条件为 *，规则内包含多个带权重的后端。 |
说明：一个请求同时命中多条匹配规则时，命中更精确的规则，规则示例详见Model API 概述。
Fallback
开启后，主后端异常时网关按顺序将请求切换到兜底后端，客户端无感知。
| 配置项 | 说明 |
|---|---|
| Fallback 开关 | 默认关闭，开启后可选择兜底后端。 |
| 兜底后端 | 按顺序依次尝试的备用后端列表，作用于整个 API，不支持为单条匹配规则单独配置。 |
| 触发范围 | 可选仅后端服务错误，或包含限流、熔断等网关错误。 |
| 首包超时阈值 | 流式响应场景下，超过该时间未返回首包即触发兜底。 |
消费者认证
| 配置项 | 说明 |
|---|---|
| 消费者认证 | （可选）默认关闭。开启后该 API 的流量默认全部拒绝，仅放行已授权的消费者。 |
| 认证方式 | （开启认证时必选）API_KEY / AK_SK，默认 API_KEY。 |
| 绑定消费者 | （开启认证时必选）选择需要放行的消费者。 |
详见授权管理。
场景配置示例
说明：下文列举几个典型业务场景的配置思路，供您参考。实际配置时请结合业务需要调整模型名称、权重等具体值。
场景一：限定可访问的模型范围（按模型名称路由）
适用场景：希望仅暴露指定的几个模型给业务方，未在白名单中的模型请求被网关直接拒绝，避免业务方误调用未授权或高成本模型。
配置思路：后端策略选择 多后端·按模型名称，为每个允许的模型配置匹配规则（如 deepseek-chat、deepseek-reasoner 分别指向对应后端）。
调用效果：客户端请求体中 model 为 deepseek-chat 时正常转发；为其他值（如 gpt-4）时被网关拒绝。
Bash
1# 允许的模型，请求正常返回
2curl https://{网关访问地址}/v1/chat/completions \
3 -H "Content-Type: application/json" \
4 -H "Authorization: Bearer {消费者API-KEY}" \
5 -d '{
6 "model": "deepseek-chat",
7 "messages": [{"role": "user", "content": "你好"}]
8 }'
9
10# 未配置的模型，请求被网关拒绝，不会转发到上游
11curl https://{网关访问地址}/v1/chat/completions \
12 -H "Content-Type: application/json" \
13 -H "Authorization: Bearer {消费者API-KEY}" \
14 -d '{
15 "model": "gpt-4",
16 "messages": [{"role": "user", "content": "你好"}]
17 }'场景二：按比例灰度发布新模型（按比例分流）
适用场景：新接入了一个模型后端，希望先承担少量流量进行稳定性验证，确认无问题后再逐步增大权重直至全量切换。
配置思路：后端策略选择 多后端·按比例，旧模型后端权重 90、新模型后端权重 10，同时开启 Fallback、兜底后端指向旧模型。
调用效果：网关将约 90% 的请求分发到旧模型、10% 分发到新模型，客户端无需感知后端的版本切分。验证稳定后，编辑 API 逐步将新模型权重提升至全量。
后续操作
评价此篇文章