AgentbaseDocs
文档目录

模型(LLM Gateway)

模型(LLM Gateway) 是 Agentbase v2.10.0 项目访问大语言模型、向量嵌入模型、重排模型与多模态视觉模型的统一底座入口。通过控制台左侧导航栏的 模型(Models) 页面,研发与运维团队可以集中管理模型供应商(Provider)连接凭据、从内置厂商预设目录一键导入模型参数、执行逐模型健康检查、签发受限网关密钥(Gateway Key),并为项目内的知识库、记忆中心、智能体工作台与可观测性评估提供开箱即用的模型算力支撑。


功能概述

在企业级 AI 应用开发中,直接将上游大模型厂商(如阿里云百炼 DashScope、OpenAI、Anthropic 或私有化部署的 vLLM/Ollama)的原始 API Key 分发给各个微服务或前端客户端,会带来严重的密钥泄露风险、超时重试不一致以及用量账单无法按项目归集等痛点。

Agentbase 的 模型(LLM Gateway) 通过三个核心功能页签解决上述问题:

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。


核心概念与架构

LLM Gateway 路由与算力供给架构

flowchart LR
    subgraph Callers["调用方(外部应用与平台内部引擎)"]
        ExtApp["外部业务应用\n(网关密钥: gw-key-support-bot)"]
        KBEngine["知识库引擎\n(kb_enterprise_support)"]
        MemEngine["记忆中心\n(Shared V2 Memory)"]
        AgentWB["智能体工作台\n(Agent Runtime)"]
    end

    subgraph LLMGateway["模型(LLM Gateway)核心处理流水线"]
        AuthRate["身份鉴权与限流器\n(白名单校验 / RPM / 月度 Token 预算)"]
        Catalog["模型目录与参数解析器\n(24 厂商预设 / 313 模型规格表)"]
        Router["多级模型路由器\n(显式连接 -> 体验模型 -> 默认 Provider 优先级)"]
        Health["健康探测与故障转移\n(Health Check: HEALTHY / 自动重试)"]
    end

    subgraph DashScopeProd["已注册提供商: dashscope-prod"]
        Endpoint["Base URL:\nhttps://dashscope.aliyuncs.com/compatible-mode/v1"]
        Models["已启用模型矩阵:\n• Chat: qwen-plus, qwen-turbo\n• Embedding: text-embedding-v3 (1024维)\n• Rerank: qwen3.7-text-rerank\n• Vision: qwen-vl-max"]
    end

    ExtApp -->|/v1/ai/chat/completions\n/v1/ai/embeddings\n/v1/ai/rerank| AuthRate
    KBEngine & MemEngine & AgentWB -->|内部受信任算力调用| Catalog
    AuthRate --> Catalog --> Router --> Health --> Endpoint --> Models

核心概念说明表

核心概念英文标识详细说明
模型提供商连接Provider项目与上游大模型推理服务之间的加密连接实例(如 dashscope-prod)。包含协议类型、Base URL、加密存储的 API Key、启用的能力集合及模型参数表。
厂商预设目录Provider Preset Catalog平台内置的 24 个主流厂商(含通义千问 DashScope、火山方舟、DeepSeek、OpenAI、Anthropic、vLLM 等)与 313 个标准模型模板。选择预设后可一键导入模型的上下文窗口、最大输出与向量维度。
模型能力分类Capabilities分为四类标准能力:chat(对话与文本生成)、embedding(文本与多模态向量化)、rerank(召回结果语义重排)、vlm(视觉图片理解)。下游模块按能力标签过滤可选模型。
按模型参数Model Parameters绑定在具体模型条目上的精细规格参数,包括 contextWindow(上下文窗口)、maxOutputTokens(最大输出 Token)、embeddingDimension(向量维度,如 1024)、maxInputTokens(最大嵌入输入 Token)等。
网关密钥Gateway Key格式为 abk_... 的项目级推理专用密钥(如 gw-key-support-bot)。自带项目路由上下文,调用时无需额外传递 X-Appwrite-Project 请求头。
平台体验模型Trial Model Binding由平台管理员全局配置并授权给项目试用的受管模型。项目成员可在不接触底层供应商密钥的情况下直接选用体验模型完成原型验证。

角色、入口与关联关系

角色权限要求

操作项Owner / AdminDeveloper只读成员 / 访客
查看已注册 Provider 列表、模型目录与健康状态支持支持支持
新增、编辑、删除 Provider 连接或更新上游 API Key支持仅限授权开发者不支持
触发模型发现(Discover)与健康探测(Health Check)支持支持不支持
创建、编辑限额或吊销网关密钥(Gateway Key)支持仅限授权开发者不支持
查看项目模型调用量与 Token 统计报表支持支持支持

控制台入口与下游模块映射


功能详解与操作指南

一、通过厂商预设注册生产级提供商(dashscope-prod)

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

操作步骤

