什么是 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 空间内即可完成以下全栈闭环:
- 统一身份与业务数据承载:通过 Auth 管理客服坐席与终端客户身份,使用基于 OceanBase
Shared V2模式的业务数据库enterprise_biz_db(如客户工单表customer_tickets)和存储桶kb_enterprise_docs、agent_multimedia_bucket承载结构化单据与非结构化多媒体的高并发读写。 - 多模型路由与企业级安全护栏:通过模型网关接入通义千问 DashScope 生产供应商(
dashscope-prod,含qwen-plus、qwen-turbo、text-embedding-v3、qwen3.7-text-rerank、qwen-vl-max),并经由 AI 网关prod-enterprise-ai-gateway(gw_7194685489feb1e169548619)配置逻辑模型路由lm-enterprise-chat、安全护栏gp-enterprise-safety与语义缓存策略cp-semantic-cache。 - 混合检索 RAG 与高阶知识编译:在知识库
kb_enterprise_support中摄取架构白皮书、客服 SOP 与排障手册,绑定同义词词典lex_enterprise_synonyms与停用词词典lex_support_stopwords,按需开启 GraphRAG 知识图谱、RAPTOR 层次聚类摘要与 LLM Wiki 编译页面。 - 长期记忆提取与技能蒸馏:基于
Shared V2引擎为终端用户(如user_zhangwei_001、user_lina_002)提取跨会话事实记忆与用户画像,并异步执行 Context Dreaming 上下文聚合及经验技能蒸馏(Experience/Skill Distillation)。 - 工作台联调与全链路可观测(AgentOps):在智能体工作台一键绑定主对话模型
qwen-plus、企业知识库与干预词库进行流式调试,同时在 AgentOps 中心追踪每一笔请求的 Span 瀑布流、Token 成本、解析分块质量与知识索引质量评分。
| 能力域 | 核心模块 | 解决的核心业务问题 | 生产级特性亮点 |
|---|---|---|---|
| 治理与底座 | 账号中心、组织管理、项目总览、限额与配额、项目设置 | 多团队研发协同、多环境隔离、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. 产品能力边界与四条核心准则
- 准则一:部署级能力(Capability)与项目开关分层生效。知识库高阶索引(GraphRAG / RAPTOR / Wiki)、统一 AI 网关、站点托管(
_APP_SITES_ENABLED)与长期记忆受底层部署环境变量与算力组件控制。若当前实例未部署某项能力,接口会稳定返回 HTTP412 Precondition Failed,而不会伪装为“项目内已关闭”;版本升级本身不会自动开启默认关闭的部署级开关。 - 准则二:控制台可见性(Console 路由)不等于数据面已就绪。左侧边栏展示某个模块入口仅代表 Console 前端路由与角色权限放行;实际业务请求能否成功,取决于项目 Settings → Services 开关、资源自身的
enabled/active状态、绑定的模型 Provider 连通性以及存储模式(如 Memory 强依赖项目处于Shared V2表模式)。 - 准则三:开发者身份(Console Account)与终端用户身份(Project Auth User)严格物理隔离。登录
/console/login的账号用于管理组织与项目基础设施;项目 Auth 模块下的用户(如user_zhangwei_001)是企业业务系统的终端客户或客服人员。两套会话 Cookie、JWT 与权限选择器彼此独立,严禁混用。 - 准则四:协议版本与 SDK 响应格式精确协商。目标实例的运行版本可通过公开免鉴权接口
GET /v1/health/version实时核验(当前稳定版本返回{"version":"2.10.0"})。Agentbase 官方自研 SDK(如agentbase-node-sdk@2.10.0、agentbase-web-sdk@2.10.0、agentbase-console-sdk@2.10.0)通过请求头X-AppBase-SDK: true与X-Appwrite-Response-Format: 2.10.0协商 2.10.0 完整响应结构;原生 Appwrite 兼容客户端则受独立版本上限(默认1.9.0)保护。
功能详解与操作指南
本节以企业新接入团队的视角,说明如何通过 Console 完成平台版本核验、项目全局认知及从基础服务到 AI 模块的标准演进路径。
1. 核验实例服务版本与控制台入口
在开始项目配置前,建议先确认当前环境的服务端版本并登录控制台:
- 在终端执行公开健康检查接口(无需任何 API Key):
curl -fsSL https://appbuild.oceanbase.com/v1/health/version预期返回 HTTP 200 OK 及 JSON 载荷 {"version":"2.10.0"}。
- 在浏览器打开控制台地址
https://appbuild.oceanbase.com/console/,使用企业开发者账号完成登录与 MFA 二次验证,在顶部导航栏切换至目标组织Agentbase 企业智能中台(ID:69c6d1aa00062e6bb60),点击进入项目企业智能客服与知识中台(ID:enterprise-ai-hub-210)。 - 进入项目后,默认展示 Overview(项目总览) 页面(如图 1 所示),顶部展示实时连接数、请求趋势、数据库读写吞吐与存储占用摘要;底部 Integrations 区域集中管理已登记的客户端平台(Platforms)、服务端生产密钥(API keys)与开发调试密钥(Dev keys)。
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 值得关注的能力
- 知识库定位与筛选:文档可使用
documentTag和subProductId做精确定位;单库 / 跨库检索、文档列表和 Graph / Wiki 冲突列表支持按标签或子产品过滤。层级标签仍用于目录整理,两者用途不同。见文档与摄取和检索测试。 - 知识索引质量评估:Observability 可分别评估 GraphRAG、RAPTOR 和 LLM Wiki 的索引产物;评估前须已有相应索引结果。见评估与评分。
- 版本化知识库:可基于 READY 版本创建工作副本,封存后发布,并保留受限的回滚目标。见版本管理。
常见问题与排障
Q1:为什么在控制台左侧导航栏看不到“AI 网关(AI Gateway)”、“消息(Messaging)”或“站点(Sites)”入口?
原因与排查步骤:
- AI 网关(AI Gateway):项目级服务开关默认关闭。请具备项目写权限(
owner/admin/developer/editor)的成员前往 Settings → Overview → Services,找到 AI Gateway(统一 AI 网关) 并将其切换为开启状态,刷新后侧边栏即会显示 AI 网关 入口。 - 消息(Messaging):当前版本侧栏默认隐藏该导航项,但底层服务完整可用。可通过浏览器直接访问
/console/project-{region}-{project}/messaging(例如/console/project-default-enterprise-ai-hub-210/messaging)或使用控制台顶部快捷键命令中心直接跳转。 - 站点(Sites):受实例级部署环境变量
_APP_SITES_ENABLED与邮箱白名单双重控制。若当前私有化或预发实例未开启该变量,侧栏会自动隐藏 Sites 入口。
Q2:调用知识库高阶索引或 Memory 接口时返回 HTTP 412 Precondition Failed 是什么原因?
原因与排查步骤: HTTP 412 在 Agentbase 中明确代表前置条件或部署级能力(Capability)未满足,而非普通的参数错误(400)或权限不足(401/403)。常见触发场景包括:
- 项目表模式不匹配:例如尝试在传统
JsonTable模式的项目中初始化 Memory 记忆服务(Memory 强制要求项目采用 OceanBaseShared V2表模式)。请检查项目 Settings → Overview → 项目表模式。 - 未绑定必需的模型路由:例如开启知识库 GraphRAG/Wiki 构建或触发记忆异步提取前,尚未在 模型(LLM Gateway) 中配置可用的 Chat 与 Embedding 模型。
- 实例未部署对应可选组件:联系平台基础设施管理员核对对应 Worker 队列与索引服务是否已启用。
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)全部章节的直达索引:
- 导论与全局参考
- 账号、组织与项目治理
- 身份认证与用户管理(Auth)
- 数据库与数据治理(Databases)
- 应用后端服务(Storage / Functions / Sites / Messaging / Moderation)
- 模型网关与统一 AI 网关(Models & AI Gateway)
- 知识库与词库工程(Knowledge Base & Lexicon)
- 长期记忆与上下文工程(Memory & Context)
- 智能体工作台(Agent Runtime)
- 智能体可观测性与评估(AgentOps / Observability)