agentbase-docs

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 即使外观相同也不可互换;不提供旧资源迁移或无差别别名。

前置

使用骨架

关键参数与返回

错误与边界

SDK 类别差异

各语言调用示例

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

执行:Chat Completions(OpenAI 兼容)

createChatCompletion 按请求体 model 路由到活跃 Provider,messages 原样透传;stream: true 走 SSE。

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 分片
});

执行:Embeddings / Rerank / Messages

Embeddings、Rerank 走 OpenAI 兼容形态;createMessage 为 Anthropic Messages 形态。

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();

Provider 管理(仅服务端 / Console)

接上游 Provider(providerType: 'openai' | 'anthropic' | 'dashscope'),按 priority 升序路由与 failover;批量变更后 refreshProviderCache() 让路由立即生效。Web SDK 无管理面。

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();       // 批量变更后刷新路由缓存

Gateway Key 管理

子密钥只能调执行面端点,受 allowedModels / 预算 / 限流约束;明文只在创建响应出现一次,之后只回 keyPrefix。Web SDK 无管理面,本卡不设 Web 页签。

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 / 用量元数据,永不返回明文

用量统计(Console 专有)

Chat 请求数、输入/输出/总 token、Embedding/Rerank token 与按模型聚合——仅 Console SDK 提供,API 参考未提供项目级用量 REST 端点。

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'

示例指引

事实源