Docs
文档目录

AI Gateway(统一 AI 数据面)

这是什么 / 何时用

AI Gateway 是 2.6.0 新增的统一 AI 数据面与控制面(services/ai-gateway),承载模型推理、Target 接入、Tool/MCP、A2A、HTTP Agent、身份(Consumer/Key)、策略(Policy)、预算、缓存与审计。资源模型:Gateway / Target / Tool / Consumer / Policy / Snapshot——Target 与 Tool 是项目级资产,经挂载关系进入一个或多个 Gateway Snapshot。

与既有 LLM Gateway 并存:不迁移旧资源、不接管旧生产路径、不提供无 gatewayId 的兼容别名。只要现有 Provider/Gateway Key/Chat/Embeddings/Rerank/VLM,继续用 llm-gateway.md;涉及 Gateway/Target/Tool/Consumer/Policy/MCP/A2A 才用本页。两者名称、凭据、路径互不互换。

前置

使用骨架

数据面入口(HTTP,2.6.0 新增;SDK 不封装这些路径):

控制面(SDK AiGateway 服务):

  1. 建 Gateway 并管理策略:createPolicyEngine / listPolicyEngines / getPolicyEngine;updateGatewayPolicy({ gatewayId, ... });策略包 createRevision/publishPolicyBundle/listPolicyBundles/getPolicyBundle;上线前 dryRunPolicy 验证;发布语义用 Snapshot:sealSnapshot / getSnapshotStatus。

  2. 接入 Target:createResource / listResources / getResource / replaceResource(kind 为资源类别路径参数);修订管理 createRevision / getRevision / transitionRevision(/resources/{kind}/{id}/revisions/{revisionId}/{action});健康与发现 checkTargetHealth / discoverTargetModels;挂载 listTargetMounts / replaceTargetMounts。

  3. 模型部署与标准模型:testModelDeployment / getModelDeploymentMetrics;createStandardModel / importStandardModels / listStandardModels / updateStandardModel。

  4. Tool/MCP 连接:createToolConnection / discoverToolConnection / updateToolConnection / deleteToolConnection。

  5. Consumer 凭据:createKey / listKeys / getKey / updateKeyStatus(abk_ 的签发与启停)。

  6. 观测与审计:getObservabilityOverview / listInvocations / getInvocation。

2.7.0 增量(appbase release-2.7.0 PR 526):

2.8.0 增量:

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

数据面入口(推理 / MCP / A2A / HTTP Agent)

推理 / MCP / A2A / HTTP Agent 是 HTTP 数据面入口,各语言 SDK(含 Web)均不封装这些路径,故本卡仅 REST 页签;公开 listener 用目标 Gateway 签发的 abk_ Key(Authorization: Bearer 携带),LLM Gateway Key、项目 API Key、上游 Provider Key 都不能当 abk_ 用。

# 推理:Responses / Chat / Embeddings / Messages 共用 /ai-gateway/g/<GATEWAY_ID>/v1 前缀
curl -sS -X POST "$APPBASE_ENDPOINT/ai-gateway/g/<GATEWAY_ID>/v1/chat/completions" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AI_GATEWAY_KEY" \
  -d '{"model":"<model>","messages":[{"role":"user","content":"你好"}]}'
# MCP:/ai-gateway/g/<GATEWAY_ID>/mcp(Tool 列表/搜索/调用共用 Agent allowlist 与 OPA 授权,副作用受幂等门禁保护)
# A2A:/ai-gateway/g/<GATEWAY_ID>/a2a/<targetSlug>(Task/Context 按调用者 + Target Revision 隔离)
# HTTP Agent:/ai-gateway/g/<GATEWAY_ID>/http/<targetSlug>[/{path...}](只转发 Target 允许的方法/相对路径/query/body,
#   不重放调用方认证 Header,凭据从受控 Credential 解析)

建 Gateway 并管理策略(策略引擎 / 策略包 / Snapshot)

策略引擎创建后把策略包经 dry-run 验证再 publish、经 updateGatewayPolicy 挂到 Gateway;sealSnapshot 封存当前配置(异步),Target / Consumer / Tool allowlist / Policy 变更只在已发布且一致的 Snapshot 上对公开流量生效。

await aiGateway.listPolicyEngines();                             // 策略引擎列表
await aiGateway.updateGatewayPolicy({ gatewayId: '<gatewayId>' }); // 挂接策略(字段见 SDK 类型定义)
await aiGateway.sealSnapshot({ gatewayId: '<gatewayId>' });      // 封存为 Snapshot(异步)
await aiGateway.getSnapshotStatus({ gatewayId: '<gatewayId>' }); // 轮询封存结果
// 策略引擎创建/详情:createPolicyEngine / getPolicyEngine
// 策略包:createRevision / publishPolicyBundle / listPolicyBundles / getPolicyBundle;上线前 dryRunPolicy 验证(只评估不执行)

接入 Target(资源 / 修订 / 挂载)

Target 走统一资源端点(kind 为路径参数)与修订状态机上线;健康检查、模型发现与挂载整体替换均为资源专有操作。

// 统一资源面:listResources / createResource / getResource / replaceResource / deleteResource
//   kind 为资源类别路径参数;请求体为泛化 schema,以 SDK 类型定义为准
// 修订:createRevision / getRevision / transitionRevision(资源上线走修订状态机)
// Target 运维:checkTargetHealth / discoverTargetModels;挂载:listTargetMounts / replaceTargetMounts

模型部署与标准模型

模型部署可先实测一次推理再上线;标准模型目录支持手工登记、把目标发现的模型批量导入合并与更新。

// 模型部署:testModelDeployment(实测部署推理)/ getModelDeploymentMetrics(部署指标)
// 标准模型:createStandardModel / importStandardModels / listStandardModels / updateStandardModel

Tool/MCP 连接

Tool 连接是 Tool/MCP 数据面调用的上游接入:创建后可触发工具发现、测试连通性、更新配置与删除(删除后网关侧随即不可再经此连接调用工具)。2.8.0 起支持连通性测试:testToolConnection(id, toolId)(toolId 可选)(POST /ai-gateway/tool-connections/{id}/test),返回诊断结果(目标可达性、凭据检查与逐工具状态),Console 连接诊断面板同源。

// createToolConnection / discoverToolConnection / updateToolConnection / deleteToolConnection
// 2.8.0 连通性测试:aiGateway.testToolConnection('<id>');可选第二参 toolId 只测单个工具
// payload 由目标资源定义,字段见 SDK 类型定义

Consumer 凭据(abk_ Key)签发与启停

createKey 签发 abk_ 凭据,用 gatewayIds 圈定可调用网关,allowedModels / allowedTools / allowedAgents 圈定模型、工具与 Agent Target;停用后立即无法通过网关校验。

import { AiGateway } from 'agentbase-node-sdk';

const aiGateway = new AiGateway(client);   // 控制面:aiGateway.read / aiGateway.write

await aiGateway.listKeys();                // abk_ 元数据视图
await aiGateway.createKey({
    name: 'agent-consumer',
    gatewayIds: ['<gatewayId>']            // allowlist 与 principal 字段见 SDK 类型定义
});
// 启停:aiGateway.updateKeyStatus(...)(abk_ 停用后立即无法通过网关校验)

观测与审计

调用记录与观测总览按 aiGateway.read scope 查询,用于网关调用的排障与审计。

await aiGateway.getObservabilityOverview();   // 观测总览
await aiGateway.listInvocations();            // 调用记录列表(过滤参数见 SDK 类型定义)
// 单条调用记录:getInvocation

示例指引