配置字段参数名标杆配置值字段说明与校验规则
连接名称namedashscope-prod项目内唯一标识,建议使用“厂商-环境”命名规范
协议类型providerTypeopenai / dashscope预设自动匹配 OpenAI 兼容协议与百炼原生扩展接口
服务地址(Base URL)baseUrlhttps://dashscope.aliyuncs.com/compatible-mode/v1预设自动填充;服务端强制执行 URL/DNS 安全策略校验,禁止指向内网回环或元数据敏感地址
API KeyapiKey<DASHSCOPE_API_KEY>阿里云百炼 API 密钥;落库时采用 AES-GCM 加密存储,任何读取接口均不回显明文
允许能力enabledCapabilities["chat", "embedding", "rerank", "vlm"]勾选该连接对外暴露的模型能力类别
默认主模型defaultModelqwen-plus当调用方未显式指定模型或平台内部任务请求默认 Chat 模型时使用的模型
对话模型列表chatModelsqwen-plus, qwen-turbo供智能体对话、知识库合成回答、图谱构建与记忆抽取调用
向量模型列表embeddingModelstext-embedding-v3供知识库文档分块嵌入与记忆向量化调用
重排模型列表rerankModelsqwen3.7-text-rerank供知识库多路召回结果重排(Rerank)调用
视觉模型列表vlmModelsqwen-vl-max供知识库图片理解(Image Understanding)与多模态解析调用
超时时间(秒)timeoutSeconds120单次上游 HTTP 推理请求超时阈值,默认 120 秒
最大重试次数maxRetries2遇到瞬时网络抖动或 502/503/504 时的自动重试次数
路由优先级priority10数值越小优先级越高,用于跨 Provider 同名模型故障转移排序
设为默认连接isDefaulttrue(开启)标记为当前项目的默认模型供应商连接
模型标识能力类型上下文窗口 (contextWindow)最大输出 (maxOutputTokens)向量维度 (embeddingDimension)最大嵌入输入 (maxInputTokens)工具调用 (supportsTools)
qwen-pluschat131072 (128K)8192--true
qwen-turbochat131072 (128K)8192--true
text-embedding-v3embedding--10248192-
qwen3.7-text-rerankrerank32768--4000-
qwen-vl-maxvlm / chat327684096--true

二、执行模型发现与健康探测(Health Probe)

提供商创建完成后,建议立即验证上游连通性与各能力端点的可用性:


三、签发与管理网关密钥(gw-key-support-bot)

为使外部业务服务安全调用项目内的模型能力,需在 网关密钥(Keys) 页签签发受限密钥:


四、通过 OpenAI / Anthropic 兼容端点调用模型验证

签发 abk_ 网关密钥后,业务应用可直接使用标准 OpenAI SDK、Anthropic SDK 或原生 HTTP 请求访问以下四类执行端点:

1. 对话补全(Chat Completions:POST /v1/ai/chat/completions)

curl -X POST "https://appbuild.oceanbase.com/v1/ai/chat/completions" \
  -H "Authorization: Bearer <APPBASE_GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus",
    "messages": [
      {"role": "system", "content": "你是企业智能客服与知识中台助手。"},
      {"role": "user", "content": "如何排查 OceanBase 向量索引构建超时?"}
    ],
    "stream": false,
    "temperature": 0.3
  }'

2. 文本向量化(Embeddings:POST /v1/ai/embeddings)

curl -X POST "https://appbuild.oceanbase.com/v1/ai/embeddings" \
  -H "Authorization: Bearer <APPBASE_GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-v3",
    "input": [
      "OceanBase 分布式事务与向量索引排障指南",
      "AI 网关模型路由与限流计费规范"
    ],
    "dimensions": 1024
  }'

3. 语义重排(Rerank:POST /v1/ai/rerank)

curl -X POST "https://appbuild.oceanbase.com/v1/ai/rerank" \
  -H "Authorization: Bearer <APPBASE_GATEWAY_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-text-rerank",
    "query": "向量索引内存不足报错 4013 怎么处理?",
    "documents": [
      "当出现 OB_ALLOCATE_MEMORY_FAILED (-4013) 时,需检查 ob_vector_memory_limit_percentage 参数配置。",
      "智能客服工单流转遵循一线坐席初审、二线专家复核的标准作业程序(SOP)。"
    ],
    "top_n": 2
  }'

4. 查询项目可用模型目录(Models:GET /v1/ai/models)

curl -X GET "https://appbuild.oceanbase.com/v1/ai/models" \
  -H "Authorization: Bearer <APPBASE_GATEWAY_KEY>"

验证结果:


常见问题与排障

Q1:添加阿里云百炼(DashScope)连接时,Base URL 应该填写哪个地址?为什么 Rerank 模型也能正常工作?

在使用内置 通义千问(DashScope) 厂商预设时,推荐将 Base URL 保持为默认的 https://dashscope.aliyuncs.com/compatible-mode/v1。Agentbase 的 DashScope 适配器会自动处理协议路由:对于 qwen-plus、qwen-turbo、text-embedding-v3、qwen-vl-max 走 OpenAI 兼容路径,而对于 qwen3.7-text-rerank 等重排模型,网关底层会自动对齐百炼原生 Rerank 协议端点并统一返回标准化的排序结构,调用方无需关心底层差异。

Q2:知识库摄取长文档时提示 Embedding 输入超限(Input length exceeds maximum allowed tokens),如何调整?

在 模型 -> 模型提供商 中编辑 dashscope-prod,展开 按模型参数(Model Parameters) 找到 text-embedding-v3,检查其 最大输入 Token(Max Input Tokens) 配置(text-embedding-v3 支持最高 8192 Tokens)。同时,在知识库的分块配置(Chunking Parser)中,建议将 chunkTokenNum 设置在 512~1024 之间,确保单个分块加上标题前缀后远低于嵌入模型的输入上限。

Q3:网关密钥(abk_...)可以用来调用创建知识库或修改 Provider 的管理接口吗?

不可以。 网关密钥遵循严格的最小权限原则,仅被授权访问 /v1/ai/* 模型执行端点(Chat Completions、Embeddings、Rerank、Anthropic Messages 与模型列表查询)。任何针对 Provider、Gateway Key、知识库或数据库的增删改管理操作,均必须使用项目在 总览 -> API Keys 中签发的 Server API Key 或控制台管理员会话。

Q4:同一个模型名称在多个 Provider 中都存在时,LLM Gateway 如何决定路由到哪个连接?

如果在请求中未显式指定连接标识,LLM Gateway 会遵循以下自动路由顺序:


相关文档