AgentbaseDocs
文档目录

统一 AI 网关(AI Gateway)

统一 AI 网关(AI Gateway) 是 Agentbase v2.10.0 面向企业多智能体、多模型与多工具生产环境打造的高级 AI 数据面治理中心。通过控制台左侧导航栏的 AI 网关(AI Gateway) 页面,架构师与运维团队可以按网关实例(如 prod-enterprise-ai-gateway)构建隔离的推理与工具入口,统一编排 逻辑模型(Logical Models)、主备故障转移(Fallback Deployments)、安全护栏(Guardrail Profiles)、语义缓存(Semantic Cache Policies)、MCP 工具审批与智能体代理、主体凭证与硬性预算(Principals & Budgets) 以及全维度流量质量观测。


功能概述

当企业 AI 应用从单点原型走向生产级规模化交付时,单纯的模型 API 转发已无法满足高可用、合规安全与成本精益化要求。统一 AI 网关通过以下五大功能页签提供全生命周期治理能力:

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。


核心概念与架构

统一 AI 网关请求处理与治理流水线

flowchart TB
    Client["业务客户端 / 智能体 SDK\n(携带绑定至网关实例的 abk_ 密钥)"]
    Entry["网关实例数据面入口\n/ai-gateway/g/gw_7194685489feb1e169548619/v1/*"]

    subgraph GovernancePipeline["AI Gateway 核心治理流水线 (prod-enterprise-ai-gateway)"]
        AuthBudget["1. 主体鉴权与硬性预算检查\n(Principal & Budgets: QPS / 突发 / 月度 Token 配额)"]
        InboundGuard["2. 入站安全护栏与 OPA 策略\n(gp-enterprise-safety: Prompt 注入拦截 / 敏感词阻断 / PII 脱敏)"]
        CacheLookup["3. 语义缓存检索\n(cp-semantic-cache: 向量相似度 >= 0.95 直接命中返回)"]
        LogicalRoute["4. 逻辑模型动态路由\n(lm-enterprise-chat)"]
        OutboundGuard["5. 出站内容护栏与审计\n(输出合规审查 / 敏感信息掩码 / 缓存回写)"]
        Telemetry["6. 流量与质量遥测汇聚\n(Traffic & Quality: 延迟 / 缓存命中率 / 费率卡成本核算)"]
    end

    subgraph Targets["物理模型部署目标与工具后端"]
        Primary["主部署目标 (Primary Deployment)\ndashscope-prod / qwen-plus (Priority 1, Weight 100)"]
        Fallback["备选容灾目标 (Fallback Deployment)\ndashscope-prod / qwen-turbo (Priority 2)"]
        MCPTools["受管工具与智能体后端\n(Remote MCP / AppBase RAG / A2A Agent)"]
    end

    Client --> Entry --> AuthBudget --> InboundGuard --> CacheLookup
    CacheLookup -->|缓存命中 (HIT)| OutboundGuard
    CacheLookup -->|缓存未命中 (MISS)| LogicalRoute
    LogicalRoute -->|正常流量| Primary
    LogicalRoute -->|超时 / 429 / 5xx 自动故障转移| Fallback
    InboundGuard -->|MCP / 工具调用审批通过| MCPTools
    Primary & Fallback & MCPTools --> OutboundGuard --> Telemetry --> Client

核心概念与配置实体表

实体名称英文标识标杆实例示例核心职责说明
网关实例Gateway Instanceprod-enterprise-ai-gateway (gw_7194685489feb1e169548619)独立的数据面流量入口与策略挂载边界。每个实例拥有唯一的 gatewayId 与不可变运行时配置快照(Snapshot)。
逻辑模型Logical Modellm-enterprise-chat面向业务暴露的虚拟模型名。业务代码固定请求 lm-enterprise-chat,无需感知底层物理模型的切换、升级或跨厂商容灾。
模型部署目标Model Deployment / Target主:qwen-plus<br/>备:qwen-turbo逻辑模型底层绑定的具体 Provider 模型及路由权重、优先级、并发上限与单目标超时参数。
安全护栏配置Guardrail Profilegp-enterprise-safety定义入站(Input)与出站(Output)的内容安全检测规则,涵盖越狱/注入攻击阻断、PII(手机号/身份证/银行卡/密钥)自动掩码或拒绝、合规关键词过滤。
语义缓存策略Cache Policycp-semantic-cache基于 Embedding 向量相似度的智能缓存机制。当新请求的语义向量与历史缓存条目的余弦相似度达到阈值(如 0.95)时,直接返回缓存响应。
主体与凭证Principal & Credentialprincipal-support-agent调用网关的业务身份主体及其绑定的 abk_ 网关密钥、角色标签与允许访问的逻辑模型/工具范围。
硬性预算配额Budgetbudget-monthly-support绑定在网关、主体或密钥维度的硬性限额,支持 QPS、突发请求数(Burst)、总请求数与总 Token 消耗的分钟/小时/日/月周期熔断。

