云原生智能网关通过 AI 网关快速对接 TokenHub

场景概述
本文将介绍如何通过 AI 网关快速接入 TokenHub 。腾讯云大模型服务平台 TokenHub 聚合了混元、DeepSeek、MiniMax、Kimi、智谱、百度等多家模型供应商的模型能力，通过统一的 API 接口对外提供服务。您通过 AI 网关将 TokenHub 接入后，可在网关层统一管理来自 TokenHub 的所有模型服务，获得统一的消费者鉴权、配额管控、监控日志和链路追踪能力，而无需在业务代码中逐个对接各家模型 API。
适用场景：需要多模型统一接入、成本分摊、流量管控的企业级 AI 应用。
前提条件
1. 已创建 AI 网关实例，实例状态为运行中。
2. 已开通腾讯云 TokenHub 服务，并在 TokenHub 控制台 快速接入 > API Key 管理 页面创建 API Key。
操作步骤
步骤一：创建 TokenHub 模型服务
1. 登录 AI 网关控制台，选择目标网关实例进入详情页。
2. 在左侧导航栏选择 流量管理 > 模型管理，选择 模型服务 页签，单击新建。
3. 在“新建模型服务”弹窗中，完成第一步“基本信息”配置：
在“模型供应商”下拉框中向下滚动（下拉框使用虚拟滚动），在 MaaS 供应商 分类下选择 TokenHub(多协议)。
参考下表配置表单参数：
参数
是否必填
说明
服务名称
是
2-60 个字符，支持中英文大小写、数字及分隔符（"-"、"_"），不能以数字和分隔符开头，不能以分隔符结尾。
服务类型
-
固定为“AI 模型服务”。AI 模型服务提供的大模型能力由第三方提供，请自行评估服务适用性与可靠性。
模型供应商
是
选择 TokenHub(多协议)。
模型协议
是
选择 OpenAI 兼容（适用于 DeepSeek、Qwen、混元等大多数模型）或 Anthropic 兼容（适用于 Claude 系列模型）。
服务地址
是
选择模型协议后自动填充 TokenHub 域名占位符，实际地址由“地域”决定，创建后展示为所选地域的实际地址。
地域
是
选择 TokenHub 服务所在区域（广州 / 新加坡），决定调用的基础域名。选择后下方展示实际请求地址（如 https://tokenhub.tencentmaas.com/v1/chat/completions），可一键复制。
密钥凭证类型
是
选择 TokenHub 供应商后出现，当前支持 API Key。选择后下方模型密钥列表仅展示该类型的密钥。
模型密钥
否（建议配置）
下拉选择已创建的密钥（支持搜索、刷新），或单击新建密钥快速创建。不配置时网关无法在转发请求时携带认证信息，调用将返回 401。
密钥使用策略
-
默认轮询（配置多个密钥时在密钥间均衡负载）。
密钥周期性轮换
否
勾选后，网关仅从创建时间在周期内的密钥中遴选调度。
描述
否
服务描述，最长 200 个字符。
4. 单击下一步，进入第二步“选择模型策略”：
模型选择方式：
指定模型（默认）：网关忽略客户端请求中的 model 参数，统一使用“默认模型”中指定的模型，适合成本控制和高可用场景。需在默认模型下拉框中选择具体模型——下拉列表自动从 TokenHub 拉取可用模型（如 MiniMax-M3、Hy3、GLM-5.3、DeepSeek-V4-Pro、Kimi K3 等）。
透传请求模型：网关直接使用客户端请求中的 model 参数转发给供应商，适合客户端灵活控制模型选择的场景。
模型 Fallback：开启后，当请求“默认模型”失败时，网关可根据规则自动切换到其他可用模型，保障服务高可用。
5. 单击确定，完成模型服务创建。
步骤二：查看服务详情与凭证管理
在模型服务列表中单击服务名称，进入服务详情页。详情页包含 基本信息 和 参数改写 两个页签：
基本信息页签：
基本信息：服务 ID、服务名称、服务类型、模型供应商（TokenHub）、模型协议、服务地址（如 https://tokenhub.tencentmaas.com）、地域（如 ap-guangzhou）、模型选择方式、默认模型、模型 Fallback、密钥使用策略、密钥周期性轮换、创建/修改时间、描述，支持单击编辑修改。
高级配置（折叠展开）：服务标签、超时配置（连接超时 10000ms、读取超时 60000ms、写入超时 60000ms、超时重试次数）、配额配置。
运行状态：展示当前运行状态（已上线），提供下线、配置健康检查操作按钮。
凭证管理：展示已绑定的密钥凭证列表（ID/名称、凭证、生成方式、操作），支持搜索与添加凭证。请确认包含 TokenHub API Key 的凭证状态为“已启用”。
参数改写页签：通过配置参数改写规则实现请求参数改写。如果 TokenHub 上的模型名称与业务代码中使用的不同，可通过参数改写规则将源模型名称映射为目标模型名称，无需修改业务代码。
步骤三：创建模型 API
模型服务创建完成后，需要创建模型 API 并绑定该服务，才能对外提供调用入口。
在 模型管理 页面，选择 模型 API 页签，单击新建。
第一步“基本信息” 配置如下：
参数
是否必填
说明
API 名称
是
2-60 个字符，命名规则同服务名称。
使用场景
-
选择 API 用途，支持：文本生成、文本向量化、图片生成、视频生成、语音合成、工具与元数据、文本排序。选择后系统按场景预置默认路由。
请求协议
-
选择 OpenAI 或 Anthropic。
路由
-
默认勾选 POST /v1/chat/completions（主路由，不可取消）；可选 POST /v1/responses（新一代有状态 Agent 对话）。
Base Path
否
默认 /，为此 API 设置统一的路由前缀。
描述
否
最长 200 个字符。
第二步“敏感信息路由”（可选）：开启后，请求将优先经过敏感信息检测，并根据检测结果分级路由至指定模型服务。如无需此能力直接进入第三步。
第三步“选择模型服务” 配置如下：
参数
是否必填
说明
服务类型
是
选择单模型服务（固定路由到一个后端服务）或多模型服务（按路由策略分发）。
标签过滤
否
开启后，将根据标签筛选符合条件的模型服务。
模型服务
是
下拉选择已创建的 TokenHub 模型服务。系统已根据第一步选择的协议和使用场景自动筛选匹配的模型服务。
全局跨服务 Fallback
否
开启后启用全局跨服务降级。
单击确定，完成模型 API 创建。
步骤四：配置认证授权
调用模型 API 前，需完成“消费者密钥 > 消费者 > API 授权”三步配置。
创建消费者密钥：在左侧导航栏选择 消费者管理 > 消费者密钥 页签，单击新建：
参数
是否必填
说明
密钥名称
是
2-60 个字符，命名规则同上。
密钥凭证类型
是
支持 API Key（默认）、JWT、OAuth 2.0、OIDC。
生成方式
是
支持自定义（默认，明文存储，适用于测试和非敏感场景）、密钥管理系统（KMS 凭据）、自动生成。
凭证内容
是
自定义方式下输入，8-60 个字符，支持英文大小写、数字及符号（"-"、"*"、"="），其中"-"、"*"不能作为首尾字符。
创建消费者：在 消费者管理 > 消费者 页签，单击新建：
参数
是否必填
说明
消费者名称
是
2-60 个字符。
所属消费者组
否
选择已有消费者组（如系统自动创建的 DefaultConsumerGroup）。
选择密钥
否
选择上一步创建的消费者密钥。
调度优先级
-
高优 / 中优（默认）/ 低优。模型 API 开启消费者优先级调度时生效，高优请求优先出队。
描述
否
最长 200 个字符。
为模型 API 授权：进入模型 API 详情页，选择 认证策略 页签：
认证方式：网关默认通过 API Key 进行认证。API 仅允许使用所配置认证方式的消费者进行访问，请确保消费者凭证类型与 API 认证方式一致。
单击新增授权，在授权范围（已授权消费者组 / 已授权消费者 / 已授权消费者标签）中选择目标。选择消费者组时，通过穿梭框勾选（如 DefaultConsumerGroup），该组内所有消费者自动获得访问权。
步骤五：获取接入地址并发起调用
1. 获取接入地址
在 AI 网关实例的 基础信息 > 网络配置 区域获取：
内网私有连接：VPC 内访问地址（如 10.0.1.2），适用于与网关同 VPC 的业务调用。
公网负载均衡：如需公网访问，单击添加配置公网 CLB，获取公网 VIP 或域名。
访问端口：HTTP 80 / HTTPS 443。
完整访问地址格式：协议://网关入口地址/路由请求路径，如 http://10.0.1.2/v1/chat/completions。模型 API 详情页的 路由管理 > 访问地址 区域也提供了该格式说明与请求示例（含复制按钮）。
2. 发起调用
curl -X POST "http://{网关CLB地址}/v1/chat/completions" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer {消费者密钥}" \\
  -d '{
    "model": "MiniMax-M3",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ],
    "max_tokens": 50
  }'
