AgentbaseDocs
文档目录

什么是 Agentbase

Agentbase 是面向企业级 AI 原生应用与智能体(Agent)工程化落地的一站式后端与智能基础设施平台。平台以高可靠的应用后端能力(身份认证、关系与文档数据库、对象存储、Serverless 云函数、消息通知、站点托管与多模态内容安全审核)为底座,深度融合企业级 Agent 所需的大模型网关(LLM Gateway)、统一 AI 网关(AI Gateway)、富文档混合检索知识库(Knowledge Base 与领域词库 Lexicon)、长期记忆与技能自进化引擎(Memory & Context Dreaming)、智能体运行工作台(Agent Runtime Workbench)以及全链路智能体可观测性(AgentOps / Observability)。本手册对应 Agentbase 2.10.0。

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

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

功能概述

在企业落地智能客服、知识助手、研发 Copilot 与自动化业务代理的过程中,工程团队通常面临“应用后端设施”与“AI 原生技术栈”割裂的痛点:一方面需要自行拼装用户鉴权、业务工单库、多租户权限、对象存储与异步任务队列;另一方面又需要独立维护模型路由网关、RAG 向量解析管线、同义词/停用词干预词典、长短期会话记忆以及 OpenTelemetry 轨迹评估系统。多套系统的鉴权体系、租户隔离边界与计量计费口径无法对齐,导致研发周期漫长、线上排障困难。

Agentbase 将传统 BaaS(Backend-as-a-Service)与 Agent Infra(智能体基础设施)收敛于统一的账号 → 组织(Organization) → 项目(Project)治理模型之下。以典型生产场景“企业智能客服与知识中台”(项目 ID:enterprise-ai-hub-210,归属组织:Agentbase 企业智能中台 69c6d1aa00062e6bb60)为例,企业只需在单个 Project 空间内即可完成以下全栈闭环:

能力域核心模块解决的核心业务问题生产级特性亮点
治理与底座账号中心、组织管理、项目总览、限额与配额、项目设置多团队研发协同、多环境隔离、API 凭据授权与成本核算三级 UTC 日聚合计量、15 种客户端平台来源校验、项目数据库/存储独立只读封禁开关
应用后端(Build)Auth 认证、Databases 数据库、Storage 存储、Functions 函数、Sites 站点、Messaging 消息、Moderation 内容审核应用端到端用户体系、关系/JSON 数据持久化、文件托管、事件驱动计算与合规风控OceanBase Shared V2 高性能表模式、Schema 版本回滚、SQL Proxy、Java 17 预构建 JAR 部署、多模态同步/异步内容审核
模型与网关(AI)LLM Gateway(模型)、AI Gateway(统一 AI 网关)多模型供应商凭据托管、主备容灾切换、语义缓存加速、提示词护栏与配额限流DashScope 等厂商目录一键导入、逻辑模型路由、语义缓存命中分析、按 Key 月度 Token 预算管控
知识与记忆(AI)Knowledge Base(知识库)、词库(Lexicon)、Memory(记忆)、上下文(PowerContext)复杂文档切片入库、专有名词召回纠偏、多跳知识推理、跨会话个性化记忆与技能进化向量+全文混合检索、同义词/停用词热干预、GraphRAG/RAPTOR/Wiki 索引、4 类可发布记忆 Pipeline、图像/PDF 多模态记忆
运行与运维(AgentOps)智能体工作台(Agent Runtime)、智能体运维(Observability)智能体快速装配验证、线上对话轨迹回放、低分根因诊断、RAG 解析与索引质量量化评测项目级工作台配置持久化、OpenTelemetry 原生接入、内置 GraphRAG/RAPTOR/Wiki 索引质量评估模板与独立模型复核

核心概念与架构

Agentbase 采用控制面(Console Plane)与数据面(Data Plane)分离、传统应用后端与 AI 引擎同源隔离的分层架构。所有资源严格挂载于 Account(账号) → Organization(组织) → Project(项目) 三级资源树下,以 Project 作为数据隔离、密钥鉴权、服务开关、表模式(JsonTable / Shared V2)与计量配额的最小完备边界。