角色、入口与关联关系

启用前提与权限矩阵

统一 AI 网关属于项目级高级治理服务,默认处于关闭状态。要访问左侧导航栏的 AI 网关(AI Gateway) 入口,需同时满足两个条件:

权限维度Owner / AdminDeveloper安全/合规审计员
创建/修改网关实例与封存运行时快照支持不支持只读查看快照历史
配置逻辑模型(lm-enterprise-chat)与主备部署路由支持支持只读
编辑安全护栏(gp-enterprise-safety)、OPA 策略与执行 Dry-Run支持支持 Dry-Run 调试支持审批与审计查看
审批高危 MCP 工具发布与管理连接模板支持可提交工具注册申请支持安全评审
签发网关专属凭证与调整硬性预算(Budgets)支持仅限个人测试凭证只读查看预算消耗

与其他模块的协同关系


功能详解与操作指南

一、创建网关实例(prod-enterprise-ai-gateway)与快照治理

字段名称参数标识标杆配置值说明
网关名称nameprod-enterprise-ai-gateway生产环境企业智能客服与知识中台统一网关
网关标识(ID)gatewayIdgw_7194685489feb1e169548619系统生成或自定义的唯一实例 ID,作为数据面 URL 路径的一部分
描述信息description承载客服对话主备路由、安全护栏与语义缓存的生产网关说明网关的业务用途与归属团队
默认安全护栏defaultGuardrailProfilegp-enterprise-safety实例级默认挂载的入站/出站安全护栏策略
默认缓存策略defaultCachePolicycp-semantic-cache实例级默认挂载的语义缓存策略

二、配置逻辑模型(lm-enterprise-chat)与主备容灾路由

配置项参数名标杆配置值路由行为说明
逻辑模型名称logicalModelNamelm-enterprise-chat客户端请求体中 model 字段填写的逻辑名称
能力类型capabilitychat支持 OpenAI Chat Completions、Responses 与 Anthropic Messages 协议
路由策略routingStrategypriority_failover(优先级主备容灾)优先路由至 Priority 1 部署目标;当主目标发生超时、429 限流或 5xx 错误时,零中断自动切换至 Priority 2 备选目标
主部署目标(Target 1)deployments[0]Provider: dashscope-prod<br/>Model: qwen-plus<br/>Priority: 1, Weight: 100<br/>Timeout: 60s承载正常生产流量的主力高推理能力模型
备选部署目标(Target 2)deployments[1]Provider: dashscope-prod<br/>Model: qwen-turbo<br/>Priority: 2, Weight: 100<br/>Timeout: 30s当 qwen-plus 出现上游限流或高延迟时的自动降级兜底模型

三、配置安全护栏(gp-enterprise-safety)与语义缓存(cp-semantic-cache)

切换到 策略与凭证(Policies & Credentials) 页签,分别配置安全护栏、语义缓存与硬性预算:

1. 安全护栏配置(gp-enterprise-safety)

护栏规则项作用方向标杆配置值触发动作
Prompt 注入与越狱检测入站(Inbound)enabled = true(严格模式)阻断请求(BLOCK),返回标准合规提示与 400 GuardrailBlocked
PII 敏感隐私信息脱敏入站 + 出站(Both)检测手机号、身份证号、银行卡号、API 密钥自动掩码替换(REDACT,如 138****5678)后再发往模型或返回客户端
企业违禁词与竞品恶意引导过滤入站 + 出站(Both)关联企业合规词表阻断生成并记录安全审计事件
OPA 策略预演(Dry-Run)策略发布前验证输入测试 JSON 载荷在不改变线上流量的前提下,预览策略允许/拒绝决策及规则命中明细

