AgentbaseDocs
文档目录

快速开始

本章提供一份端到端、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 的研发团队往往希望快速验证两条核心链路:

通过本章的 6 个标准步骤,你无需编写复杂的胶水代码,即可在 Console 内完成全部基础设施装配,并获得可直接用于生产微服务的 curl 验证脚本。

实操阶段耗时预估涉及控制台模块本阶段交付产出物
步骤 1:登录与创建组织/项目5 分钟登录页、Organization、Project 创建向导组织 Agentbase 企业智能中台(69c6d1aa00062e6bb60)、项目 enterprise-ai-hub-210(Shared V2 模式)
步骤 2:登记平台与创建 API Key5 分钟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. 操作前置准备

在开始执行以下步骤前,请确认具备以下条件:

2. 关键入口路径速查

操作阶段控制台左侧导航位置路由后缀(相对于 /console/project-{region}-{project})
入门引导与 Agent SkillGetting 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 项目

步骤 2:登记客户端平台与创建服务端 API Key

     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"}
   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 模型供应商与核心模型目录

步骤 5:创建企业支持知识库与干预词库

步骤 6:在智能体工作台(Agent Runtime Workbench)配置与对话验证

完成模型与知识库准备后,即可进入智能体工作台进行可视化装配与流式对话测试:

   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 字段快速定位:

Q2:知识库上传文档后状态一直停留在 uploaded 或变为 failed 怎么办?

原因与排查步骤:

Q3:使用服务端 API Key 调用 /v1/agent-runtime/* 接口时有哪些注意事项?

原因与排查步骤: 自 Agentbase 2.10.0 起,项目级 Agent Runtime 接口已正式支持服务端项目 API Key 认证(此前仅支持 Console 用户会话)。使用 API Key 调用时需确保:

相关文档