功能概述
模型 API 接入是 AI Agent 安全网关提供的核心业务接入能力，用于将大模型服务安全、便捷地接入网关，实现对大模型流量的集中管控和安全防护。
通过模型 API 接入，用户可以在网关层面统一管理大模型的访问入口、后端路由和安全策略，享受以下核心价值：
协议标准化：基于 OpenAI 协议标准封装，屏蔽不同模型厂商的接口差异，用户无需逐一对接各模型的 API 规范，即可快速完成接入。
多模型管理：支持多模型后端的负载均衡和智能路由，适用于企业在多模型场景下的高可用和灵活调度需求。
安全防护：在网关层统一配置流量控制、token 控制、内容安全、提示词安全和 IP 黑白名单等安全策略，防止敏感数据泄露，拦截恶意请求。
操作场景
本文介绍如何在 AI Agent 安全网关中完成模型 API 接入的全流程配置，将大模型后端服务安全地暴露给业务应用调用。
适用于以下场景：
需要将第三方或自建的大模型服务（自定义模型应用）通过网关进行安全代理和访问控制。
需要对多个大模型后端进行负载均衡，实现高可用和故障切换。
需要为大模型调用配置统一的凭据鉴权，保护后端模型服务的访问安全。
需要在应用维度统一实施流量控制、token 控制、内容安全、提示词安全和 IP 黑白名单等安全策略。
前提条件
已开通大模型安全网关服务。
如需接入自定义模型服务，需确保模型服务已部署且网络可达（支持公网或内网访问），并已获取模型服务的访问地址和鉴权凭据。
如需配置内容安全策略，需已开通 内容安全服务。
操作步骤
模型 API 接入的整体流程为：创建应用 → 新建模型 → 新建模型 API → 关联应用与模型 API。
步骤一：创建应用
应用是 AI Agent 安全网关的业务管理入口，用于统一管理 MCP 和大模型服务的访问。所有大模型侧的流量统一以应用作为访问入口。
1. 登录 AI Agent 安全网关 页面，在左侧导航栏中，单击应用。
2. 在应用页面，单击新建应用。
3. 在新建应用弹窗中，配置以下参数：
参数 | 说明 |
应用名称 | 输入应用的名称，建议使用有业务含义的命名，例如"智能客服应用" |
认证类型 | APIKey：应用密钥，用于标识和验证应用的身份，确保 API 调用的安全性 SecretKey：增强认证安全性，生成令牌或签名 OAuth2：实现授权码流、客户端凭据等标准 OAuth 2.0 流程，确保 API 访问的安全授权 关联模型 API 请选择 APIKey 或 SecretKey。每种认证类型最多支持创建 10 条凭据数据 |
应用描述 | 输入对该应用的描述信息，便于后续管理和识别 |
4. 单击创建应用，完成应用创建。
创建成功后，系统将自动为该应用生成一组默认凭据（APIKey 或 SecretKey），用于后续客户端调用网关时的身份验证。
说明：
为降低密钥泄漏风险，只在新建时提供默认凭据，后续不可再进行查询，请保存好默认凭据。
步骤二：新建模型
模型管理用于注册和管理后端大模型服务的连接信息，包括模型类型、后端地址、通信协议和负载方式等。
1. 在左侧导航栏中，单击模型 > 模型管理。
2. 在模型管理页面，单击新建模型。
3. 在新建模型页面，配置以下参数：
参数 | 说明 |
模型名称 | 自定义模型名称，用于标识模型用途，例如"混元大模型"。支持中英文、数字、下划线，长度不超过 64 个字符 |
模型类型 | 选择后端模型服务的类型，支持以下模型类型： TI-ONE 应用：接入已在 TI-ONE 平台部署的模型推理服务 自定义模型应用：接入第三方或自部署的模型服务，需手动填写后端路径 |
选择服务 | 当模型类型选择 TI-ONE 应用 时，选择对应的服务名称、版本以及调用类型 |
后端协议 | 选择与后端模型服务通信的协议，可选 HTTP 或 HTTPS |
协议检查 | 当后端协议选择 HTTPS 时，选择是否启用协议检查。启用后，网关将校验后端服务的 SSL/TLS 证书有效性 |
协议版本 | 选择协议版本，支持1.1和2.0。如模型服务支持 gRPC，请选择 2.0 |
后端服务 | 后端服务节点地址，添加多个节点 原始域名/IP：后端服务节点的实际域名或 IP 地址，用于指定网关转发请求的目标地址。{domain}:{port}形式 转发权重：用于设定当前后端节点的流量分配权重，取值范围 1-100，默认值为 10。权重越高，分配到该节点的请求比例越大 |
后端路径 | 输入后端模型服务的 API 路径，例如 /v1/chat/completions |
凭据选择 |
4. 单击确定，完成模型创建。
注意：
修改模型的后端路径后，关联该模型的所有模型 API 的请求转发目标将同步变更，请确认不影响线上业务后再执行修改操作。
步骤三：新建模型 API
模型 API 用于定义接入路由，将前端请求路径映射到后端模型服务，是连接应用和后端模型的桥梁。
1. 在左侧导航栏中，单击模型 > 模型 API。
2. 在模型 API 页面，单击新建模型 API。
3. 在新建模型 API 页面，配置以下参数：
参数名称 | 说明 |
基本信息 | |
API 名称 | 自定义模型 API 名称，用于标识当前 API 的业务用途，例如"对话补全接口"。由64以内的中文、大小写字母、数字、_、-、()、（）组成，实例下唯一 |
API 描述 | 对模型 API 的补充说明信息。长度1024以内 |
前端配置 | |
请求路径 | 前缀匹配：API 请求的路径以"路径"的配置为前缀 绝对匹配：API 请求的路径要与"路径"的配置一致，匹配优先级最高 正则匹配：API 请求的路径正则匹配"路径"的配置，支持路径参数，参数必须以{}包裹，作为独立部分包含在路径中（示例：/{param}/），匹配优先级最低 输入访问路径，以"/"进行分隔，如/ebus/amp/rio/web |
后端配置 | |
模型地址 | 后端模型：选择已创建的模型。如果尚未创建模型，请先前往 模型管理 页面创建 匹配名称：关联模型后自动展示的后端模型访问地址 模型权重：用于设定当前模型在流量分发中的权重比例，权重越高分配到的请求越多 可关联多个模型。关联多个模型时，请求将按照模型管理中配置的负载方式进行分发 |
超时时间 | 后端请求超时时间，单位为秒，取值范围 1-600，默认 60 秒。建议根据模型推理耗时设置 |
4. 单击下一步，完成高级配置。
参数 | 说明 |
流量控制 | 开启后可自定义某个时间内最大请求次数、时间窗口长度、转发超时时间等 |
token 控制 | 开启后可自定义时间窗口内累计总量消耗或单次请求消耗上限控制 |
内容安全 | 开启后可对请求和响应内容进行安全检测，支持内置原生检测模型或腾讯云上内容安全产品 |
提示词安全 | 开启后可对请求内容进行提示词安全检测 |
IP 黑名单 | 开启后可限定指定的 IP 无法访问该模型 API，其他 IP 都可访问 |
IP 白名单 | 开启后只允许指定的 IP 访问该模型 API，其他 IP 都无法访问 |
5. 单击保存，完成模型 API 创建。
步骤四：关联应用与模型 API
创建模型 API 后，需要将其关联到应用中，并配置安全策略，使客户端能够通过应用入口访问大模型服务。
1. 在左侧导航栏中，单击应用。
2. 在应用页面，单击目标应用名称。
3. 在应用详情页面，单击左下角的关联模型 API。
4. 在关联模型 API 弹窗中，配置以下参数：
参数 | 说明 |
模型 API | 下拉选择已创建的模型 API |
流量控制 | 单击开启后，可配置 QPS 上限，防止后端模型服务被过量请求压垮。建议设置为实际业务峰值的 1.2-1.5 倍 |
token 控制 | 单击开启后，可配置单次请求 token 上限和单日 token 上限，控制模型调用成本 |
5. 单击确定，完成关联配置。
6. 关联成功后，业务应用即可通过应用的访问入口和凭据，经由网关安全地调用后端大模型服务。
结果验证
完成上述步骤后，您可以通过以下方式验证模型 API 接入是否配置成功：
1. 在应用页面，单击目标应用名称进入详情页，在关联模型 API 区域确认目标模型 API 已显示在列表中。
2. 在模型 API 列表页中，确认后端模型数和关联应用列数据与预期一致。
3. 使用应用的凭据，通过网关地址发起测试请求，确认能正常调用后端模型并获得响应。
API 示例调用如下（以 curl 为例）：
$ curl -X POST https://<网关域名>/v1/chat/completions \\-H "Content-Type: application/json" \\-H "Authorization: Bearer <模型 API Key>" \\-d '{"model": "<模型名称>","messages": [{"role": "user", "content": "您好"}]}'
参数说明：
参数 | 说明 |
网关域名 | AI Agent 安全网关分配的访问域名 |
/v1/chat/completions | 模型 API 中配置的前端请求路径，请替换为实际值 |
模型 API Key | |
模型名称 | 后端模型的名称，根据实际使用的模型填写 |
若返回模型正常响应结果，表示模型 API 接入配置成功，流量已通过 AI Agent 安全网关进行代理和防护。
