操作场景
您需要将大模型服务添加到 AI 网关中，以便网关能代理请求至相应的模型供应商，实现统一接入、路由、降级与密钥管理。AI 网关支持添加混元、Google Gemini、DeepSeek、千问、OpenAI 等供应商的模型服务。本文介绍如何为 AI 网关添加、编辑和删除模型服务。此外，AI 网关为模型服务提供生命周期管理能力：支持三态管理，可手动下线控制流量接入，并按供应商协议分类进行健康检查，异常时自动摘除流量、恢复后自动回归，状态变更记录到操作记录与事件中心。
操作步骤
添加模型服务
1. 登录 微服务平台控制台，在左侧导航栏单击 AI 网关 > 实例列表。
2. 在实例列表页面，单击需要配置的网关实例的“ID”，进入该网关实例的基本信息页面。
3. 在左侧导航栏单击模型管理，然后单击模型服务页签，在服务列表中单击新建。
4. 在“新建模型服务”窗口中，完成第一步“基本信息”的配置。
参数 | 是否必填 | 说明 |
服务名称 | 是 | 输入服务名称。最长60个字符，支持中英文大小写、数字及分隔符（“-”、“_”)，不能以数字和分隔符开头，不能以分隔符结尾。 |
服务类型 | 是 | 固定为“AI 模型服务”。 |
模型供应商 | 是 | 选择模型供应商： 标准供应商：Hunyuan、OpenAI、Anthropic、Google-Gemini、DeepSeek、Qwen、月之暗面、智谱、百度千帆、腾讯云 TI-ONE MaaS 供应商：TokenHub、AWS Bedrock、Azure OpenAI、火山方舟、Google Vertex AI 自定义供应商 |
模型协议 | 是 | 根据模型供应商支持的模型协议，支持 OpenAI 兼容和 Anthropic 兼容。 |
服务地址 | 是 | 确认模型服务的服务地址。 若选择自定义供应商，此处可选手动填写或关联服务来源。 手动填写：请自行评估服务地址的有效性，确保服务地址符合相关法规和协议要求。提供路径拼接功能，在配置服务地址时单独指定路径前缀，系统将自动拼接完整请求地址。支持两种路径拼接模式： 自动拼接（默认）：将模型 API 请求路径拼接到 Base URL 之后，适用于大多数标准 OpenAI 兼容协议服务。 使用固定路径：请求路径固定为 Base URL，不拼接，适用于 Bedrock、Azure 等固定 endpoint 场景。 关联服务来源：支持选择已创建的容器服务或北极星服务，并配置具体服务来源、命名空间、容器服务、请求协议。 |
模型密钥 | 否 | 选择已配置的该供应商 API 密钥，或单击“新建密钥”跳转至密钥管理页面进行添加。网关将使用此密钥调用对应模型 API。 |
密钥使用策略 | 否 | 当配置了多个密钥时，定义密钥的使用方式。默认为轮询，可在多个密钥间均衡负载。 |
密钥周期性轮换 | 否 | 开启后，网关仅从创建时间在周期内的密钥中遴选调度 |
描述 | 否 | 该服务的描述信息，便于后续管理。 |
注意：
AI 模型服务提供的大模型能力由第三方提供，AI 网关不直接提供这些能力。请自行评估服务适用性与可靠性，确保使用行为符合相关法规和协议要求，否则请自行承担因违反规定产生的后果。
5. 配置高级配置(可选)：
在高级配置区域，配置服务的网络超时、SNI、配额和标签等参数。
超时配置说明：
参数 | 默认值 | 范围 | 说明 |
连接超时时间 | 10000 ms | 1 ~ 3600000 ms | 建立与后端服务 TCP 连接的超时时间。建议根据模型推理时间设置，快速模型可适当降低超时时间 |
读取超时时间 | 60000 ms | 1 ~ 3600000 ms | 从后端服务读取响应数据的超时时间 |
写入超时时间 | 60000 ms | 1 ~ 3600000 ms | 向后端服务发送请求数据的超时时间 |
超时配置建议值：
模型类型 | 连接超时 | 读取超时 | 写入超时 | 说明 |
快速推理模型（< 5秒） | 5000 ms | 30000 ms | 30000 ms | 如 qwen-turbo、gpt-4o-mini |
标准推理模型（5 ~ 30秒） | 10000 ms | 60000 ms | 60000 ms | 默认值，适用于大多数模型 |
慢速推理模型（> 30秒） | 15000 ms | 120000 ms | 120000 ms | 如深度推理模型、长文本生成 |
流式响应 | 10000 ms | 不限制 | 30000 ms | 流式模式下读取超时不限制 |
SNI 配置说明：
参数 | 是否必填 | 说明 |
SNI | 否 | TLS 握手时发送的 Server Name Indication 值，留空时使用服务地址中的域名作为 SNI |
配额配置说明：
参数 | 是否必填 | 说明 | 示例 |
RPM（每分钟请求数） | 否 | 供应商规定的模型每分钟允许的最大请求次数。不填写则无法在模型 API 中使用配额感知 Fallback | 1000 |
TPM（每分钟 Token 数） | 否 | 供应商规定的模型每分钟允许的最大 Token 消耗量。不填写则无法在模型 API 中使用配额感知 Fallback | 100000 |
并发请求数 | 否 | 供应商规定的模型同一时刻允许的最大并行请求数。不填写则无法在模型 API 中使用配额感知 Fallback | 100 |
说明：
配额配置用于配额感知 Fallback 场景。当消费者的剩余配额低于阈值时，网关自动将请求降级到备用服务。如果模型服务未配置 RPM/TPM，则无法参与配额感知 Fallback。
服务标签说明:
参数 | 是否必填 | 说明 | 示例 |
标签键 | 否 | 分类标识，建议使用有业务含义的键名 | region、env、provider |
标签值 | 否 | 对应键的值 | singapore、production、openai |
说明：
服务标签用于在模型 API 中通过“基于标签路由”策略自动筛选服务。新增模型服务时只需配置标签，即可自动被匹配的 API 发现和使用，无需修改 API 配置。
6. 完成基本信息后，单击下一步，进入选择模型策略步骤。
模型选择方式：此配置决定网关如何处理客户端请求中的模型（model）参数。
网关将忽略客户端请求中的 model 参数，统一使用您在下方“默认模型”中指定的模型。此模式适合成本控制和高可用场景，便于统一路由和降级。
默认模型：当“模型选择方式”为“指定模型”时，必须在此处选择一个具体的模型名称
模型 Fallback：开启后，当请求“默认模型”失败时，网关可根据规则自动切换（Fallback）到其他可用模型，保障服务高可用。
备选规则：开启 Fallback 后，需在此选择或配置当主模型不可用时的备选模型列表及切换规则。
网关将直接使用客户端请求中的 model 参数，并将其转发给供应商。此模式适合需要客户端灵活控制模型选择的场景（如评估请求延迟、统计 Token 用量等），但使用透传请求时网关无法明确识别用户实际请求的模型名称，请确保客户端传递正确的模型名称。
若用户请求的模型名称与后端供应商的模型名称一致或不需要对模型名称做任何转换处理，可直接透传用户请求中的 model name 至后端服务。
若需将用户请求中的 model name 替换为供应商中定义的模型名称，可配置模型名称映射信息。支持精确匹配和前缀匹配(*)，支持添加多条映射规则。
请求模型名称（客户端请求的模型名称）
目标模型名称（需要重写的模型名称，即后端供应商实际使用的模型名称）
高级配置（可选）
模型参数校验：开启后，网关将校验客户端请求中的 model 参数是否在允许的列表内。
允许的模型列表：定义客户端允许请求的模型名称白名单。
校验失败处理：定义当模型校验失败时的处理策略，支持“返回404”或“使用默认模型降级”。
7. 配置完成后，单击确定即可创建模型服务。
8. 添加后，服务列表中会出现新增的服务，单击服务 ID/名称，查看详细的服务信息。
编辑服务
在模型服务列表页面，找到目标服务，单击其操作列下的编辑，即可修改服务配置信息，修改后单击确定保存。
删除服务
在模型服务列表页面，找到目标服务，单击其操作列下的删除，系统将进行删除前的依赖关系校验。
1. 系统会弹窗提示您确认删除，并自动检查该服务是否存在被其他资源（如“模型 API”）绑定的情况。
2. 确认结果：
若无依赖：弹窗将直接显示服务 ID 和名称，单击确定即可删除。
若存在依赖：弹窗会在服务信息下方显示“资源删除依赖关系检查结果”，并提示“存在未解除的依赖关系”，同时列出具体的依赖项。
3. 若存在依赖，您需要先行解除所有列出的依赖关系。解除依赖后，可单击弹窗内的重新检查操作，系统将再次进行校验。当校验通过，依赖提示消失后，单击确定即可最终删除该服务。若需放弃删除，可单击取消。
模型服务生命周期管理
生命周期状态说明
模型服务支持以下三种状态，模型服务列表新增状态列与上线/下线操作：
状态 | 说明 | 是否接收流量 |
未上线 | 手动下线 | 否 |
运行中 | 正常运行，健康检查通过 | 是 |
异常 | 健康检查失败，等待恢复或人工介入 | 否 |
状态转换触发条件：
转换 | 触发方式 | 说明 |
未上线 → 运行中 | 手动上线 | 用户在控制台单击“上线” |
运行中 → 未上线 | 手动下线 | 用户在控制台单击“下线”，停止接收流量 |
运行中 → 异常 | 健康检查失败 | 连续 N 次探测失败（N 可配置，默认 3 次） |
异常 → 运行中 | 健康检查恢复 | 探测成功，自动恢复（无需手动） |
异常 → 运行中 | 手动上线 | 用户确认异常已解除，手动触发 |
上线/下线模型服务
1. 在左侧导航栏单击模型管理，然后单击模型服务页签。
2. 在模型服务列表中，查看各服务的状态列。
3. 对目标服务执行操作：
上线：单击操作列的上线，服务进入"运行中"状态，开始接收流量（模型服务默认上线状态）。
下线：单击操作列的下线，在确认弹窗中单击确认下线。下线后该服务停止接收新的模型 API 请求，关联的模型 API 不再路由到该服务，服务配置不丢失，可重新上线。
配置健康检查
1. 在模型服务详情页，找到健康检查配置区域，单击编辑。
2. 开启健康检查开关，配置通用参数：
字段 | 必填 | 默认值 | 说明 |
检查间隔 | 是 | 30 秒 | 探测周期 |
超时时间 | 是 | 5 秒 | 单次探测超时 |
失败阈值 | 是 | 3 次 | 连续失败 N 次后标记异常 |
恢复阈值 | 是 | 1 次 | 连续成功 N 次后标记恢复 |
探测路径 | 是 | /v1/models | 可根据模型协议进行配置 |