3. 参数说明：
{网关 CLB 地址}：网关入口地址（内网私有连接地址或公网负载均衡地址），在实例“基础信息”页获取。
{消费者密钥}：消费者密钥的凭证内容（如 sk-xxxx），在消费者密钥管理中获取。
model 参数使用 TokenHub 模型广场中的模型名称（如 MiniMax-M3、DeepSeek-V4-Pro、Hy3 等）。模型服务配置为“指定模型”时，网关忽略该参数统一转发到默认模型。
认证方式：在 HTTP 请求头中添加 Authorization: Bearer ${您的消费者密钥}。
支持流式调用：在请求体中添加 "stream": true。
﻿
﻿

参数	是否必填	说明
服务名称	是	2-60 个字符，支持中英文大小写、数字及分隔符（"-"、"_"），不能以数字和分隔符开头，不能以分隔符结尾。
服务类型	-	固定为“AI 模型服务”。AI 模型服务提供的大模型能力由第三方提供，请自行评估服务适用性与可靠性。
模型供应商	是	选择 TokenHub(多协议)。
模型协议	是	选择 OpenAI 兼容（适用于 DeepSeek、Qwen、混元等大多数模型）或 Anthropic 兼容（适用于 Claude 系列模型）。
服务地址	是	选择模型协议后自动填充 TokenHub 域名占位符，实际地址由“地域”决定，创建后展示为所选地域的实际地址。
地域	是	选择 TokenHub 服务所在区域（广州 / 新加坡），决定调用的基础域名。选择后下方展示实际请求地址（如 `https://tokenhub.tencentmaas.com/v1/chat/completions`），可一键复制。
密钥凭证类型	是	选择 TokenHub 供应商后出现，当前支持 API Key。选择后下方模型密钥列表仅展示该类型的密钥。
模型密钥	否（建议配置）	下拉选择已创建的密钥（支持搜索、刷新），或单击新建密钥快速创建。不配置时网关无法在转发请求时携带认证信息，调用将返回 401。
密钥使用策略	-	默认轮询（配置多个密钥时在密钥间均衡负载）。
密钥周期性轮换	否	勾选后，网关仅从创建时间在周期内的密钥中遴选调度。
描述	否	服务描述，最长 200 个字符。

通过 AI 网关快速对接 TokenHub

本页目录：

场景概述

前提条件

操作步骤

步骤一：创建 TokenHub 模型服务

步骤二：查看服务详情与凭证管理

步骤三：创建模型 API

步骤四：配置认证授权

步骤五：获取接入地址并发起调用