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 才用本页。两者名称、凭据、路径互不互换。
前置
启用门禁:Docker Compose 需显式启用
ai-gatewayprofile;聚合 Helm 默认aiGateway.enabled=false;当前仅支持 OceanBase Shared V2 项目。项目服务首次显式启用时才初始化项目控制表。公开 listener 用目标 Gateway 签发的 abk_ Key:验证 Key + Gateway + Consumer + 已发布 Snapshot 的一致性。LLM Gateway Key、项目 API Key、上游 Provider Key 都不能当 abk_ 用。
内部服务走独立 internal listener + 签名 runtime context(不发凭据);internal listener 不得暴露到 Ingress,公开 listener 必须拒绝内部 context。
使用骨架
数据面入口(HTTP,2.6.0 新增;SDK 不封装这些路径):
模型推理在 v2.12.0 的 AI Gateway 中不可用;模型调用使用 LLM Gateway。
MCP:
/ai-gateway/g/{gatewayId}/mcp(Tool 列表/搜索/调用共用 Agent allowlist 与 OPA 授权,副作用受幂等门禁保护)。A2A:
/ai-gateway/g/{gatewayId}/a2a/{targetSlug}(Task/Context 按调用者 + Target Revision 隔离)。HTTP Agent:
/ai-gateway/g/{gatewayId}/http/{targetSlug}[/{path...}](只转发 Target 允许的方法/相对路径/query/body,不重放调用方认证 Header,凭据从受控 Credential 解析)。
控制面(SDK AiGateway 服务):
建 Gateway 并管理策略:
createPolicyEngine/listPolicyEngines/getPolicyEngine;updateGatewayPolicy({ gatewayId, ... });策略包createRevision/publishPolicyBundle/listPolicyBundles/getPolicyBundle;上线前dryRunPolicy验证;发布语义用 Snapshot:sealSnapshot/getSnapshotStatus。接入 Target:
createResource/listResources/getResource/replaceResource(kind为资源类别路径参数);修订管理createRevision/getRevision/transitionRevision(/resources/{kind}/{id}/revisions/{revisionId}/{action});健康检查checkTargetHealth;挂载listTargetMounts/replaceTargetMounts。模型推理、模型部署与标准模型管理在 v2.12.0 不可用。
Tool/MCP 连接:
createToolConnection/discoverToolConnection/updateToolConnection/deleteToolConnection。Consumer 凭据:
createKey/listKeys/getKey/updateKeyStatus(abk_ 的签发与启停)。观测与审计:
getObservabilityOverview/listInvocations/getInvocation。
2.7.0 增量(appbase release-2.7.0 PR 526):
凭据治理:
createKey新增可选limits——硬性限流/配额规则数组,元素{ scope, resourceId, rate, quota }(resourceId、rate、quota均可选):scope取credential/model/tool/agent(非credential需指定resourceId);rate为requestsPerSecond+burst(burst缺省取requestsPerSecond);quota按minute/hour/day/month周期限制requests/tokens(tokens仅credential/modelscope)。网关数据面按规则 fail-closed 执行。工具审批闭环:Tool 的静态审批下限(
none/always/policy)与策略引擎决策合成 fail-closed 运行时门禁;命中REQUIRE_APPROVAL时生成审批请求(ID 形如apr_前缀,TTL 15 分钟,重放调用经X-AppBase-Approval-Request-Id头关联);策略强制拒绝不可被人工审批提升为放行。审批面无新增公开 SDK 方法/端点。托管工具模板:
rag用于托管 RAG;standard-models模板所依赖的标准模型管理接口在 v2.12.0 已禁用。
2.8.0 增量:
工具连接连通性测试:
testToolConnection(id, toolId)(toolId可选)(POST /ai-gateway/tool-connections/{id}/test,2.8.0)——对工具连接做连通性测试与诊断(目标可达性、凭据与逐工具检查,Console 连接诊断面板同源);可选toolId只测单个工具。逻辑模型挂载:v2.12.0 不提供逻辑模型配置;历史 SDK 方法不能作为可用功能使用。
关键参数与返回
资源类方法的
kind是路径参数(资源类别),配合资源 ID 定位修订与挂载;具体可用类别以目标实例 specs/返回为准,不要凭猜测拼类别名。Snapshot:发布门禁的落点——Target/Consumer/Tool allowlist/Policy 变更只有在已发布且一致的 Snapshot 上对公开流量生效。
策略包(Policy Bundle)经 dry-run 验证后 publish;
transitionRevision承担修订状态迁移动作。
错误与边界
出站受 SSRF、重定向与大小限制;默认拒绝私网,部署可按精确主机白名单受控开放指定私网端点,云元数据等受保护地址仍不可访问。
工具调用详情可能保存经过有限字段脱敏和截断的参数及结果预览;不能保证任意业务内容已脱敏。列表、CSV、OTel 和 Langfuse 不包含该预览。调用前应自行处理敏感信息。
A2A/HTTP 方法、出站地址、重定向均过 allowlist;越权即拒绝。
项目服务
aiGateway与llmGateway是两个独立开关;工具数据面检查aiGateway。
SDK 类别差异
Server SDK(server-sdk/nodejs.md)与客户端 SDK(client-sdk/web.md):
AiGateway服务面一致(控制面全集);MCP/A2A/HTTP 走 HTTP 入口;模型推理使用 LLM Gateway。Console SDK(console-sdk/nodejs.md):2.6.0 不含 AI Gateway 服务。
Java Server / Console SDK 均有
AiGateway服务。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
工具数据面入口(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_ 用。
- REST(curl)
# 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 上对公开流量生效。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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 验证(只评估不执行)// Web SDK 同一 AiGateway 控制面
await aiGateway.sealSnapshot({ gatewayId: '<gatewayId>' });
await aiGateway.getSnapshotStatus({ gatewayId: '<gatewayId>' });aiGateway.listPolicyEngines(); // 策略引擎列表
aiGateway.updateGatewayPolicy("<gatewayId>"); // 挂接策略
aiGateway.sealSnapshot("<gatewayId>"); // 封存为 Snapshot(异步)
aiGateway.getSnapshotStatus("<gatewayId>"); // 轮询封存结果
// 策略引擎创建/详情:createPolicyEngine / getPolicyEngine
// 策略包:createRevision / publishPolicyBundle / listPolicyBundles / getPolicyBundle;上线前 dryRunPolicy 验证(只评估不执行)# server-python@release-2.6.0 无 AiGateway 服务;控制面暂经 REST(见下)或 nodejs SDK 调用// server-go@release-2.6.0 无 AiGateway 服务;控制面暂经 REST(见下)或 nodejs SDK 调用curl -sS -X POST "$APPBASE_ENDPOINT/ai-gateway/gateways/<GATEWAY_ID>/snapshots" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 异步封存:轮询 GET .../gateways/<GATEWAY_ID>/snapshots/status 至完成
# 策略面(body 字段以 API 参考 / SDK 类型定义为准):PUT .../gateways/<GATEWAY_ID>/policy;
# GET|POST /ai-gateway/policy-engines;POST .../policy-engines/{policyEngineId}/bundles(发布);
# POST .../policy-engines/{policyEngineId}/dry-run(上线前试运行)接入 Target(资源 / 修订 / 挂载)
Target 走统一资源端点(kind 为路径参数)与修订状态机上线;健康检查与挂载整体替换为资源专有操作。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// 统一资源面:listResources / createResource / getResource / replaceResource / deleteResource
// kind 为资源类别路径参数;请求体为泛化 schema,以 SDK 类型定义为准
// 修订:createRevision / getRevision / transitionRevision(资源上线走修订状态机)
// Target 运维:checkTargetHealth;挂载:listTargetMounts / replaceTargetMounts// Web SDK 同一 AiGateway 控制面:资源 / 修订 / 挂载方法名同 Node 页签// Java 面不外露泛化 schema 请求体,方法只收定位参数(kind 为资源类别路径参数):
aiGateway.createResource("targets"); // 创建资源
aiGateway.createRevision("targets", "<id>"); // 建修订
aiGateway.transitionRevision("targets", "<id>", "<revisionId>", "publish"); // 修订状态机上线
aiGateway.checkTargetHealth("<id>"); // 探活
aiGateway.replaceTargetMounts("<id>"); // 挂载整体替换# server-python@release-2.6.0 无 AiGateway 服务// server-go@release-2.6.0 无 AiGateway 服务(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 资源创建(kind=targets)与整体替换:POST|PUT /ai-gateway/resources/{kind}[/{id}]
# (请求体为泛化 schema,字段见 API 参考 / SDK 类型定义)
# 上线走修订状态机:POST .../resources/{kind}/{id}/revisions → POST .../revisions/{revisionId}/{action}
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/ai-gateway/resources/targets/<ID>/revisions/<REVISION_ID>/publish" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
# 探活:POST .../resources/targets/<ID>/health-check
# 挂载整体替换:PUT .../resources/targets/<ID>/mounts
)模型部署与标准模型
v2.12.0 禁用 AI Gateway 的模型部署、发现和标准模型管理;请使用 LLM Gateway 接入模型。
Tool/MCP 连接
Tool 连接是 Tool/MCP 数据面调用的上游接入:创建后可触发工具发现、测试连通性、更新配置与删除(删除需要 region 参数,活动连接须先停用;删除后应验证相关工具调用的实际结果)。2.8.0 起支持连通性测试:testToolConnection(id, toolId)(toolId 可选)(POST /ai-gateway/tool-connections/{id}/test),返回诊断结果(目标可达性、凭据检查与逐工具状态),Console 连接诊断面板同源。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// createToolConnection / discoverToolConnection / updateToolConnection / deleteToolConnection
// 2.8.0 连通性测试:aiGateway.testToolConnection('<id>');可选第二参 toolId 只测单个工具
// payload 由目标资源定义,字段见 SDK 类型定义// Web SDK 同一 AiGateway 控制面:工具连接方法名同 Node 页签// 工具连接创建、发现、更新和删除的请求体与 region 要求见 API 参考;
// 请先核对所用 Java SDK 的实际方法签名。# server-python@release-2.6.0 无 AiGateway 服务// server-go@release-2.6.0 无 AiGateway 服务(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 创建 / 发现可用工具:POST /ai-gateway/tool-connections、POST .../tool-connections/discover
# (payload 由目标资源定义,字段见 SDK 类型定义)
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/ai-gateway/tool-connections/discover" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"endpoint":"https://tools.example.com/mcp"}'
# 更新:PUT .../tool-connections/<ID>(完整请求体见 API 参考);删除:DELETE .../tool-connections/<ID>?region=<REGION>(先停用活动连接)
# 连通性测试(2.8.0):POST .../tool-connections/<ID>/test(可选 body {"toolId":"<TOOL_ID>"} 只测单个工具)
)Consumer 凭据(abk_ Key)签发与启停
createKey 签发 abk_ 凭据,用 gatewayIds 圈定可调用网关,allowedModels / allowedTools / allowedAgents 圈定模型、工具与 Agent Target。停用会尝试清除认证缓存;若清除失败,旧缓存可能短暂有效,已在途请求也可能继续。应验证实际调用被拒绝,不能只依赖成功响应。
省略 allowedModels、allowedTools 或 allowedAgents 时,该项默认为 ["*"];空数组表示拒绝该类型。以下示例仅允许指定工具,不允许模型或 Agent,仍受快照和策略约束。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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>'],
allowedModels: [], allowedTools: ['<TOOL_ID>'], allowedAgents: [] // allowlist 与 principal 字段见 SDK 类型定义
});
// 启停:aiGateway.updateKeyStatus(...);验证停用后的实际调用结果import { AiGateway } from 'agentbase-web-sdk'; // Web SDK 与 Server 的 AiGateway 服务面一致(控制面全集)
const aiGateway = new AiGateway(client);
await aiGateway.listKeys();
await aiGateway.createKey({ name: 'agent-consumer', gatewayIds: ['<gatewayId>'], allowedModels: [], allowedTools: ['<TOOL_ID>'], allowedAgents: [] });import io.agentbase.services.AiGateway;
AiGateway aiGateway = new AiGateway(client); // Java Server SDK 有 AiGateway 服务
aiGateway.listKeys();
aiGateway.createKey("agent-consumer", List.of("<gatewayId>"),
null, List.of(), List.of("<TOOL_ID>"), List.of(), null, null); // region / allowedModels / allowedTools / allowedAgents / defaultLogicalModel / principal# server-python@release-2.6.0 无 AiGateway 服务;abk_ 签发/启停暂经 REST(见下)或 nodejs SDK 调用// server-go@release-2.6.0 无 AiGateway 服务;
// abk_ Key 签发/启停暂经 REST(见下)或 nodejs SDK 调用(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/ai-gateway/keys" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"name":"agent-consumer","gatewayIds":["<gatewayId>"],"allowedModels":[],"allowedTools":["<TOOL_ID>"],"allowedAgents":[]}'
# allowlist 圈定:allowedModels / allowedTools / allowedAgents;principal 携带角色与扁平 claims(字段见 API 参考)
# 列表 GET /ai-gateway/keys;明文找回 GET .../keys/{keyId}(可恢复语义);启停 PUT .../keys/{keyId}/status
)观测与审计
调用记录与观测总览按 aiGateway.read scope 查询,用于网关调用的排障与审计。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
await aiGateway.getObservabilityOverview(); // 观测总览
await aiGateway.listInvocations(); // 调用记录列表(过滤参数见 SDK 类型定义)
// 单条调用记录:getInvocation// Web SDK 同一 AiGateway 控制面
await aiGateway.getObservabilityOverview();
await aiGateway.listInvocations();aiGateway.getObservabilityOverview(); // 观测总览
aiGateway.listInvocations(); // 调用记录列表(过滤参数见 SDK 类型定义)
// 单条调用记录:getInvocation# server-python@release-2.6.0 无 AiGateway 服务// server-go@release-2.6.0 无 AiGateway 服务;
// 观测与审计暂经 REST(见下)或 nodejs SDK 调用curl -sS "$APPBASE_ENDPOINT/ai-gateway/observability/overview" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 调用记录:GET /ai-gateway/invocations;单条:GET /ai-gateway/invocations/<INVOCATION_ID>示例指引
JavaScript(Node 控制面调用 + 数据面 HTTP 形态):examples/javascript.md
Java:examples/java.md
2.12.0 — 审批、初始化与工具向量
新增 listApprovalRequests/getApprovalRequest/approveApprovalRequest/rejectApprovalRequest、getInitializationStatus、listToolEmbeddings/createToolEmbeddings。读取与写入分别需要 aiGateway.read / aiGateway.write。先查看请求所属工具、调用与当前状态,再明确批准或拒绝;不能为了重试读取而重复批准。工具向量化可能调用模型,查询初始化状态不等于所有资源已就绪。