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

前置

使用骨架

  1. 接 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)使用。

  2. 签发 Gateway Key:createKey({ keyId, name, description, allowedModels, monthlyTokenBudget, rateLimit, expiresAt });rateLimit 为每分钟请求数(null 用项目默认);isActive: false 立即禁用,删除即吊销。

  3. 执行:

    • 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 查询可用模型。

  4. 用量(Console SDK):getUsage / getUsageModels / getKeyUsage({ startDate, endDate, period: '1h' | '1d' })——Chat 请求数、输入/输出/总 token、Embedding/Rerank token、按模型聚合。

关键参数与返回

错误与边界

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'

示例指引

2.12.0 — Rerank 原生排序指令

rerank 增加可选 instruct;仅支持对应原生排序指令的 DashScope 模型可用,空字符串省略此指令,不把所有提供商视为等价。其它 model/query/documents 和 return_documents 参数沿用原契约。