Docs
文档目录

模型与 AI 网关总览

Agentbase v2.10.0 为企业级 AI 应用提供双层模型接入与治理体系:模型(LLM Gateway) 与 AI 网关(AI Gateway)。两套体系在项目内并存、职责边界清晰且互不接管——模型(LLM Gateway) 聚焦项目级模型供应商连接注册、预置模型目录同步、模型健康探测与平台内部 AI 引擎(知识库向量化、重排、记忆抽取、智能体工作台、可观测性评估)的底层算力供给;AI 网关(AI Gateway) 则面向多团队、多智能体生产环境提供带网关实例隔离的统一数据面入口,支持逻辑模型(Logical Model)动态路由、主备容灾切换、语义缓存(Semantic Cache)、安全护栏(Guardrail & OPA 策略)、多协议代理(OpenAI / Anthropic / MCP / A2A / HTTP Agent)以及细粒度 Token/QPS 预算治理。


功能概述

在企业级 AI 中台落地过程中,研发与架构团队通常面临两类截然不同的模型管理诉求:

  1. 项目底座算力连接(由「模型 / LLM Gateway」承载):

    • 项目内的 知识库(Knowledge Base) 需要稳定的 Embedding 模型(如 text-embedding-v3)进行分块向量化、需要 Rerank 模型(如 qwen3.7-text-rerank)执行多路召回精排、需要多模态视觉模型(如 qwen-vl-max)完成扫描件与架构图解读,并需要大语言模型(如 qwen-plus)驱动 GraphRAG 图谱抽取、RAPTOR 递归聚类、Wiki 编译及合成问答。

    • 记忆中心(Memory) 需要 Chat 与 Embedding 模型完成长期事实提取、画像归纳、上下文梦境重整(Dreaming)与技能蒸馏(Skill Distillation)。

    • 智能体工作台(Agent Runtime) 与 可观测性评估(Observability Evaluations) 同样直接读取项目在「模型」页注册的 Provider 与模型目录。

    • 同时,业务服务可通过签发项目级受限密钥(abk_...)调用 /v1/ai/chat/completions、/v1/ai/embeddings、/v1/ai/rerank、/v1/ai/messages 等标准接口。

  2. 多网关实例生产流量治理(由「AI 网关 / AI Gateway」承载):

    • 当企业将大模型与智能体能力暴露给外部业务线、合作伙伴或多租户终端时,需要在物理模型之上构建一层逻辑抽象(例如将主模型 qwen-plus 与备选模型 qwen-turbo 封装为统一的逻辑模型 lm-enterprise-chat)。

    • 需要对入站 Prompt 与出站生成结果执行统一的内容安全护栏(Guardrail Profile,如 PII 个人隐私脱敏、Prompt 注入防御、敏感词阻断)及 OPA 策略预检。

    • 需要开启基于向量相似度的语义缓存(Semantic Cache),对高频重复咨询直接命中缓存返回,大幅降低首包延迟(TTFT)与 Token 成本。

    • 需要按网关实例(如 /ai-gateway/g/gw_7194685489feb1e169548619/v1/...)统一纳管 MCP 工具审批、A2A 智能体调用、主体凭证(Principals & Credentials)及多周期硬性预算(Budgets)。


核心概念与架构

双层模型接入与治理架构图

以下架构图展示了 模型(LLM Gateway) 与 AI 网关(AI Gateway) 在 Agentbase 平台内部及外部业务调用链路中的协作关系:

模型与 AI 网关总览:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心概念与能力对比表

