快速开始
本章提供一份端到端、30 分钟内即可跑通的企业级实战入门指南。我们将以真实生产样板“企业智能客服与知识中台”(项目 ID:enterprise-ai-hub-210)为例,完整走通从登录 Console、创建组织与 Shared V2 项目、登记接入平台与签发 API Key、接入阿里云百炼 DashScope 模型供应商(qwen-plus、text-embedding-v3、qwen3.7-text-rerank)、构建企业支持知识库与同义词词库,到在智能体工作台(Agent Runtime Workbench)完成首次 RAG 对话调试与服务端 curl 验证的全流程闭环。
截图未公开:原图可能包含账号或资源标识。
界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。
功能概述
首次接入 Agentbase 的研发团队往往希望快速验证两条核心链路:
- 标准应用后端链路(BaaS 闭环):如何获取项目端点与服务端 API Key,通过标准 REST 接口完成服务版本探活与业务资源读写?
- 企业级智能体链路(Agent 闭环):如何将大模型(DashScope)、企业领域文档(知识库与干预词库)快速装配为一个可在线流式对话、可通过 API 集成的智能客服助手?
通过本章的 6 个标准步骤,你无需编写复杂的胶水代码,即可在 Console 内完成全部基础设施装配,并获得可直接用于生产微服务的 curl 验证脚本。
| 实操阶段 | 耗时预估 | 涉及控制台模块 | 本阶段交付产出物 |
|---|---|---|---|
| 步骤 1:登录与创建组织/项目 | 5 分钟 | 登录页、Organization、Project 创建向导 | 组织 Agentbase 企业智能中台(69c6d1aa00062e6bb60)、项目 enterprise-ai-hub-210(Shared V2 模式) |
| 步骤 2:登记平台与创建 API Key | 5 分钟 | Overview → Integrations(Platforms / API keys) | 已登记的 Web 平台域名、具备最小权限的 standard_ API Key |
| 步骤 3:命令行探活与首个数据面调用 | 3 分钟 | 终端命令行(curl) | 验证 /v1/health/version(2.10.0)与 /v1/users 鉴权闭环 |
| 步骤 4:配置 DashScope 模型供应商 | 5 分钟 | AI → 模型(/llm-gateway) | 供应商 dashscope-prod 及 qwen-plus、text-embedding-v3、qwen3.7-text-rerank、qwen-vl-max |
| 步骤 5:创建知识库与绑定干预词库 | 7 分钟 | AI → 知识库(/knowledge-base)与词库 | 同义词库 lex_enterprise_synonyms、停用词库 lex_support_stopwords、知识库 kb_enterprise_support |
| 步骤 6:智能体工作台联调与 API 验证 | 5 分钟 | AI → 智能体工作台(/agent-runtime) | 绑定模型+知识库+词库的工作台配置,完成在线问答与服务端 API 调用验证 |
核心概念与架构
在 30 分钟快速上手流程中,各配置步骤之间遵循自底向上的依赖装配关系。下图展示了本次实战创建的各实体标识及其调用流向:
flowchart LR
subgraph Step1_2["步骤 1~3:项目底座与鉴权"]
Org["组织: Agentbase 企业智能中台<br/>(69c6d1aa00062e6bb60)"]
Proj["项目: 企业智能客服与知识中台<br/>(enterprise-ai-hub-210 / Shared V2)"]
Key["服务端 API Key (standard_...)<br/>+ Web Platform 域名白名单"]
Org --> Proj --> Key
end
subgraph Step4["步骤 4:模型网关接入"]
Provider["DashScope 供应商: dashscope-prod<br/>dashscope.aliyuncs.com/compatible-mode/v1"]
ChatModel["Chat: qwen-plus / qwen-turbo"]
EmbedModel["Embedding: text-embedding-v3 (1024维)"]
RerankModel["Rerank: qwen3.7-text-rerank"]
Provider --> ChatModel
Provider --> EmbedModel
Provider --> RerankModel
end
subgraph Step5["步骤 5:知识库与词库构建"]
Bucket["存储桶: kb_enterprise_docs<br/>4 份企业技术支持 Markdown 文档"]
Lexicon["干预词库:<br/>lex_enterprise_synonyms (同义词)<br/>lex_support_stopwords (停用词)"]
KB["知识库: kb_enterprise_support<br/>向量+全文混合检索 / GraphRAG / Wiki"]
Bucket --> KB
Lexicon --> KB
EmbedModel --> KB
RerankModel --> KB
end
subgraph Step6["步骤 6:智能体工作台闭环"]
Workbench["智能体工作台 (/agent-runtime)<br/>/v1/agent-runtime/project/config"]
Caller["控制台流式对话 & 服务端 cURL 调用"]
ChatModel --> Workbench
KB --> Workbench
Lexicon --> Workbench
Key --> Caller --> Workbench
end快速上手核心资源参数对照表
| 资源类别 | 控制台显示名称 | 资源 ID($id / 标识) | 核心配置参数与规格 |
|---|---|---|---|
| 所属组织 | Agentbase 企业智能中台 | 69c6d1aa00062e6bb60 | 团队协作容器,当前操作账号具备 owner 或 developer 角色 |
| 目标项目 | 企业智能客服与知识中台 | enterprise-ai-hub-210 | 区域 default,底层存储模式为 OceanBase Shared V2 |
| 模型供应商 | DashScope 生产供应商 | dashscope-prod | 端点 https://dashscope.aliyuncs.com/compatible-mode/v1 |
| 核心模型集 | 通义千问系列模型 | qwen-plus / text-embedding-v3 / qwen3.7-text-rerank | 对话生成 / 1024 维向量化 / 检索结果精排 |
| 干预词库 | 企业同义词与停用词词典 | lex_enterprise_synonyms / lex_support_stopwords | 扩展“OB=OceanBase”等业务同义词,过滤客服语气寒暄停用词 |
| 企业知识库 | 企业智能客服与技术支持知识库 | kb_enterprise_support | 挂载 kb_enterprise_docs 桶内 4 份文档,全部分块入库状态 ready |
角色、入口与关联关系
1. 操作前置准备
在开始执行以下步骤前,请确认具备以下条件:
- 浏览器与网络:可正常访问目标实例控制台地址(如
https://appbuild.oceanbase.com/console/)。 - 账号与角色:拥有一个已通过邮箱验证(及 MFA 验证,若已开启)的 Console 开发者账号,且在目标组织中具备
owner、admin或developer写角色。 - 大模型 API Key(用于步骤 4~6):准备一枚有效的阿里云百炼 DashScope API Key(在文档中以
<DASHSCOPE_API_KEY>表示),用于驱动真实的向量化入库与智能体对话。
2. 关键入口路径速查
| 操作阶段 | 控制台左侧导航位置 | 路由后缀(相对于 /console/project-{region}-{project}) |
|---|---|---|
| 入门引导与 Agent Skill | Getting started | /get-started |
| 平台登记与 API Key 管理 | Overview → Integrations | /overview/platforms · /overview/api-keys |
| 服务开关与项目表模式确认 | Settings → Overview | /settings |
| 模型供应商与目录导入 | 模型(Models) | /llm-gateway |
| 知识库与干预词库构建 | 知识库(Knowledge Base) / 词库 | /knowledge-base · /knowledge-base/lexicons |
| 智能体装配与对话调试 | 智能体工作台(Agent Workbench) | /agent-runtime |
功能详解与操作指南
步骤 1:登录 Console 并创建组织与 Shared V2 项目
- 在浏览器打开
https://appbuild.oceanbase.com/console/。若尚未登录,系统会自动携带目标地址跳转至/console/login。输入开发者邮箱与密码完成登录(若账号启用了 MFA,在/console/mfa输入 6 位动态验证码)。 - 创建或选择组织:
- 首次登录的新账号会自动进入创建组织引导页(默认名称
Personal Projects);也可点击顶部组织下拉菜单选择 Create organization,输入组织名称Agentbase 企业智能中台完成创建。
- 首次登录的新账号会自动进入创建组织引导页(默认名称
- 创建项目:
- 在组织首页点击右上角 Create project。
- 输入项目名称
企业智能客服与知识中台,自定义项目 ID 为enterprise-ai-hub-210(或由系统自动生成),选择部署区域(Region),创建完成后自动进入项目的 Getting started(入门引导) 页(如图 1 所示)。 - 在入门引导页中,可看到 Agentbase Agent Skill 卡片,支持一键复制当前环境的 Skill 安装提示词,直接粘贴至 Cursor 或 Claude Code 等 AI 编程工具中辅助开发。
- 确认表模式与服务开关:
- 点击左侧导航底部的 Settings,在 Overview 页签下确认 项目表模式 为
Shared V2(若后续需使用 AI Memory 长期记忆,项目必须运行在Shared V2模式)。 - 在 Services 卡片中确认
Databases、Storage、Knowledge Bases、Memory与AI Gateway均处于启用状态。
- 点击左侧导航底部的 Settings,在 Overview 页签下确认 项目表模式 为
步骤 2:登记客户端平台与创建服务端 API Key
- 登记 Web 平台(供前端 SDK 跨域校验):
- 点击左侧导航 Overview,在下方 Integrations 区域处于 Platforms 页签时,点击 Add platform → 选择 Web app。
- 填写 Name(如
企业客服前端门户)与 Hostname(本地联调可填localhost,生产环境填写实际业务域名),点击提交完成登记。
- 创建服务端 API Key(供后端与命令行调用):
- 切换到 Integrations → API keys 页签,点击 Create API key。
- Name:填写
backend-quickstart-key;Expiration:选择90 days或Never。 - Scopes(权限范围):为完成本次快速验证,勾选
health.read、users.read、databases.read、databases.write、files.read、files.write以及 Knowledge Base 与 AI Gateway 分类下的读写权限。 - 点击 Create,在详情页立即点击 Copy API key 复制生成的密钥(以
standard_开头),并在本地终端导出为环境变量(切勿将密钥硬编码进代码库或直接拼接在命令行历史中):
export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"步骤 3:验证服务版本与首个数据面 API 调用
在终端中依次执行以下两条 curl 命令,验证网络连通性、项目 ID 路由与 API Key 权限:
- 公开版本探活(无需鉴权凭证):
curl -fsSL "${APPBASE_ENDPOINT}/health/version"预期成功响应(HTTP 200):
{"version":"2.10.0"}- **携带 API Key 查询项目终端用户列表(需
users.readScope)**:
curl -fsSL "${APPBASE_ENDPOINT}/users" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json"预期成功响应(HTTP 200):
{
"total": 2,
"users": [
{
"$id": "user_zhangwei_001",
"name": "张伟",
"email": "zhangwei@enterprise.example.com",
"status": true
},
{
"$id": "user_lina_002",
"name": "李娜",
"email": "lina@enterprise.example.com",
"status": true
}
]
}步骤 4:接入 DashScope 模型供应商与核心模型目录
- 点击项目左侧导航栏的 模型(Models)(路径
/llm-gateway)。 - 在 Providers(模型供应商) 页签点击 Create provider(添加供应商):
- 从厂商预设目录中选择 DashScope(阿里云百炼 / 通义千问)。
- Provider Name / ID:填写
dashscope-prod。 - Base URL:确认自动填充为
https://dashscope.aliyuncs.com/compatible-mode/v1。 - API Key:填入准备好的
<DASHSCOPE_API_KEY>。
- 在模型目录导入步骤中,勾选并启用以下生产模型:
- 对话生成(Chat):
qwen-plus(主力推理模型)、qwen-turbo(高并发兜底模型)。 - 文本向量化(Embedding):
text-embedding-v3(向量维度设为1024)。 - 重排序(Rerank):
qwen3.7-text-rerank。 - 多模态视觉(Vision):
qwen-vl-max(供后续图片/PDF 记忆与多模态解析使用)。
- 对话生成(Chat):
- 点击保存并确认供应商状态变为
Enabled / Active。
步骤 5:创建企业支持知识库与干预词库
- 创建干预词库(Lexicons):
- 点击左侧导航 词库(或进入 知识库 → 词库 页签
/knowledge-base/lexicons)。 - 创建同义词词典
lex_enterprise_synonyms(名称:企业专有名词同义词典),录入词条如OB, OceanBase, 分布式数据库(双向等价)与限流 -> 速率限制, Ratelimit, 429报错(单向扩展)。 - 创建停用词词典
lex_support_stopwords(名称:客服高频寒暄停用词典),录入词条如请问、你好、麻烦问一下。
- 点击左侧导航 词库(或进入 知识库 → 词库 页签
- 创建知识库并摄取文档:
- 先在左侧导航 Storage 中确认已创建存储桶
kb_enterprise_docs。 - 进入左侧导航 知识库(Knowledge Base),点击 Create knowledge base,填写名称
企业智能客服与技术支持知识库,自定义 ID 为kb_enterprise_support。 - 选择存储桶
kb_enterprise_docs,绑定 Embedding 模型dashscope-prod / text-embedding-v3(维度锁定为1024)与 Rerank 模型qwen3.7-text-rerank,并在词库设置中挂载lex_enterprise_synonyms与lex_support_stopwords。 - 进入知识库 Documents(文档) 页签,上传企业技术支持文档(如
Agentbase企业架构白皮书.md、智能客服SOP标准作业手册.md、OceanBase分布式事务与向量索引排障指南.md、AI网关模型路由与限流计费规范.md),触发解析摄取(Ingestion),等待文档状态由processing变为ready。
- 先在左侧导航 Storage 中确认已创建存储桶
步骤 6:在智能体工作台(Agent Runtime Workbench)配置与对话验证
完成模型与知识库准备后,即可进入智能体工作台进行可视化装配与流式对话测试:
- 点击项目左侧导航栏的 智能体工作台(Agent Workbench)(路径
/console/project-default-enterprise-ai-hub-210/agent-runtime)。 - 在左侧或顶部的 工作台配置面板 中完成绑定:
- 主对话模型(Model):选择
dashscope-prod下的qwen-plus。 - 系统提示词(System Prompt):输入企业客服角色指令(如:
你是 Agentbase 企业智能客服专家,请优先依据绑定的《企业智能客服与技术支持知识库》内容准确回答用户关于架构、排障与网关计费的问题,并在引用处标明文档来源。)。 - 挂载知识库(Knowledge Bases):勾选
kb_enterprise_support(企业智能客服与技术支持知识库),并开启词库干预(关联lex_enterprise_synonyms与lex_support_stopwords)。 - 点击 保存配置(Save),控制台会自动将该配置持久化至项目级端点
/v1/agent-runtime/project/config。
- 主对话模型(Model):选择
- 在线对话测试:
- 在右侧对话框中输入测试问题:
OceanBase 向量索引排障有哪些关键检查项?AI 网关如何配置主备模型路由与限流? - 点击发送,观察工作台流式返回结构化回答,并核对回答下方展开的知识库命中切片与来源文档引用。
- 在右侧对话框中输入测试问题:
- 通过服务端 API Key 验证工作台配置读取与对话(2.10.0 支持项目 API Key 认证):
curl -fsSL "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
-H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
-H "Content-Type: application/json"确认返回的 JSON 配置中包含已绑定的 qwen-plus 模型标识与 kb_enterprise_support 知识库 ID,至此端到端快速上手全部完成。
下一步:完成一次知识检索
如果你的目标是让 Agent 检索项目资料,按这条路径完成最小闭环:
| 步骤 | 页面 | 完成标志 |
|---|---|---|
| 1. 配置至少一个具备 Embedding 能力的模型 | Models | 创建知识库时能选到该模型 |
| 2. 创建知识库并选择 Embedding 模型 | Knowledge Base | 知识库出现在列表中 |
| 3. 上传一份代表性文档并等待摄取 | 知识库 Documents | 文档状态为 Ready,分块可查看 |
| 4. 输入一个能由该文档回答的问题 | 知识库 Search | 结果包含相关摘录和来源定位 |
| 5. 打开来源核对原文 | 结果 View source | 返回片段与原始页码/章节一致 |
详细配置、文档更新和检索调优见知识库。文档状态未就绪或来源不支持答案时,先检查解析与分块结果,不要仅凭相似度分数把召回内容当作事实。
常见问题与排障
Q1:执行步骤 3 的 curl 命令时返回 HTTP 401 或 403 错误如何排查?
原因与排查步骤: 请对照返回的 JSON 错误体 {message, code, type, version, requestId} 中的 type 字段快速定位:
type = "general_unauthorized_scope"(HTTP 401):当前 API Key 未勾选该接口所需的权限 Scope(如请求/v1/users缺少users.read)。请回到 Overview → Integrations → API keys 编辑该 Key,勾选对应 Scope 并保存。type = "user_unauthorized"(HTTP 401):请求头未携带X-Appwrite-Key,或环境变量${APPBASE_API_KEY}为空、复制时遗漏了standard_前缀。type = "project_not_found"或project_id_missing(HTTP 404 / 400):请求头X-Appwrite-Project填写的项目 ID 与实际创建的项目 ID 不一致,或 API Key 归属于另一个项目。
Q2:知识库上传文档后状态一直停留在 uploaded 或变为 failed 怎么办?
原因与排查步骤:
- 若状态为
uploaded:说明文件仅完成了上传登记,尚未触发异步摄取任务(Ingestion),请在文档列表行内点击 Ingest / 解析入库 按钮。 - 若状态变为
failed:点开该文档详情查看失败原因。最常见的原因是在步骤 4 配置dashscope-prod时填写的<DASHSCOPE_API_KEY>无效或欠费,或所选 Embedding 模型输出维度与知识库创建时锁定的1024维不一致。修正模型网关凭据后,在文档行操作中点击 重新摄取(Re-ingest) 即可恢复为ready。
Q3:使用服务端 API Key 调用 /v1/agent-runtime/* 接口时有哪些注意事项?
原因与排查步骤: 自 Agentbase 2.10.0 起,项目级 Agent Runtime 接口已正式支持服务端项目 API Key 认证(此前仅支持 Console 用户会话)。使用 API Key 调用时需确保:
- 该 Key 为项目级有效密钥(未过期,且与
X-Appwrite-Project请求头指定的项目严格匹配)。 - 若调用涉及特定终端用户的会话或记忆隔离,请在请求载荷中按接口规范显式传入目标
userId(如user_zhangwei_001)。