AgentbaseDocs
文档目录

模型与 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 中台落地过程中,研发与架构团队通常面临两类截然不同的模型管理诉求:


核心概念与架构

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

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

flowchart TB
    subgraph ExternalClients["外部业务与智能体客户端"]
        AppClient["业务后端 / 移动端SDK"]
        AgentClient["MCP / A2A / OpenAI 客户端"]
    end

    subgraph PlatformInternal["Agentbase 平台内生 AI 服务"]
        KB["知识库 (Knowledge Base)\n向量化 / Rerank / GraphRAG / Wiki"]
        Mem["记忆中心 (Memory)\n事实抽取 / 画像 / 梦境 / 蒸馏"]
        Workbench["智能体工作台 (Agent Runtime)\n在线对话与词库检索联动"]
        Obs["可观测评估 (Observability)\nLLM-as-a-Judge 质量打分"]
    end

    subgraph AIGatewayLayer["统一 AI 网关层 (AI Gateway: prod-enterprise-ai-gateway)"]
        GWEntry["数据面入口: /ai-gateway/g/{gatewayId}/v1/*"]
        Budget["主体凭证与预算控制\n(Principals / QPS & Token Budgets)"]
        Guardrail["安全护栏与策略引擎\n(gp-enterprise-safety / OPA)"]
        SemCache["语义缓存策略\n(cp-semantic-cache)"]
        LogicalModel["逻辑模型路由与主备容灾\n(lm-enterprise-chat: qwen-plus -> qwen-turbo)"]
        ToolGov["MCP 工具审批与智能体网关"]
    end

    subgraph LLMGatewayLayer["项目级模型层 (LLM Gateway: Models)"]
        LLMRouter["项目级模型路由与目录\n(/v1/ai/chat/completions, /v1/ai/embeddings, /v1/ai/rerank)"]
        PresetCatalog["厂商预设目录 (24 预设 / 313 模型)\n按模型上下文窗口、维度、并发参数治理"]
        TrialBinding["平台体验模型绑定 (Trial Models)"]
        Provider["已注册模型供应商 (dashscope-prod)\n健康检查: HEALTHY"]
    end

    subgraph Upstream["上游模型推理服务"]
        DashScope["阿里云百炼 DashScope API\n(qwen-plus / qwen-turbo / text-embedding-v3 / qwen3.7-text-rerank / qwen-vl-max)"]
    end

    AppClient -->|Authorization: Bearer abk_...| LLMRouter
    AgentClient -->|Authorization: Bearer abk_...| GWEntry
    GWEntry --> Budget --> Guardrail --> SemCache --> LogicalModel
    GWEntry --> ToolGov
    LogicalModel -->|复用或指向底层 Provider| Provider
    KB & Mem & Workbench & Obs -->|内部安全算力调用| LLMRouter
    LLMRouter --> PresetCatalog
    LLMRouter --> TrialBinding
    LLMRouter --> Provider
    Provider -->|HTTPS 加密调用| DashScope

核心概念与能力对比表

维度模型(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 下的数据面推理与工具端点,受主体预算与护栏策略实时约束

控制台入口与上下游关联


功能详解与操作指南

场景一:选型决策——何时使用「模型(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)」完成供应商注册与健康探测

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

步骤 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 怎么办?

请按以下顺序排查:

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 或网关策略配置。


相关文档