维度模型(LLM Gateway)统一 AI 网关(AI Gateway)
控制台导航入口项目左侧导航栏 模型(Models)项目左侧导航栏 AI 网关(AI Gateway)
核心定位项目级基础模型供应商连接池、模型目录与平台内部 AI 算力底座多网关实例隔离的企业级 AI 流量网关、逻辑路由、护栏、缓存与工具治理面
默认启用状态项目创建后默认启用(受项目设置中 AI Gateway 服务开关控制客户端访问)默认按需开启网关实例;与 LLM Gateway 并存且互不覆盖、互不接管
数据面请求路径/v1/ai/chat/completions、/v1/ai/embeddings、/v1/ai/rerank、/v1/ai/messages、/v1/ai/models强制携带网关实例 ID:/ai-gateway/g/{gatewayId}/v1/chat/completions、/responses、/embeddings、/rerank、/messages 及 /mcp、/a2a
模型寻址方式直接使用物理模型标识(如 qwen-plus、text-embedding-v3)或连接 ID + 模型名支持逻辑模型(Logical Model)(如 lm-enterprise-chat),底层按权重与优先级路由至多个物理部署目标(Deployments)
平台内生服务依赖直接依赖:知识库、记忆、智能体工作台、可观测评估均从此处读取 Provider 配置无耦合:启用或修改 AI Gateway 实例不会改变知识库或记忆模块的既有模型调用行为
安全与缓存策略基础网关密钥(abk_...)白名单、月度 Token 上限与每分钟请求速率限制(RPM)完整的 安全护栏(Guardrail Profile)、语义缓存(Semantic Cache)、OPA 策略预演、工具审批状态机与多粒度预算控制
典型标杆配置连接 dashscope-prod(接入 qwen-plus、qwen-turbo、text-embedding-v3、qwen3.7-text-rerank、qwen-vl-max),网关密钥 gw-key-support-bot网关实例 prod-enterprise-ai-gateway(gw_7194685489feb1e169548619)、逻辑模型 lm-enterprise-chat、护栏 gp-enterprise-safety、缓存 cp-semantic-cache

角色、入口与关联关系

角色与权限矩阵

在组织(如 Agentbase 企业智能中台,ID:69c6d1aa00062e6bb60)与项目(如 企业智能客服与知识中台,ID:enterprise-ai-hub-210)中,不同角色对两套系统的操作权限如下:

角色名称模型(LLM Gateway)权限AI 网关(AI Gateway)权限
Owner / Admin(组织所有者 / 管理员)完整权限:创建/编辑/删除 Provider、执行健康探测、签发与吊销 Gateway Key、查看全量 Token 账单完整权限:创建网关实例、配置逻辑模型与部署目标、发布安全护栏与缓存策略、审批高危 MCP 工具、封存运行时快照
Developer(研发人员)可查看已注册 Provider 与模型参数、执行健康探测、在知识库/记忆/智能体工作台中绑定模型、查看调用统计可查看网关实例、调试逻辑模型路由、执行策略 Dry-Run 预演、查看流量与质量指标
网关密钥调用方(abk_... 客户端)仅允许调用被授权白名单内的模型执行端点(Chat / Embedding / Rerank),严禁访问管理面 API仅允许调用所绑定 gatewayId 下的数据面推理与工具端点,受主体预算与护栏策略实时约束

控制台入口与上下游关联

  1. 控制台入口路径:

    • 模型(LLM Gateway):登录控制台 -> 选择项目 企业智能客服与知识中台 (enterprise-ai-hub-210) -> 左侧导航栏点击 模型(路由:/console/project-default-enterprise-ai-hub-210/llm-gateway)。

    • AI 网关(AI Gateway):同一项目左侧导航栏点击 AI 网关(路由:/console/project-default-enterprise-ai-hub-210/ai-gateway)。

  2. 与上下游模块的关联关系:

    • 知识库(Knowledge Base):创建知识库 kb_enterprise_support 时,必须从「模型」页已启用 embedding 能力的 Provider 中选择向量模型(如 text-embedding-v3,1024 维);开启多模态图片理解时需选择具备 vlm 能力的模型(如 qwen-vl-max);在混合检索(searchMode=hybrid)中开启重排时需选择具备 rerank 能力的模型(如 qwen3.7-text-rerank)。

    • 记忆(Memory):记忆提取、画像生成、梦境整合与经验技能蒸馏(Distillation)依赖「模型」页配置的默认 Chat 与 Embedding 模型。

    • 智能体工作台(Agent Runtime):在工作台中配置主对话模型(如 qwen-plus)并关联知识库 kb_enterprise_support 与词库(lex_enterprise_synonyms、lex_support_stopwords),实现开箱即用的企业级知识问答。

    • 限额与可观测(Limits & Observability):无论通过 LLM Gateway 还是 AI Gateway 发起模型调用,产生的 Prompt Tokens、Completion Tokens、延迟与错误率均自动汇聚至项目的 可观测(Observability) 与 用量限额(Limits) 看板。