2. 语义缓存策略配置(cp-semantic-cache)

缓存参数项参数名标杆配置值说明
策略名称namecp-semantic-cache企业客服高频问答语义缓存策略
向量化模型embeddingModeltext-embedding-v3 (1024 维)用于计算用户提问语义向量的嵌入模型
相似度命中阈值similarityThreshold0.95仅当余弦相似度 $\ge 0.95$ 时才判定为语义等价并命中缓存,兼顾准确率与召回率
缓存有效期(TTL)ttlSeconds3600(1 小时)缓存条目的自动过期时间;知识库版本发布后支持一键清空关联缓存
排除条件bypassWhentemperature > 0.7 或携带 X-AI-Gateway-No-Cache: true高随机性创作请求或显式要求实时计算的请求自动绕过缓存

3. 凭证签发与硬性预算(Budgets)

在 凭证与预算 区域,为客服业务主体创建专属 abk_ 网关密钥(强制绑定至 gw_7194685489feb1e169548619),并配置多维硬性配额:


四、配置工具与智能体(Tools & Agents)及审批流


五、验证多协议数据面调用与流量质量观测

使用绑定至 gw_7194685489feb1e169548619 的网关密钥,验证 OpenAI Chat Completions、Responses 与 Anthropic Messages 兼容接口:

# 1. 调用网关实例的 OpenAI Chat Completions 兼容入口
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": "user", "content": "我的工单号是 TK-20261022-001,联系电话 13800138000,请帮我解释 OceanBase 向量索引排障步骤。"}
    ]
  }'

# 2. 调用网关实例的 Anthropic Messages 兼容入口
curl -X POST "https://appbuild.oceanbase.com/ai-gateway/g/gw_7194685489feb1e169548619/v1/messages" \
  -H "x-api-key: <APPBASE_AI_GATEWAY_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lm-enterprise-chat",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "请总结智能客服 SOP 标准作业手册中的工单升级时限要求。"}
    ]
  }'

验证结果:


常见问题与排障

Q1:可以不带 /ai-gateway/g/{gatewayId} 前缀,直接通过 /v1/ai/chat/completions 调用逻辑模型 lm-enterprise-chat 吗?

不可以。 统一 AI 网关的设计原则是「严格按网关实例隔离,不提供无 Gateway ID 的推理别名路由」。逻辑模型 lm-enterprise-chat、护栏 gp-enterprise-safety 与缓存 cp-semantic-cache 均挂载在具体网关实例 gw_7194685489feb1e169548619 下,因此必须通过 /ai-gateway/g/gw_7194685489feb1e169548619/v1/... 路径访问。

Q2:为什么注册了一个新的 MCP 工具后,无法将其审批模式设置为「无需审批(No Approval)」?

为了防范未授权工具调用导致的数据越权或生产事故,AI 网关内置了强制安全门禁:任何被标记为高风险等级(High Risk)或尚未通过安全评审(Unreviewed)的工具,系统在接口与控制台层面均严禁直接以「无需审批」模式发布。请先由项目管理员完成工具安全评审并将风险等级确认为低风险只读,或改用「按策略审批 / 始终审批」模式。

Q3:语义缓存(cp-semantic-cache)命中后返回了旧版本的知识回答,如何立即刷新?

当知识库(如 kb_enterprise_support)发布了新版本或业务规则发生重大变更时,您可以:

Q4:主模型 qwen-plus 触发自动容灾切换到备选模型 qwen-turbo 时,客户端需要修改代码重试吗?

不需要。 故障转移在 AI 网关内部透明完成。客户端只需单次请求逻辑模型 lm-enterprise-chat,网关检测到主部署目标超时或返回 429/5xx 后,会在同一请求生命周期内自动切换至备选部署目标 qwen-turbo,并在响应元数据及 流量与质量 观测日志中标注实际执行的物理部署目标。


相关文档