前言
本手册是 Agentbase 2.10.0 的全量中文用户手册,面向企业研发架构师、AI 应用开发工程师、知识与数据运营专员以及平台运维管理员,系统阐述如何通过 Agentbase 控制台(Console)完成组织与项目治理、应用后端基础设施构建、大模型网关配置、企业知识库与干预词库建设、长期记忆与技能自进化管理、智能体工作台联调以及全链路 AgentOps 可观测与评估。
功能概述
本手册旨在为企业用户提供一份自包含、可复现、生产可用的产品操作指南。无论是从零搭建一套智能客服与知识中台,还是在既有业务系统之上增量引入混合检索 RAG、长期用户记忆与多模型路由治理,读者均可依据本手册的章节脉络完成端到端配置与线上问题排查。
为了帮助不同技术背景的读者高效获取所需信息,本手册以真实企业生产样板——“企业智能客服与知识中台”(所属组织:Agentbase 企业智能中台 69c6d1aa00062e6bb60,项目 ID:enterprise-ai-hub-210,底层存储模式:OceanBase Shared V2)为主线贯穿全书。手册中的每一项配置参数、界面导航路径、状态流转规则与排障方法均与 Agentbase 服务基线严格对齐。
| 目标读者角色 | 核心职责与关注重点 | 推荐优先阅读章节 | 典型产出物 |
|---|---|---|---|
| 平台架构师 / 组织 Owner | 规划多团队组织架构、项目环境隔离、表存储模式选型、用量配额治理与安全合规基线 | 什么是 Agentbase、核心概念、组织与账号中心、项目设置、限额与配额 | 组织与成员角色矩阵、Shared V2 生产项目、自定义域名與 Webhook 安全策略 |
| 应用后端开发工程师 | 构建用户认证体系、设计业务数据库表与索引、管理存储桶文件、开发云函数与多渠道通知 | 快速开始、项目总览、认证概览、数据库概览、存储、函数、消息 | enterprise_biz_db 业务库、customer_tickets 工单表、Java 17 / Node 云函数、最小权限 API Key |
| AI 算法与智能体工程师 | 接入大模型供应商、配置 AI 网关路由与护栏、调优混合检索与长期记忆 Pipeline、联调智能体工作台 | 模型与 AI 网关概览、LLM Gateway、统一 AI 网关、智能体工作台概览、模型与词库配置、会话与运行、知识库与记忆协同、工具网关与技能包、记忆概览与启用、召回调优与配置 | dashscope-prod 模型目录、prod-enterprise-ai-gateway、项目级智能体工作台、四类记忆 Pipeline 与经验技能蒸馏 |
| 知识工程与质检运营专员 | 上传企业文档与分块治理、维护同义词/停用词词库、构建 Wiki/GraphRAG 索引、执行评测集与根因分析 | 知识库概览、文档摄取与分块管理、Wiki、GraphRAG、RAPTOR 与索引治理、可观测性概览、评估与评分 | kb_enterprise_support 知识库、lex_enterprise_synonyms 词典、10 页编译态 Wiki 与索引质量评估报告 |
核心概念与架构
本手册的章节编排严格映射 Agentbase 的“三级资源治理树 + 双域业务能力面”架构。读者在阅读具体功能页之前,可通过下方架构导图建立全局心智模型:
flowchart LR
subgraph DocTree["全量用户手册阅读脉络(对应 Console 架构层次)"]
direction TB
L1["第一层:导论与全局基线<br/>what-is-agentbase / core-concepts / getting-started / routes / faq"]
L2["第二层:账号、组织与项目治理<br/>account/register-login → organization/org-account → overview/*"]
L3["第三层:应用后端底座(Build 域)<br/>auth/* · databases/* · storage · functions · sites · messaging · moderation"]
L4["第四层:AI 原生基础设施(AI 域)<br/>models-ai-gateway/* · knowledge-base/* · memory/*"]
L5["第五层:智能体运行与可观测闭环(AgentOps 域)<br/>智能体工作台 (/agent-runtime) · observability/*"]
L1 --> L2
L2 --> L3
L2 --> L4
L3 --> L5
L4 --> L5
end手册核心术语与全书统一口径表
| 规范维度 | 术语与标识 | 全书统一说明与工程约束 |
|---|---|---|
| 产品与版本标识 | Agentbase / 2.10.0 | 产品名称统一为 Agentbase;在线实例稳定版本通过 GET /v1/health/version 核验。历史兼容请求头(如 X-Appwrite-Project、X-Appwrite-Key、X-AppBase-SDK)按实际协议原样书写。 |
| 控制台路由路径变量 | {organization}、{region}、{project} | 所有 Console 页面挂载于 /console 基路径下;文档中如 /console/project-{region}-{project}/overview 的路径变量,在实际操作时替换为真实区域(如 default)与项目 ID(如 enterprise-ai-hub-210)。 |
| 安全脱敏变量标记 | <PROJECT_ID>、<APPBASE_API_KEY>、<DASHSCOPE_API_KEY> | 手册严禁出现任何真实私钥、密码或内部凭据;所有命令行与配置示例均采用尖括号变量标记或环境变量引用(如 ${APPBASE_API_KEY})。 |
| 样板工程实体 | enterprise-ai-hub-210 / kb_enterprise_support | 全书跨章节演示统一采用 enterprise-ai-hub-210 项目下的真实资源 ID,确保从模型配置、知识库构建、记忆提取到工作台调试的上下文前后贯通。 |
| 界面语言约定 | 英文原版按钮标签 + 中文释义 | 为确保不同语言偏好下定位零偏差,文内涉及控制台页签、按钮与状态徽标时,均保留精确的 Console 界面标识并附中文说明(如 Create API key(创建 API 密钥)、状态 ready)。 |
角色、入口与关联关系
1. 两套身份体系与三类接入面的关系
在阅读本手册各功能章节时,请始终区分以下两套身份与三类操作入口:
- 控制台开发者身份(Console Account):通过
/console/login注册并登录的平台管理与研发人员账号,归属于一个或多个 Organization(组织),按组织角色(owner、admin、developer、editor、billing、analyst)对项目资源执行配置、构建与运维操作。 - 应用终端用户身份(Project Auth User):在某个具体项目 Auth(认证) 模块内注册或同步的业务终端用户(如企业智能客服系统的客户
user_zhangwei_001、user_lina_002)。终端用户仅在应用前端通过客户端会话访问被授权的业务数据,无法登录/console/。 - 三类文档树的分工:
- 产品手册(本手册):聚焦 Console 可视化界面中各功能模块的概念、入口、配置步骤、异步状态流转与排障。
- REST API 参考手册:聚焦服务端通过项目 API Key 调用
/v1/*端点的 HTTP 方法、请求载荷、响应结构与错误码。 - SDK 开发指南:聚焦 Node.js(
agentbase-node-sdk@2.10.0)、Web(agentbase-web-sdk@2.10.0)、Console(agentbase-console-sdk@2.10.0)以及 Python(agentbase-python-sdk==2.10.0)、Java、Go 等多语言 SDK 的代码集成。
2. 模块间上下游配置依赖关系
Agentbase 内的 AI 能力模块并非孤立存在,而是存在严格的上下游前置依赖。按正确的依赖顺序完成配置,可避免绝大部分 412 Precondition Failed 或构建失败报错:
| 下游使用模块 | 强依赖的上游配置模块 | 必需满足的前置条件 |
|---|---|---|
| 知识库(Knowledge Base) | 存储(Storage)+ 模型网关(LLM Gateway) | 必须先准备好存储桶(如 kb_enterprise_docs)承载原始文件,并在模型网关中配置可用的 Embedding 模型(如 text-embedding-v3,1024 维)与 Rerank 模型(如 qwen3.7-text-rerank)。 |
| 知识库 GraphRAG / RAPTOR / Wiki | 知识库基础切片 + 模型网关 Chat 模型 | 文档必须先完成基础解析入库(状态 ready),且模型网关中已配置高可用 Chat 生成模型(如 qwen-plus)。 |
| 长期记忆(Memory) | 项目表模式 + 模型网关 Chat/Embedding/Vision | 项目必须为 OceanBase Shared V2 表模式;启用时需绑定 Chat 模型与 Embedding 模型(一旦初始化锁定 Embedding 维度);图片/PDF 记忆解析另需绑定视觉模型(如 qwen-vl-max)。 |
| 智能体工作台(Agent Runtime) | 模型网关 + 知识库 + 词库(可选) | 项目工作台配置(/v1/agent-runtime/project/config)需绑定主对话模型(如 qwen-plus),并按需挂载已就绪的知识库(kb_enterprise_support)与同义词/停用词词库。 |
| 知识索引质量评估(Evaluations) | 知识库高阶索引产物 + 评估模型配置 | 目标知识库已生成 GraphRAG、RAPTOR 或 LLM Wiki 产物,且在智能体运维评估页已配置默认评估模型(Judge LLM)。 |
功能详解与操作指南
本节提供面向不同业务诉求的“阅读路线图与实操检索指南”,帮助读者在 5 分钟内定位目标操作章节并掌握标准阅读规范。
1. 场景化阅读路径指南
路线 A:30 分钟首次开通与智能体对话闭环(推荐新用户)
- 阅读快速开始,完成 Console 登录、创建组织与
Shared V2项目enterprise-ai-hub-210。 - 参照项目总览登记 Web 平台并创建第一枚服务端 API Key,使用
curl验证/v1/health/version与/v1/users。 - 参照LLM Gateway 模型管理一键导入 DashScope 厂商预设(
qwen-plus、text-embedding-v3、qwen3.7-text-rerank)。 - 参照知识库概览创建知识库与词库,上传测试文档并在智能体工作台完成首次带知识库引用的对话调试。
路线 B:构建企业级高可靠应用后端(面向后端研发)
- 用户与权限设计:阅读核心概念掌握
user:{id}、team:{id}/{role}权限选择器,并在认证概览、用户管理、团队管理中配置 OAuth2/SSO 与会话安全策略。 - 结构化数据建模:阅读数据库概览与表、列、行与索引操作,创建业务库与索引;通过Schema 版本与回滚管理生产表结构变更,利用SQL 访问面执行在线 SQL 诊断。
- 文件、计算与风控:阅读存储管理分桶与文件令牌,阅读函数部署源码或 Java 17 预构建 JAR 函数,并在内容审核中为数据表和存储桶挂载阿里云 Green 多模态内容安全门禁。
路线 C:深耕 RAG 知识工程、长期记忆与 AgentOps(面向 AI 团队)
- 网关治理:在统一 AI 网关中配置逻辑模型主备路由、语义缓存
cp-semantic-cache与输入输出安全护栏gp-enterprise-safety。 - 高阶 RAG 与版本管理:在文档摄取与分块管理中配置
documentTag与subProductId,在Wiki、GraphRAG、RAPTOR 与索引治理中构建多跳图谱与编译态 Wiki,并通过知识库版本、封存与回滚实现零停机发版。 - 记忆与评测闭环:在记忆创建与召回检索、用户画像管理、记忆演化与技能蒸馏中运营跨会话个性化记忆,最后通过评估、评分与索引质量评测量化检验解析分块与索引产物质量。
2. 手册页面结构与图例阅读说明
本手册每一篇功能点文档均遵循统一的六节式工业级标准结构:
- 功能概述:阐明模块业务价值、适用场景与核心能力清单。
- 核心概念与架构:提供 Mermaid 架构/状态流转图及核心实体属性表。
- 角色、入口与关联关系:明确操作所需的组织角色、API Key Scope、Console 精确路由与上下游依赖。
- 功能详解与操作指南:按 Console 真实界面拆解分步操作、参数约束表、异步状态流转与验证结果,并配以真实环境带业务数据的界面截图与斜体图注。
- 常见问题与排障:针对高频报错码(如
401、403、409、412、503)与配置盲区提供可执行排查方案。 - 相关文档:提供同语言树内关联章节的相对路径跳转链接。
常见问题与排障
Q1:如何确认当前访问的 Agentbase 环境版本是否与本手册一致?
原因与排查步骤: 在浏览器或终端直接请求公开免鉴权接口 GET /v1/health/version。当返回 {"version":"2.10.0"} 时,表明服务端稳定基线与本手册完全对应。同时,在 Console 登录会话接口 /v1/account/sessions 的响应载荷及项目概览页底部状态栏中,也可核对当前运行版本。
Q2:为什么文档中提到的某些功能(如 Sites 站点、AI 网关或知识库可选索引)在我的项目控制台里找不到或提示不可用?
原因与排查步骤: Agentbase 的功能可见性由实例部署级开关(Capability)、项目级服务开关(Project Services)与当前账号组织角色三层共同决定:
- 若为项目默认关闭能力(如统一 AI 网关
aiGateway),请使用具备projects.write权限的角色进入 Settings → Overview → Services 手动开启。 - 若为侧栏默认隐藏入口(如消息
Messaging或智能体运维报表Observability Reports),可通过界面与路由速查中记载的直达 URL 访问。 - 若接口返回 HTTP
412,说明当前部署实例未开启对应环境变量或未部署相关 Worker 组件,请联系平台管理员确认部署清单。
Q3:在阅读本手册进行实操时,不小心误删了项目或修改错了表结构/知识库配置,能否恢复?
原因与排查步骤: Agentbase 针对核心生产资源提供了多层防误删与版本回滚机制:
- 项目级误清理:通过组织级 Project cleanup 发起清理的不活跃项目,在后台物理清理任务正式开始前,均可在 Account(账号中心) → Project cleanup 页签点击 Restore 无损恢复。
- 数据库 Schema 变更:在Schema 版本与回滚中支持版本化 Schema 快照与一键回滚,且激活前会自动校验物理表结构。
- 知识库与记忆 Pipeline:知识库支持工作副本封存与版本回滚;记忆服务支持四类 Pipeline 版本回滚与经验技能历史版本回滚。