Docs
文档目录

什么是 Agentbase

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

功能概述

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

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

  1. 统一身份与业务数据承载:通过 Auth 管理客服坐席与终端客户身份,使用基于 OceanBase Shared V2 模式的业务数据库 enterprise_biz_db(如客户工单表 customer_tickets)和存储桶 kb_enterprise_docs、agent_multimedia_bucket 承载结构化单据与非结构化多媒体的高并发读写。

  2. 模型接入与路由:在模型页面接入供应商,并按需在 AI 网关配置工具接入。

  3. 混合检索 RAG 与高阶知识编译:在知识库 kb_enterprise_support 中摄取架构白皮书、客服 SOP 与排障手册,绑定同义词词典 lex_enterprise_synonyms 与停用词词典 lex_support_stopwords,按需开启 GraphRAG 知识图谱、RAPTOR 层次聚类摘要与 LLM Wiki 编译页面。

  4. 长期记忆提取与技能蒸馏:基于 Shared V2 引擎为终端用户(如 user_zhangwei_001、user_lina_002)提取跨会话事实记忆与用户画像,并异步执行 Context Dreaming 上下文聚合及经验技能蒸馏(Experience/Skill Distillation)。

  5. 工作台联调与全链路可观测(AgentOps):在智能体工作台一键绑定主对话模型 qwen-plus、企业知识库与干预词库进行流式调试,同时在 AgentOps 中心追踪每一笔请求的 Span 瀑布流、Token 成本、解析分块质量与知识索引质量评分。

能力域核心模块解决的核心业务问题生产级特性亮点
治理与底座账号中心、组织管理、项目总览、限额与配额、项目设置多团队研发协同、多环境隔离、API 凭据授权与成本核算三级 UTC 日聚合计量、客户端平台登记与适用的浏览器来源检查、项目数据库/存储独立只读封禁开关
应用后端(Build)Auth 认证、Databases 数据库、Storage 存储、Functions 函数、Sites 站点、Messaging 消息、Moderation 内容审核应用端到端用户体系、关系/JSON 数据持久化、文件托管、事件驱动计算与合规风控OceanBase Shared V2 高性能表模式、Schema 版本回滚、SQL Proxy、Java 17 预构建 JAR 部署、多模态同步/异步内容审核
模型与网关(AI)LLM Gateway、AI Gateway模型供应商接入、网关路由与访问管理配置可用模型和凭证
知识与记忆(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)与计量配额的最小完备边界。

核心架构组件表

架构层次核心概念标识与示例(生产实景)架构职责与工程约束
组织层(Organization)团队与计费容器Agentbase 企业智能中台(69c6d1aa00062e6bb60)承载多个 Project,统一管理团队成员角色(owner、admin、developer、editor、billing、analyst)、30 日聚合用量与不活跃项目清理。
项目层(Project)资源与安全隔离边界企业智能客服与知识中台(enterprise-ai-hub-210)绑定物理区域(Region)与底层表存储模式(如 Shared V2);项目间数据库、存储桶、知识库、记忆空间与 API Key 完全隔离。
模型路由层供应商与逻辑网关dashscope-prod统一收口外部大模型 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财务与采购专员默认无 projects.read,自托管时不能仅凭此角色进入项目默认无管理权限组织级 billing.read;功能取决于部署组织用量以实际授权为准
Analyst数据分析师 / 质检员默认无 projects.read,自托管时不能仅凭此角色进入项目默认无管理权限只读查看组织信息项目数据以实际授权为准

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

功能详解与操作指南

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

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

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

  1. 在终端查询目标环境的公开健康接口(无需 API Key)。先将 AGENTBASE_ENDPOINT 环境变量设为你的 Agentbase 服务地址:

    curl -fsSL "$AGENTBASE_ENDPOINT/v1/health/version"

    成功时返回 HTTP 200 OK,其中 version 为该环境的运行版本。

  2. 打开该环境的控制台,登录后选择你的组织和项目。若环境要求额外验证,请按页面提示完成。

  3. 进入项目后,通过侧栏访问项目总览、平台和 API 密钥等页面。新项目可能先显示接入引导,具体内容以当前页面为准。

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

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

构建阶段侧边栏入口名控制台路由后缀关键配置动作与产出物(以 enterprise-ai-hub-210 为例)
第一阶段:项目底座与安全基线概览 / 设置/overview · /settings确认项目表模式为 OceanBase Shared V2;在 服务 中开启 AI Gateway、Knowledge Bases、Memory 等服务;创建最小权限原则的 standard_ API Key。
第二阶段:应用后端构建(Build)认证 / 数据库 / 存储 / 函数 / 内容审核/auth · /databases · /storage · /functions · /moderation配置终端用户登录方式;创建业务库 enterprise_biz_db 与工单表 customer_tickets(录入 TK-20261022-001 等工单);创建存储桶 kb_enterprise_docs 上传制度文档;开启写路径多模态内容审核。
第三阶段:模型网关与路由治理模型 / AI 网关/llm-gateway · /ai-gateway添加模型供应商,按需配置网关实例和工具。
第四阶段:知识工程与长期记忆(AI)知识库 / 词库 / 记忆 / 上下文/knowledge-base · /memory · /powercontext创建同义词库 lex_enterprise_synonyms 与停用词库 lex_support_stopwords;创建知识库 kb_enterprise_support,上传所需文档,并按需构建 GraphRAG、RAPTOR 与 Wiki;初始化 Shared V2 记忆服务,配置四类记忆 Pipeline 与经验技能蒸馏。
第五阶段:智能体联调与 AgentOps智能体工作台 / 智能体运维 / 链路日志/agent-runtime · /observability · /logs在 智能体工作台 绑定 qwen-plus 与 kb_enterprise_support 进行多轮对话实测;在 智能体运维(AgentOps) 中查看 Trace 瀑布流,运行知识库解析评估与知识索引质量评估任务。

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

下表列出 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)”入口?

原因与排查步骤:

  1. AI 网关(AI Gateway):项目级服务开关默认关闭。请具备项目写权限(owner / admin / developer / editor)的成员前往 设置 → 概览 → 服务,找到 AI Gateway(统一 AI 网关) 并将其切换为开启状态,刷新后侧边栏即会显示 AI 网关 入口。

  2. 消息(Messaging):当前版本侧栏默认隐藏该导航项,但底层服务完整可用。可通过浏览器直接访问 /console/project-{region}-{project}/messaging(例如 /console/project-default-enterprise-ai-hub-210/messaging)或使用控制台顶部快捷键命令中心直接跳转。

  3. 站点(Sites):受实例开关与邮箱白名单共同控制。应用代码未设置 _APP_SITES_ENABLED 时默认为 enabled,实际部署可能覆盖;Console 入口还取决于当前用户的白名单状态。

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。请进入项目 概览 → 集成 → API 密钥,点开对应 Key 详情页,在 Scopes 折叠面板中补齐所需权限后保存,无需更换 Key Secret 即可立即生效。

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

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

相关文档

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