功能详解与操作指南

场景一:选型决策——何时使用「模型(LLM Gateway)」与「AI 网关(AI Gateway)」

在实际工程交付中,建议遵循以下「底座先行、网关按需演进」的标准路径:

业务阶段与场景推荐使用的模块核心配置动作
阶段 1:为项目接入大模型算力底座(支撑知识库摄取、混合检索重排、记忆抽取、智能体工作台问答)模型(LLM Gateway)在 模型 -> 模型提供商 中通过「阿里云百炼(DashScope)」预设注册 dashscope-prod,一键导入 qwen-plus、qwen-turbo、text-embedding-v3、qwen3.7-text-rerank、qwen-vl-max 并完成健康探测。
阶段 2:单业务应用直接调用统一兼容接口(后端微服务需以 OpenAI SDK 标准格式调用千问模型)模型(LLM Gateway)在 模型 -> 网关密钥 中签发 gw-key-support-bot(限定模型白名单与月度 Token 预算),业务端将 base_url 指向 https://appbuild.oceanbase.com/v1/ai。
阶段 3:企业多智能体/多渠道生产级流量治理(需要主备模型无缝容灾、敏感信息拦截、语义缓存降本、MCP 工具鉴权审批)AI 网关(AI Gateway)在 AI 网关 -> 网关 中创建实例 prod-enterprise-ai-gateway,配置逻辑模型 lm-enterprise-chat(主路由 qwen-plus,备选故障转移 qwen-turbo),挂载护栏 gp-enterprise-safety 与语义缓存 cp-semantic-cache。

场景二:端到端打通「模型底座 -> AI 网关实例 -> 业务调用」

步骤 1:在「模型(LLM Gateway)」完成供应商注册与健康探测

  1. 进入项目 enterprise-ai-hub-210 的 模型(Models) 页面,在 模型提供商(Providers) 页签点击 添加提供商。

  2. 选择内置厂商预设 通义千问(DashScope),连接名称填写 dashscope-prod,Base URL 自动填充为 https://dashscope.aliyuncs.com/compatible-mode/v1,填入 <DASHSCOPE_API_KEY>。

  3. 勾选开启 chat、embedding、rerank、vlm 四项能力,导入并保留以下 5 个核心模型:

    • 对话模型(Chat):qwen-plus(默认主模型)、qwen-turbo(高并发轻量模型)

    • 向量模型(Embedding):text-embedding-v3(默认维度 1024,最大输入 Token 8192)

    • 重排模型(Rerank):qwen3.7-text-rerank(最大并发与文档片段精排)

    • 视觉模型(VLM):qwen-vl-max(用于知识库多模态图表与扫描件理解)

  4. 保存后点击连接行的 健康检查(Health Check),确认状态徽标更新为绿色 HEALTHY。

步骤 2:在「AI 网关(AI Gateway)」构建高可用逻辑模型与安全策略

  1. 切换至左侧导航栏 AI 网关(AI Gateway) 页面,在 网关(Gateways) 页签创建网关实例:

    • 网关名称:prod-enterprise-ai-gateway

    • 网关实例 ID:gw_7194685489feb1e169548619

  2. 进入 模型路由(Model routing) 页签,创建逻辑模型 lm-enterprise-chat:

    • 将主部署目标(Primary Target)指向 dashscope-prod 下的 qwen-plus(权重 100,优先级 1)。

    • 将备用故障转移目标(Fallback Target)指向 dashscope-prod 下的 qwen-turbo(优先级 2,当主模型超时或返回 5xx/429 时自动接管)。

  3. 进入 策略与凭证(Policies & Credentials) 页签:

    • 创建并绑定安全护栏配置 gp-enterprise-safety(开启入站 Prompt 注入检测与出站手机号/身份证号/密钥脱敏)。

    • 创建并绑定语义缓存策略 cp-semantic-cache(余弦相似度阈值 0.95,TTL 3600 秒)。

    • 为客服机器人主体签发绑定至该网关实例的专属密钥,设置硬性配额(如 QPS 上限 20、月度预算 50,000,000 Tokens)。