flowchart TB
    subgraph ClientAndCaller["接入层:客户端与服务端调用方"]
        WebApp["Web / 移动端应用<br/>(Web SDK / 已登记 Platform)"]
        BackendSvc["企业后端与外部 Agent<br/>(Server SDK / REST API / API Key)"]
        ConsoleUI["管理控制台浏览器<br/>(Console SPA / 开发者会话)"]
    end

    subgraph GovernanceLayer["治理与网关层(Project 边界:enterprise-ai-hub-210)"]
        AuthGuard["双平面鉴权与安全门禁<br/>Console Session / Server API Key / Client JWT"]
        ServiceSwitch["项目服务开关与只读栅栏<br/>Services Toggle / DB & Storage Read-Only"]
        AIGateway["AI 网关与模型路由<br/>LLM Gateway (dashscope-prod) / AI Gateway (lm-enterprise-chat)"]
    end

    subgraph CoreServices["核心服务层"]
        subgraph AppBackend["应用后端域(Build)"]
            AuthSvc["Auth 认证与团队"]
            DBSvc["Databases 数据库<br/>(enterprise_biz_db / customer_tickets)"]
            StorageSvc["Storage 对象存储<br/>(kb_enterprise_docs)"]
            FuncSite["Functions 函数 & Sites 站点<br/>(ACS 云沙箱 / Java 17 / Node)"]
            ModMsg["Moderation 审核 & Messaging 消息"]
        end

        subgraph AIEngine["AI 原生引擎域(AI & AgentOps)"]
            AgentWB["智能体工作台<br/>(Agent Runtime Workbench)"]
            KBSvc["知识库与词库<br/>(kb_enterprise_support + GraphRAG/Wiki/Lexicon)"]
            MemSvc["长期记忆与上下文<br/>(Memory Shared V2 / 画像 / 技能蒸馏)"]
            ObsSvc["智能体运维 AgentOps<br/>(Traces / 评估模板 / 索引质量评分 / 指标)"]
        end
    end

    subgraph InfraLayer["分布式存储与算力底座"]
        OBCluster["OceanBase 分布式数据库集群<br/>(关系表 / JSON 半结构化 / HNSW 向量索引 / 全文索引)"]
        ObjStore["分布式对象存储与沙箱运行时"]
    end

    ConsoleUI --> AuthGuard
    WebApp --> AuthGuard
    BackendSvc --> AuthGuard
    AuthGuard --> ServiceSwitch
    ServiceSwitch --> AppBackend
    ServiceSwitch --> AIEngine
    AgentWB --> AIGateway
    AgentWB --> KBSvc
    AgentWB --> MemSvc
    KBSvc --> AIGateway
    KBSvc --> StorageSvc
    MemSvc --> AIGateway
    AppBackend --> OBCluster
    AppBackend --> ObjStore
    AIEngine --> OBCluster
    AIEngine --> ObsSvc

核心架构组件表

架构层次核心概念标识与示例(生产实景)架构职责与工程约束
组织层(Organization)团队与计费容器Agentbase 企业智能中台(69c6d1aa00062e6bb60)承载多个 Project,统一管理团队成员角色(owner、admin、developer、editor、billing、analyst)、30 日聚合用量与不活跃项目清理。
项目层(Project)资源与安全隔离边界企业智能客服与知识中台(enterprise-ai-hub-210)绑定物理区域(Region)与底层表存储模式(如 Shared V2);项目间数据库、存储桶、知识库、记忆空间与 API Key 完全隔离。
模型路由层供应商与逻辑网关dashscope-prod / prod-enterprise-ai-gateway统一收口外部大模型 API Key(掩码保存、不回显),对内为知识库切片向量化、记忆抽取、在线推理与 LLM-as-a-Judge 评估提供标准调用面。
知识与记忆层结构化增强上下文kb_enterprise_support / lex_enterprise_synonyms / Memory结合存储桶原始文档、向量索引、词库同义词扩展与用户长期事实记忆,为智能体组装高召回率、低幻觉的动态 Prompt 上下文。
可观测与评测层AgentOps 闭环质量治理Traces / Observations / Evaluations自动采集或通过 OTLP 接收智能体执行轨迹,提供从分块解析质量、GraphRAG/Wiki 索引产物质量到端到端回复质量的量化评分与根因分析。

