LLM Gateway(大模型网关)
这是什么 / 何时用
LLM Gateway 是项目级的大模型代理(/v1/llm-gateway/*):统一管理上游 Provider(OpenAI 兼容 / Anthropic / DashScope),签发 Gateway Key,转发 Chat Completions、Messages、Embeddings、Rerank 请求,并输出用量统计。适合:前端/服务端用同一套 OpenAI 兼容接口调多家模型;给第三方下发受限的模型 Key;统计项目 token 消耗。
与 AI Gateway(2.6.0 新统一 AI 数据面,ai-gateway.md)并存:两套资源、两条验证链路,Key 即使外观相同也不可互换;不提供旧资源迁移或无差别别名。
前置
- Scopes:Provider 管理
providers.read/providers.write;Key 管理keys.read/keys.write;执行类execute;用量查询需对应 read scope。 - 执行类四种认证(任选):① Gateway Key(
Authorization: Bearer abk_...或x-api-key,Key 内嵌项目 ID,免x-appwrite-project);② 项目 API Key(x-appwrite-key+x-appwrite-project,需含 execute);③ 用户 Session(cookie);④ JWT(x-appwrite-jwt)。 - Gateway Key 只能调执行类接口,不能管理资源或读用量;明文只在创建响应里出现一次,之后只返回 keyPrefix。
- 项目级
llmGateway服务开关只拦截 Client API 身份访问整个 namespace,不删除 Provider/Key;新项目默认开启。
使用骨架
- 接 Provider:
createProvider({ providerId, connectionName, providerType, baseUrl, apiKey, defaultModel, allowedCapabilities: ['chat'|'embedding'|'rerank'|'vlm'], supportedModels, priority, timeoutMs, maxRetries })。supportedModels用["*"]放行任意模型,否则与请求 model 精确匹配;priority越小越优先,主 Provider 失败按优先级 failover。仅dashscope支持从云端拉模型列表(listProviderModels),OpenAI/Anthropic 兼容类型需手填supportedModels。批量更新后调refreshProviderCache()刷新路由缓存。 2.9.0 起:providerType扩至 24 个厂商预设类型(OpenAI / Anthropic 的官方与 API-Compatible、火山方舟(豆包)volcengine、openai-official/anthropic-official、xAI、智谱、Moonshot、DeepSeek 等,及 Ollama / vLLM 等自托管类);先用listProviderPresets()(GET /v1/llm-gateway/provider-presets,无需鉴权外 scope)获取预置目录(24 厂商 / 313 模型,含 Base URL、默认能力与按模型参数:上下文窗口、最大输出、Embedding 维度与输入上限、工具调用、多模态 Embedding),选中预设后 Base URL 与模型清单可直接带入createProvider;Provider 支持**按模型modelMetadata** 保存并合并预设值,供平台内部任务(知识库索引、Memory)使用。 - 签发 Gateway Key:
createKey({ keyId, name, description, allowedModels, monthlyTokenBudget, rateLimit, expiresAt });rateLimit为每分钟请求数(null 用项目默认);isActive: false立即禁用,删除即吊销。 - 执行:
createChatCompletion({ model, messages, temperature, maxTokens, stream, tools, toolChoice })——OpenAI 兼容;messages原样透传(文本/多模态/工具调用都支持),stream: true走 SSE;视觉模型(VLM)同样经 chat completions 传图片内容。createMessage(...)——Anthropic Messages 形态。createEmbeddings({ model, input })——dimensions需与向量 collection 维度一致。createRerank({ model, query, documents, topN, returnDocuments })。listModels/getModel查询可用模型。
- 用量(Console SDK):
getUsage/getUsageModels/getKeyUsage({ startDate, endDate, period: '1h' | '1d' })——Chat 请求数、输入/输出/总 token、Embedding/Rerank token、按模型聚合。
关键参数与返回
- Provider
apiKey加密存储,响应只回apiKeySet布尔;Provider 路径默认chatCompletionsPath=/v1/chat/completions、embeddingsPath=/v1/embeddings、rerankPath为空表示不启用。 - 路由规则:显式匹配按
priority升序 →["*"]Provider → 可用 Provider 兜底;禁止 OpenRouter 式provider/model前缀写法。 - Key 的
allowedModels与请求model精确匹配;不匹配报Model not allowed。 - Function 内调用:使用平台注入的动态 Key(请求头
x-appwrite-key)+APPWRITE_FUNCTION_PROJECT_ID+APPWRITE_FUNCTION_API_ENDPOINT,函数需配llm-gateway.executescope;用 OpenAI SDK 直连时补defaultHeaders。
错误与边界
- 401/403:认证方式或 scope 不对(检查四种认证形态与 Key 权限)。
- 路由失败/上游错误排查顺序:Provider 已激活 →
allowedCapabilities包含该能力 →supportedModels精确匹配 → 更新后是否refreshProviderCache()。 - Gateway Key 泄露即吊销重建(
updateKeyStatus/ 删除);明文无法二次获取。 - 流式响应按 SSE 逐事件解析,客户端需处理中断与部分内容。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):Provider/Key 管理全集 + 四类执行;执行面也可用「独立 Client +
Authorization: Bearer <GatewayKey>」直连。 - 客户端 SDK(client-sdk/web.md):执行类(chat / messages / embeddings / rerank / 模型查询)与试用 Provider 绑定(trial provider binding);无 Provider/Key 管理。
- Console SDK(console-sdk/nodejs.md):管理面全集 + 用量视图(
getUsage/getUsageModels/getKeyUsage)。 - Java Server / Console SDK 均有
LlmGateway服务。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
执行:Chat Completions(OpenAI 兼容)
createChatCompletion 按请求体 model 路由到活跃 Provider,messages 原样透传;stream: true 走 SSE。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Client, LlmGateway } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // 服务端只存项目 API Key
const llmGateway = new LlmGateway(client);
const chat = await llmGateway.createChatCompletion({
model: 'qwen-max', // 与 Provider 模型清单 / Key allowedModels 精确匹配
messages: [{ role: 'user', content: '用一句话介绍 TablesDB' }],
temperature: 0.2,
maxTokens: 1024,
stream: false // true 时响应为 SSE 分片
});import { Client, LlmGateway } from 'agentbase-web-sdk'; // 前提:用户已登录(Session 认证,不能带 Key)
const llmGateway = new LlmGateway(client);
const chat = await llmGateway.createChatCompletion({
model: 'qwen-max',
messages: [{ role: 'user', content: '用一句话介绍 TablesDB' }]
});import io.agentbase.services.LlmGateway;
LlmGateway llmGateway = new LlmGateway(client); // client 初始化见 server-sdk/java.md
Object chat = llmGateway.createChatCompletion(
"qwen-max", // 与 Provider 模型清单 / Key allowedModels 精确匹配
List.of(Map.of("role", "user", "content", "用一句话介绍 TablesDB")),
0.2, 1024L, false, null, null); // temperature / maxTokens / stream / tools / toolChoicefrom agentbase.services.llm_gateway import LlmGateway
llm_gateway = LlmGateway(client) # 同步调用
chat = llm_gateway.create_chat_completion(
model='qwen-max', # 与 Provider 模型清单 / Key allowedModels 精确匹配
messages=[{'role': 'user', 'content': '用一句话介绍 TablesDB'}],
temperature=0.2,
max_tokens=1024,
stream=False) # True 时响应为 SSE 分片llmGateway := agentbase.NewLlmGateway(cl) // facade 构造器;cl 为已装载项目 API Key / Gateway Key 的 Client
chat, err := llmGateway.CreateChatCompletion("qwen-max", // 与 Provider 模型清单 / Key allowedModels 精确匹配
[]interface{}{map[string]interface{}{"role": "user", "content": "用一句话介绍 TablesDB"}},
llmGateway.WithCreateChatCompletionTemperature(0.2),
llmGateway.WithCreateChatCompletionMaxTokens(1024),
llmGateway.WithCreateChatCompletionStream(false)) // true 时响应为 SSE 分片
_ = chatcurl -sS -X POST "$APPBASE_ENDPOINT/llm-gateway/chat/completions" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"model":"qwen-max","messages":[{"role":"user","content":"用一句话介绍 TablesDB"}],"temperature":0.2}'
# Gateway Key 认证:改用 -H "Authorization: Bearer $LLM_GATEWAY_KEY"(abk_ 凭据,Key 内嵌项目 ID,可省略 X-Appwrite-Project)
# 流式:body 加 "stream":true,响应为 SSE(data: {"choices":[{"delta":{...}}]} 分片,以 data: [DONE] 结束)执行:Embeddings / Rerank / Messages
Embeddings、Rerank 走 OpenAI 兼容形态;createMessage 为 Anthropic Messages 形态。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
await llmGateway.createEmbeddings({
model: 'text-embedding-v3',
input: ['文本'],
dimensions: 1536 // 需与向量 collection 维度一致
});
await llmGateway.createRerank({
model: '<rerank-model>',
query: 'q',
documents: ['d1', 'd2'],
topN: 3
});
// Anthropic 形态:llmGateway.createMessage(...),原样透传 Anthropic Messages 字段
// 可用模型:await llmGateway.listModels();// Web SDK 同一执行面子集:embeddings / rerank / messages / 模型查询
await llmGateway.createEmbeddings({ model: 'text-embedding-v3', input: ['文本'] });
await llmGateway.createRerank({ model: '<rerank-model>', query: 'q', documents: ['d1', 'd2'], topN: 3 });// Java 面无 dimensions 参数;createRerank(model, query, documents, topN, returnDocuments)
llmGateway.createEmbeddings("text-embedding-v3", List.of("文本"));
llmGateway.createRerank("<rerank-model>", "q", List.of("d1", "d2"), 3L, null);llm_gateway.create_embeddings(model='text-embedding-v3', input=['文本']) # Python 面无 dimensions 参数
llm_gateway.create_rerank(model='<rerank-model>', query='q', documents=['d1', 'd2'], top_n=3)
# create_message(...) 为 Anthropic Messages 形态;list_models() 查询可用模型emb, err := llmGateway.CreateEmbeddings("text-embedding-v3", []string{"文本"}) // Go 面无 dimensions 选项
rerank, err := llmGateway.CreateRerank("<rerank-model>", "q", []string{"d1", "d2"},
llmGateway.WithCreateRerankTopN(3))
_ = emb
_ = rerank
// Anthropic 形态:CreateMessage(model, messages, maxTokens, ...),原样透传 Anthropic Messages 字段
// 可用模型:ListModels()curl -sS -X POST "$APPBASE_ENDPOINT/llm-gateway/embeddings" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"model":"text-embedding-v3","input":["文本"]}'
curl -sS -X POST "$APPBASE_ENDPOINT/llm-gateway/rerank" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"model":"<rerank-model>","query":"q","documents":["d1","d2"]}'
# Anthropic Messages:POST /llm-gateway/messages;模型清单:GET /llm-gateway/modelsProvider 管理(仅服务端 / Console)
接上游 Provider(providerType: 'openai' | 'anthropic' | 'dashscope'),按 priority 升序路由与 failover;批量变更后 refreshProviderCache() 让路由立即生效。Web SDK 无管理面。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { ID, ProviderType, LlmGateway } from 'agentbase-node-sdk';
const controlGateway = new LlmGateway(client); // 管理面必须用项目 API Key(providers.write)
await controlGateway.createProvider({
providerId: ID.unique(),
connectionName: 'reviewed-upstream',
providerType: ProviderType.Openai,
baseUrl: '<upstream-base-url>',
apiKey: process.env.LLM_PROVIDER_API_KEY, // 加密存储,响应只回 apiKeySet 布尔
defaultModel: 'qwen-max',
supportedModels: ['qwen-max', 'text-embedding-v3'] // 与请求 model 精确匹配;["*"] 放行任意
});
await controlGateway.refreshProviderCache(); // 批量变更后刷新路由缓存import io.agentbase.ID;
import io.agentbase.enums.ProviderType;
import io.agentbase.services.LlmGateway;
LlmGateway controlGateway = new LlmGateway(client); // 管理面必须用项目 API Key(providers.write)
controlGateway.createProvider(ID.unique(), "reviewed-upstream",
ProviderType.OPENAI, "<upstream-base-url>",
System.getenv("LLM_PROVIDER_API_KEY"), "qwen-max",
null, List.of("qwen-max", "text-embedding-v3"), // allowedCapabilities, supportedModels(["*"] 放行任意)
null, null, null, null, // chat/embedding/rerank/vlm 模型清单
null, null, null, // chatCompletionsPath / embeddingsPath / rerankPath
null, null, null, null, null, null, null, null); // description / isDefault / isActive / timeoutMs / maxRetries / priority / maxInputTokens / allowByok
controlGateway.refreshProviderCache(); // 批量变更后刷新路由缓存import os
from agentbase.id import ID
control_gateway = LlmGateway(client) # 管理面必须用项目 API Key(providers.write)
control_gateway.create_provider(
provider_id=ID.unique(),
connection_name='reviewed-upstream',
provider_type='openai', # 'openai' | 'anthropic' | 'dashscope'
base_url='<upstream-base-url>',
api_key=os.environ['LLM_PROVIDER_API_KEY'], # 加密存储,响应只回 api_key_set
default_model='qwen-max',
supported_models=['qwen-max', 'text-embedding-v3']) # 精确匹配请求 model;['*'] 放行任意
control_gateway.refresh_provider_cache() # 批量变更后刷新路由缓存controlGateway := agentbase.NewLlmGateway(cl) // 管理面必须用项目 API Key(providers.write)
_, err := controlGateway.CreateProvider(id.Unique(), "reviewed-upstream", "openai", // openai | anthropic | dashscope
"<upstream-base-url>",
controlGateway.WithCreateProviderApiKey(os.Getenv("LLM_PROVIDER_API_KEY")), // 加密存储,响应只回 apiKeySet
controlGateway.WithCreateProviderDefaultModel("qwen-max"),
controlGateway.WithCreateProviderSupportedModels([]string{"qwen-max", "text-embedding-v3"})) // ["*"] 放行任意
_, err = controlGateway.RefreshProviderCache() // 批量变更后刷新路由缓存curl -sS -X POST "$APPBASE_ENDPOINT/llm-gateway/providers" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"providerId":"openai-prod","connectionName":"reviewed-upstream","providerType":"openai","baseUrl":"<upstream-base-url>","apiKey":"<upstream-key>","defaultModel":"qwen-max","supportedModels":["qwen-max","text-embedding-v3"]}'
# 列表:GET /llm-gateway/providers;更新:PATCH .../providers/{providerId};删除:DELETE .../providers/{providerId}
# 变更后刷新路由:POST /llm-gateway/providers/cache/refresh;健康:GET .../providers/{providerId}/health;上游模型发现:GET .../providers/{providerId}/modelsGateway Key 管理
子密钥只能调执行面端点,受 allowedModels / 预算 / 限流约束;明文只在创建响应出现一次,之后只回 keyPrefix。Web SDK 无管理面,本卡不设 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const issued = await controlGateway.createKey({
keyId: ID.unique(),
name: 'frontend',
allowedModels: ['qwen-max'], // 与请求 model 精确匹配,不匹配报 Model not allowed
monthlyTokenBudget: 1000000,
rateLimit: 60 // 每分钟请求数;null 用项目默认
});
// issued.key 明文只在本次响应出现一次:立即写入受控 secret store,不能进前端或日志
await controlGateway.listKeys(); // keyPrefix / 用量元数据,永不返回明文import io.agentbase.ID;
controlGateway.createKey(ID.unique(), "frontend", null,
List.of("qwen-max"), // 精确匹配请求 model,不匹配报 Model not allowed
1000000L, 60L, null); // monthlyTokenBudget / rateLimit(null 用项目默认)/ expiresAt
// 明文 key 只在创建响应出现一次:立即写入受控 secret store,不能进前端或日志
controlGateway.listKeys(); // keyPrefix / 用量元数据,永不返回明文control_gateway.create_key(
key_id=ID.unique(),
name='frontend',
allowed_models=['qwen-max'], # 精确匹配请求 model,不匹配报 Model not allowed
monthly_token_budget=1_000_000,
rate_limit=60) # 每分钟请求数;None 用项目默认
# 明文 key 只在创建响应出现一次:立即写入受控 secret store,不能进前端或日志
control_gateway.list_keys() # keyPrefix / 用量元数据,永不返回明文_, err := controlGateway.CreateKey(id.Unique(), "frontend",
controlGateway.WithCreateKeyAllowedModels([]string{"qwen-max"}), // 精确匹配请求 model,不匹配报 Model not allowed
controlGateway.WithCreateKeyMonthlyTokenBudget(1_000_000),
controlGateway.WithCreateKeyRateLimit(60)) // 每分钟请求数;零值用项目默认
// 明文 key 只在创建响应出现一次:立即写入受控 secret store,不能进前端或日志
_, err = controlGateway.ListKeys() // keyPrefix / 用量元数据,永不返回明文curl -sS -X POST "$APPBASE_ENDPOINT/llm-gateway/keys" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"keyId":"key_frontend","name":"frontend","allowedModels":["qwen-max"],"monthlyTokenBudget":1000000,"rateLimit":60}'
# 响应含一次性明文 key;列表 GET /llm-gateway/keys;启停/改配 PATCH .../keys/{keyId};吊销 DELETE .../keys/{keyId}用量统计(Console 专有)
Chat 请求数、输入/输出/总 token、Embedding/Rerank token 与按模型聚合——仅 Console SDK 提供,API 参考未提供项目级用量 REST 端点。
- Console(Node)
import { Client, LlmGateway } from 'agentbase-console-sdk';
// 项目资源面 client(sdk.forProject 自动 setProject + setMode('admin'))初始化见 console-sdk/nodejs.md
const llmGateway = new LlmGateway(client);
await llmGateway.getUsage({ startDate: '<ISO>', endDate: '<ISO>' }); // 请求与 token 总量
await llmGateway.getUsageModels(); // 按模型聚合
await llmGateway.getKeyUsage({ startDate: '<ISO>', endDate: '<ISO>', period: '1d' }); // period: '1h' | '1d'示例指引
- JavaScript(Node 执行 + Console 管理):examples/javascript.md
- Java:examples/java.md
事实源
skills/ob-agentbase/references/llm-gateway.md- appbase v2.10.0(tag v2.10.0,peeled
0a5d23f9…);v2.9.0(peeledebae9540…;预置目录app/config/llm_gateway_provider_presets.php) - agentbase-sdks v2.10.0 specs(
packages/sdks/server-nodejs/src/services/llm-gateway.ts:2.9.0listProviderPresets、provider +modelMetadata、model +metadata;2.10.0 方法面无新增) - agentbase-sdks v2.7.0 specs(
packages/sdks/server-nodejs/src/services/llm-gateway.ts、packages/sdks/console-web/src/services/llm-gateway.ts方法面)