步骤 3:验证两套数据面端点的独立调用

通过 curl 分别验证项目级 LLM Gateway 与实例级 AI Gateway 的推理端点,确认两者并存且按各自策略生效:

# 1. 调用项目级 LLM Gateway 标准端点(直接指定物理模型 qwen-plus)
curl -X POST "https://appbuild.oceanbase.com/v1/ai/chat/completions" \
  -H "Authorization: Bearer <APPBASE_GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {"role": "system", "content": "你是企业智能客服助手。"},
      {"role": "user", "content": "请简述 OceanBase 分布式事务的两阶段提交机制。"}
    ],
    "temperature": 0.2
  }'

# 2. 调用统一 AI Gateway 实例端点(指定逻辑模型 lm-enterprise-chat,自动经过护栏与语义缓存)
curl -X POST "https://appbuild.oceanbase.com/ai-gateway/g/gw_7194685489feb1e169548619/v1/chat/completions" \
  -H "Authorization: Bearer <APPBASE_AI_GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lm-enterprise-chat",
    "messages": [
      {"role": "system", "content": "你是企业智能客服助手。"},
      {"role": "user", "content": "请简述 OceanBase 分布式事务的两阶段提交机制。"}
    ],
    "temperature": 0.2
  }'

验证结果:


常见问题与排障

Q1:启用了「AI 网关(AI Gateway)」并配置了逻辑模型后,会影响知识库或记忆模块的模型调用吗?

不会。 Agentbase 的「模型(LLM Gateway)」与「AI 网关(AI Gateway)」采用完全解耦的并存设计。知识库(向量化、重排、图谱抽取、Wiki 编译)、记忆中心与智能体工作台始终通过项目级「模型(LLM Gateway)」读取已注册的 Provider 与物理模型参数;AI 网关仅处理显式发往 /ai-gateway/g/{gatewayId}/... 的数据面流量,绝不劫持或篡改 LLM Gateway 的既有路由。

Q2:使用 abk_ 开头的网关密钥调用 /ai-gateway/g/{gatewayId}/v1/chat/completions 返回 401 Unauthorized 或 403 Forbidden 怎么办?

请按以下顺序排查:

  1. 检查密钥归属面:在「模型(LLM Gateway)」页签创建的普通项目级密钥仅能访问 /v1/ai/* 端点;访问 /ai-gateway/g/{gatewayId}/v1/* 必须使用在该 gatewayId 实例下签发并绑定的网关凭证。

  2. 检查模型白名单与逻辑模型映射:确认请求体中的 model 字段填写的是该网关实例下已发布的逻辑模型名称(如 lm-enterprise-chat)或已导入的标准模型,且当前凭证的角色策略允许访问该模型。

  3. 检查预算熔断状态:前往 AI 网关 -> 策略与凭证,检查该凭证关联的 Token 或 QPS 硬性配额(Budget)是否已达周期上限。

Q3:为什么在创建知识库或开启混合检索 Rerank 时,下拉框中看不到刚才在 DashScope Provider 中填写的模型?

这是因为在「模型(LLM Gateway)」中添加或编辑 Provider 时,不仅需要在模型列表中填入模型名称(如 text-embedding-v3 或 qwen3.7-text-rerank),还必须勾选对应能力的启用开关(embedding / rerank / vlm),并将模型准确填入对应能力的专属模型列表(例如将 text-embedding-v3 填入 Embedding 模型列表,将 qwen3.7-text-rerank 填入 Rerank 模型列表)。建议优先使用 厂商预设(Preset Catalog) 导入模型,系统会自动完成能力分类与上下文窗口、向量维度等参数绑定。

Q4:项目设置(Settings -> Services)中的 AI Gateway 开关关闭后会产生什么影响?

当项目设置中的服务开关关闭时,仅阻断外部客户端通过 Client API / 网关密钥发起的模型推理请求;平台内部系统任务(如已排队的知识库摄取、后台记忆整理、服务端 Server API Key 管理调用)仍按各自权限安全运行,且不会丢失任何已保存的 Provider 或网关策略配置。


相关文档