角色、入口与关联关系

在日常研发与运维中,不同岗位的团队成员通过 Console 的不同视图协作完成应用交付。理解 Console 角色权限、服务开关以及控制面与数据面的边界,是安全使用 Agentbase 的前提。

1. 组织角色与操作权限矩阵

组织角色适用岗位应用后端与 AI 资源写权限API Key / 凭据管理组织设置与成员治理用量与可观测性查看
Owner平台架构师 / 技术负责人全部读写(含列删除、表模式转换、项目删除)创建、编辑、查看完整 Secret、吊销创建/删除组织、邀请/移除成员、清理不活跃项目账号、组织、项目三级全量视图
Admin研发主管 / 运维负责人全部读写(不含仅限 Owner 的破坏性开关)创建、编辑、查看授权 Secret、吊销修改组织设置、邀请成员(不可删除组织)组织与项目全量视图
Developer后端工程师 / AI 算法工程师读写数据库、存储、函数、知识库、记忆、网关与评估创建与管理项目 API Key / Dev Key只读查看成员列表组织与项目全量视图
Editor知识运营 / Prompt 工程师维护表数据、知识库文档、词库词条、评测数据集按授权范围使用只读查看成员列表项目级业务与观测视图
Billing财务与采购专员只读(无权修改业务配置或触发构建)无权创建或查看 Secret管理账单、发票与订阅计划组织与项目用量计量视图
Analyst数据分析师 / 质检员只读(无权修改业务资源)无权创建或查看 Secret只读查看观测轨迹、评估报告与用量统计

2. 产品能力边界与四条核心准则

功能详解与操作指南

本节以企业新接入团队的视角,说明如何通过 Console 完成平台版本核验、项目全局认知及从基础服务到 AI 模块的标准演进路径。

1. 核验实例服务版本与控制台入口

在开始项目配置前,建议先确认当前环境的服务端版本并登录控制台:

   curl -fsSL https://appbuild.oceanbase.com/v1/health/version

预期返回 HTTP 200 OK 及 JSON 载荷 {"version":"2.10.0"}。

2. 控制台左侧边栏分区与标准构建流

Agentbase 项目控制台左侧导航栏按照研发演进生命周期划分为三大核心区域,推荐团队遵循以下顺序逐层构建企业智能应用:

构建阶段侧边栏入口名控制台路由后缀关键配置动作与产出物(以 enterprise-ai-hub-210 为例)
第一阶段:项目底座与安全基线Overview / Settings/overview · /settings确认项目表模式为 OceanBase Shared V2;在 Services 中开启 AI Gateway、Knowledge Bases、Memory 等服务;创建最小权限原则的 standard_ API Key。
第二阶段:应用后端构建(Build)Auth / Databases / Storage / Functions / Moderation/auth · /databases · /storage · /functions · /moderation配置终端用户登录方式;创建业务库 enterprise_biz_db 与工单表 customer_tickets(录入 TK-20261022-001 等工单);创建存储桶 kb_enterprise_docs 上传制度文档;开启写路径多模态内容审核。
第三阶段:模型网关与路由治理(AI)模型 / AI 网关/llm-gateway · /ai-gateway在 模型 页从预设目录添加 dashscope-prod(导入 qwen-plus、text-embedding-v3、qwen3.7-text-rerank、qwen-vl-max);在 AI 网关 页创建 prod-enterprise-ai-gateway,绑定逻辑模型 lm-enterprise-chat、安全护栏 gp-enterprise-safety 与语义缓存 cp-semantic-cache。
第四阶段:知识工程与长期记忆(AI)知识库 / 词库 / 记忆 / 上下文/knowledge-base · /memory · /powercontext创建同义词库 lex_enterprise_synonyms 与停用词库 lex_support_stopwords;创建知识库 kb_enterprise_support,上传 4 份企业核心 Markdown 文档并构建 GraphRAG、RAPTOR 与 10 页编译态 Wiki;初始化 Shared V2 记忆服务,配置四类记忆 Pipeline 与经验技能蒸馏。
第五阶段:智能体联调与 AgentOps智能体工作台 / 智能体运维 / Trace logs/agent-runtime · /observability · /logs在 智能体工作台 绑定 qwen-plus 与 kb_enterprise_support 进行多轮对话实测;在 智能体运维(AgentOps) 中查看 Trace 瀑布流,运行知识库解析评估与知识索引质量评估任务。

3. 2.10.0 核心特性全景核对表

为了帮助从早期版本升级或首次评估平台的架构师快速掌握当前基线能力,下表汇总了 Agentbase 2.10.0 的关键生产能力及对应的操作验证方式:

特性名称所属模块核心配置项或接口标识控制台验证结果
知识索引质量独立评估智能体运维 → 评估Built-in 模板:GraphRAG / LLM Wiki / RAPTOR Index Quality;默认每能力分层抽样 30 条生成 0~1 能力级质量分,经独立模型复核后支持按 kind=index 下钻查看单条产物规则与模型评分明细
文档层级标签与子产品过滤知识库 → 文档 / 检索测试documentTag({subProductId}_{sectionCode}_{fileKey})与独立 subProductId 字段文档列表支持标签树/平铺切换,单库与跨库检索支持按 subProductId 与 metadataFilter 精准收窄召回范围
干预词库(Lexicon)闭环知识库 → 词库同义词词典(双向等价/单向扩展)与停用词词典绑定至知识库或智能体工作台后,混合检索自动完成业务黑话扩展与高频噪音词剔除
Memory 四类 Pipeline 与技能二次确认记忆 → 配置 / 经验与技能记忆、画像、经验与技能、遗忘四类 Pipeline;evolution.requireConfirmation支持 Pipeline 草稿保存、真实样例验证、发布与回滚;技能蒸馏支持候选版本 Diff 对比、人工编辑与批准回滚
Java 17 预构建 JAR 函数部署函数 → 部署Runtime java-17.0 + artifactMode=java-jar(manifest 声明 Main-Class)无需上传源码压缩包重新编译,上传符合有效大小上限的预构建 JAR(默认 100 MB,另受套餐上限约束);等待部署 ready 后确认激活和执行结果
项目数据库与存储独立只读栅栏限额与配额(平台治理)databaseReadOnly / storageReadOnly开启期间拒绝对应域写入(返回 project_database_read_only 或 project_storage_read_only),保障迁移与故障隔离期数据零脏写

2.10.0 值得关注的能力

常见问题与排障

Q1:为什么在控制台左侧导航栏看不到“AI 网关(AI Gateway)”、“消息(Messaging)”或“站点(Sites)”入口?

原因与排查步骤:

Q2:调用知识库高阶索引或 Memory 接口时返回 HTTP 412 Precondition Failed 是什么原因?

原因与排查步骤: HTTP 412 在 Agentbase 中明确代表前置条件或部署级能力(Capability)未满足,而非普通的参数错误(400)或权限不足(401/403)。常见触发场景包括:

Q3:为什么服务端脚本使用 API Key 调用接口返回 401 general_unauthorized_scope?

原因与排查步骤: Agentbase 的项目 API Key 严格遵循最小权限(Least Privilege)原则。创建 API Key 时若未勾选目标接口所属的 Scope(例如调用用户查询未勾选 users.read,或调用知识库检索未勾选知识库相关 Scope),服务端将直接拦截并返回 general_unauthorized_scope。请进入项目 Overview → Integrations → API keys,点开对应 Key 详情页,在 Scopes 折叠面板中补齐所需权限后保存,无需更换 Key Secret 即可立即生效。

Q4:项目设置中关闭某个 Service 开关后,已有的数据会被清空吗?后台服务端还能访问吗?

原因与排查步骤: 不会删除任何数据,且不影响服务端 API Key 访问。项目 Settings → Services 中的开关仅控制客户端访问面(Client SDK / 浏览器与移动端直接携带用户 Session 访问)的可达性。关闭某项服务后,来自前端应用的直接请求会被拒绝,但后端微服务携带有效 Server API Key 发起的调用依然正常执行,底层数据库表、存储桶文件与知识库索引完好保留。

相关文档

为方便查阅全站功能点,以下列出本手册(zh-CN)全部章节的直达索引: