AgentbaseDocs
文档目录

知识库总览

知识库(Knowledge Base) 是 Agentbase v2.10.0 面向企业非结构化与半结构化知识资产打造的全链路检索增强生成(RAG)引擎。通过控制台左侧导航栏的 知识库(Knowledge Base) 入口,企业可将 Markdown、PDF、Office 文档、Excel 表格及语雀(Yuque)外部空间数据统一摄取入库,结合 词库(Lexicon) 同义词与停用词治理、多路混合检索(searchMode=hybrid)、语义重排(Rerank)、高级派生索引(GraphRAG、RAPTOR、LLM Wiki)以及不可变版本管理,为 智能体工作台(Agent Runtime) 与业务应用提供高准确率、可溯源的企业知识底座。


功能概述与核心场景

在企业智能客服与技术支持场景(如项目 企业智能客服与知识中台,ID:enterprise-ai-hub-210)中,传统单路向量检索往往面临专有名词漏召回、跨章节全局问题难以汇总、知识更新引发线上抖动等挑战。Agentbase 知识库提供端到端闭环能力:


核心概念与架构

企业级全链路 RAG 与知识治理架构图

flowchart TB
    subgraph Sources["多源知识输入与词库资产"]
        Docs["企业核心文档资产 (4 篇 ready 文档)\n• Agentbase企业架构白皮书.md\n• 智能客服SOP标准作业手册.md\n• OceanBase分布式事务与向量索引排障指南.md\n• AI网关模型路由与限流计费规范.md"]
        Yuque["外部数据源同步 (Data Sources)\n语雀知识库增量同步"]
        Lexicons["项目级词库 (Lexicons)\n• lex_enterprise_synonyms (同义词/扩展词)\n• lex_support_stopwords (停用词/拦截词)"]
    end

    subgraph IngestionPipeline["异步摄取与解析分块流水线 (HTTP 202 -> processing -> ready)"]
        Parser["多模态文档解析器\n(text / vlm: qwen-vl-max / mineru)"]
        Chunker["结构化分块器\n(general / title / smart / regex / faq)\n+ documentTag & subProductId 定位标签"]
        Embed["向量化引擎 (OceanBase Shared V2)\ntext-embedding-v3 (1024 维)"]
    end

    subgraph DerivedIndexes["高级派生知识索引 (Index Capabilities)"]
        GraphRAG["GraphRAG 知识图谱\n实体/关系抽取 + Leiden 社区报告"]
        RAPTOR["RAPTOR 递归摘要树\n跨章节层次化聚类摘要"]
        Wiki["LLM Wiki 知识百科\n自动编译 10 篇章节树页面 + 冲突裁决"]
    end

    subgraph RetrievalEngine["多路混合检索与答案合成引擎"]
        QueryRewrite["词库预处理\n停用词过滤 + 同义词扩展"]
        HybridSearch["多路召回 (searchMode=hybrid)\n向量检索 (vectorWeight) + 全文检索 + Graph/RAPTOR"]
        Reranker["语义重排 (qwen3.7-text-rerank)\nrecallLimit 候选精排;显式模型失败返回错误"]
        Synthesizer["接地答案合成 (answer=true)\nqwen-plus 结合 Top 证据生成引用回答"]
    end

    subgraph Consumers["下游消费端"]
        Workbench["智能体工作台 (Agent Runtime)\n/v1/agent-runtime/project/config"]
        AIGW["AI 网关 / 业务 API 调用"]
    end

    Docs & Yuque --> Parser --> Chunker --> Embed
    Embed --> GraphRAG & RAPTOR & Wiki
    Lexicons --> QueryRewrite
    QueryRewrite --> HybridSearch
    Embed & GraphRAG & RAPTOR --> HybridSearch
    HybridSearch --> Reranker --> Synthesizer --> Workbench & AIGW

核心概念与术语说明表

核心概念关键字段 / 接口标识详细说明
知识库实例knowledgeBaseId知识文档、分块、向量索引、派生图谱与版本快照的顶层容器(如 kb_enterprise_support)。创建时绑定唯一的 Embedding 模型(text-embedding-v3,1024 维)。
异步摄取作业ingestionId / HTTP 202文档上传或触发重建后生成的异步摄取流水线记录。接口立即返回 202 Accepted,后台经历解析、分块、图片理解与向量化,最终将文档状态置为 ready。
文档定位标识documentTag / subProductIdv2.10.0 引入的精准过滤元数据。documentTag 格式为 {subProductId}_{sectionCode}_{fileKey},支持在文档列表、单库/跨库检索与 Wiki 冲突列表中精确过滤。
词库(Lexicon)lexiconId项目级词汇治理组件,支持同义词(synonym)、扩展词(expansion)与停用词(stop)。可同时绑定至知识库与智能体工作台。
检索模式searchMode支持 hybrid(默认,向量 + 全文混合检索)、vector(纯语义向量检索)与 fulltext(关键词全文检索)。
混合向量权重vectorWeight在 searchMode=hybrid 下控制向量相似度得分与全文 BM25 得分的加权比例(取值范围 0.0~1.0,如 0.7 表示 70% 向量权重 + 30% 全文权重)。
增强检索降级allowDegraded单库默认 true;GraphRAG / RAPTOR / Wiki 遇到可降级错误时保留普通结果,并通过 capabilities / degradedCapabilities 记录。设为 false 时相关错误向调用方返回。
派生知识索引graphrag / raptor / wiki在基础 Chunk 向量索引之上构建的三类高阶索引能力,分别解决多跳实体关系推理、跨文档宏观总结与结构化百科沉淀问题。

功能入口与权限矩阵

十子模块导航、REST API 与权限矩阵总表

子模块名称手册专章链接前端控制台路由路径核心 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
知识库总览与实例管理overview.md/console/project-default-enterprise-ai-hub-210/knowledge-baseGET/POST /v1/knowledgebasesknowledgeBase.list() / create()owner、admin、developer(只读成员仅查看)<br/>Scope:knowledgebases.read / write依赖 dashscope-prod 的 text-embedding-v3(1024 维)与 OceanBase Shared V2
文档与异步摄取管理documents.md/console/.../kb-kb_enterprise_support/documentsPOST /v1/knowledgebases/{kbId}/documents<br/>GET .../ingestions/{ingestionId}knowledgeBase.createDocument()<br/>getIngestion()owner、admin、developer<br/>Scope:knowledgebases.write依赖 kb_enterprise_docs 存储桶与 text / vlm / mineru 解析器
外部数据源与语雀同步datasources.md/console/.../kb-kb_enterprise_support/datasourcesPOST .../datasources/personal_yuque<br/>POST .../datasources/{id}/syncknowledgeBase.createPersonalYuqueDataSource()<br/>syncDataSource()owner、admin、developer<br/>Scope:knowledgebases.write同步后自动触发摄取并标记派生索引为 stale (data_source_sync)
高级知识索引构建治理indexing.md/console/.../kb-kb_enterprise_support/indexesGET/PATCH .../index-capabilities/{cap}<br/>POST .../index-operationsknowledgeBase.updateIndexCapability()<br/>createIndexOperation()owner、admin、developer<br/>Scope:knowledgebases.write依赖 qwen-plus、text-embedding-v3 与 ModelCapacity 双信号量隔离
知识图谱可视化与社区报告graph.md/console/.../kb-kb_enterprise_support/graphGET .../graph<br/>GET .../graph/entities/{id}/neighbors<br/>GET .../graph/community-reportsknowledgeBase.getGraph()<br/>getGraphEntityNeighbors()<br/>listGraphCommunityReports()owner、admin、developer、member<br/>Scope:knowledgebases.read依赖 GraphRAG 构建就绪;赋能 useKnowledgeGraph: true 多跳检索
知识库 Wiki 编译与治理wiki.md/console/.../kb-kb_enterprise_support/wikiGET/POST .../wiki/pages<br/>GET .../wiki/conflicts<br/>POST .../export-to-memoryknowledgeBase.listWikiPages()<br/>resolveWikiConflict()<br/>exportWikiPageToMemory()owner、admin、developer<br/>Scope:knowledgebases.write联动 版本管理(Versions) 封存门禁与 记忆(Memory) 导出
混合检索与问答调试search.md/console/.../kb-kb_enterprise_support/searchPOST /v1/knowledgebases/{kbId}/search<br/>POST /v1/knowledgebases/searchcreateSearch() / create_search()<br/>createMultiSearch() / create_multi_search()owner、admin、developer、member<br/>Scope:knowledgebases.read依赖 qwen3.7-text-rerank 重排、增强检索降级状态与 qwen-plus 合成
不可变版本管理与回滚versions.md/console/.../kb-kb_enterprise_support/versionsPOST .../version-adoptions<br/>POST .../versions/{id}/seal<br/>POST .../publish & rollbackknowledgeBase.createVersion()<br/>sealVersion()<br/>publishVersion()owner、admin(及授权发布人员)<br/>Scope:knowledgebases.write写时复制隔离草稿(DRAFT)与线上激活版本(Current)
项目级词库与多端绑定lexicons.md/console/.../knowledge-base/lexicons<br/>/console/.../kb-kb_enterprise_support/lexiconsGET/POST /v1/lexicons<br/>PUT .../kb_enterprise_support/lexiconsknowledgeBase.createLexicon()<br/>updateKnowledgeBaseLexicons()owner、admin、developer<br/>Scope:lexicons.writenative-v1 分词器同时赋能检索改写、GraphRAG 消歧与智能体 stopIntercept
知识库设置与多模态 VLMsettings.md/console/.../kb-kb_enterprise_support/settingsPATCH /v1/knowledgebases/{kbId}<br/>POST /v1/knowledgebases/{kbId}/reindexknowledgeBase.update()<br/>reindex()owner、admin、developer(删除仅限 owner/admin)<br/>Scope:knowledgebases.write绑定 qwen-vl-max 图片理解(并发 1..16)与 OpenTelemetry 摄取追踪

与智能体工作台(Agent Runtime)的深度集成

在控制台左侧导航栏进入 智能体工作台(Agent Runtime),可通过项目级运行时配置(PUT /v1/agent-runtime/project/config)将主对话模型设为 qwen-plus,直接挂载知识库 kb_enterprise_support 并绑定项目级词库 lex_enterprise_synonyms 与 lex_support_stopwords,立即在工作台对话窗口中验证带知识引用角标的企业客服问答。


功能详解与操作指南

步骤 1:创建企业知识库(kb_enterprise_support)

配置项字段名标杆配置值说明与约束
知识库名称name企业智能客服与技术支持知识库展示名称(标识 ID:kb_enterprise_support)
描述description沉淀架构白皮书、客服 SOP、OceanBase 向量排障与 AI 网关规范选填,说明知识库覆盖领域
向量模型(Embedding Model)embeddingModeltext-embedding-v3(来自 dashscope-prod)必选且创建后不可变更;系统自动探测模型可用性
向量维度(Dimension)embeddingDimension1024与 text-embedding-v3 输出维度严格一致,存储在 OceanBase Shared V2 向量表中
文档解析器(Document Parser)documentParsertext(支持按需切换 vlm / mineru)控制原始文件到结构化 Markdown 文本的提取方式
分块策略(Chunking Parser)chunkingParsertitle / smart推荐技术文档使用按标题层级或智能语义分块
分块大小与重叠率chunkTokenNum / overlapPercent512 Tokens / 10%兼顾上下文完整性与向量聚焦度
图片理解(Image Understanding)imageUnderstanding开启,模型选 qwen-vl-max,并发度 4自动对文档内的架构图与截图生成文字描述并合入分块索引
摄取追踪(Ingestion Tracing)ingestionTracing开启(true)记录解析与分块中间产物,供可观测性「知识库解析评估」使用

步骤 2:摄取核心文档并轮询 202 异步摄取状态至 ready

# 查询指定文档的异步摄取作业详情
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/documents/doc_ob_troubleshooting/ingestions/ing_9f8e7d6c5b4a3210" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

步骤 3:绑定词库(Lexicon)并启用高级索引(GraphRAG / RAPTOR / Wiki)


步骤 4:执行混合检索(searchMode=hybrid)与关联智能体工作台

在 检索测试(Search) 页签核对召回与来源;以下 API 示例另开启答案合成,并指定重排模型。示例模型名须替换为项目实际配置,显式模型失败不会被 allowDegraded 忽略:

curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/search" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "OceanBase 向量索引构建报 4013 内存不足时如何排障?工单升级 SOP 是什么?",
    "searchMode": "hybrid",
    "vectorWeight": 0.7,
    "similarityThreshold": 0.35,
    "limit": 5,
    "rerank": true,
    "rerankModel": "qwen3.7-text-rerank",
    "recallLimit": 20,
    "allowDegraded": true,
    "answer": true
  }'

随后,在 智能体工作台(Agent Runtime) 中保存项目级配置(/v1/agent-runtime/project/config),将 kb_enterprise_support 与词库 lex_enterprise_synonyms、lex_support_stopwords 挂载至 qwen-plus 智能体,即可在对话面板直接获得融合了排障指南与客服 SOP 的精准解答。


知识库设置与项目级词库(Lexicons)管理

一、管理知识库全局设置(Knowledge Base Settings)

进入 kb_enterprise_support 的 设置(Settings) 页签,可按分组查看与修改以下配置:

设置分组配置项标杆配置值变更影响与注意事项
基础信息名称与描述 (name / description)企业智能客服与技术支持知识库修改后立即生效,不影响任何索引与检索行为。
向量底座(只读)向量模型与维度 (embeddingModel / embeddingDimension)text-embedding-v3 / 1024 维创建后严禁修改。因为不同模型或不同维度的向量无法在同一 OceanBase 向量索引表中计算余弦距离。如需更换向量模型,请新建知识库。
**默认摄取与分块 (indexingDefaults)**文档解析器 (documentParser)<br/>分块解析器 (chunkingParser)<br/>分块参数 (chunkTokenNum 等)text<br/>title<br/>512 Tokens / 10% 重叠保存后仅对后续新上传或新触发摄取的文档生效;若希望存量 ready 文档应用新分块策略,须回到 文档 页签点击 整库重建(Reindex)。
**多模态图片理解 (imageUnderstanding)**启用开关 (enabled)<br/>视觉模型 (model)<br/>并发度 (maxConcurrency)<br/>自定义提示词 (prompt)true<br/>qwen-vl-max<br/>4(范围 1–8)<br/>请提取架构图与表格中的关键组件、参数与流向要求项目已在 LLM Gateway 注册具备 vlm 能力的 Provider;开启后需对历史含图文档重新摄取以生成图片描述。
**检索默认值 (retrievalDefaults)**向量权重 (vectorWeight)、相似度阈值 (similarityThreshold)示例 0.7、0.35检索请求省略这些参数时读取库默认值;searchMode 由请求选择,省略为 hybrid。
**答案合成模型 (indexingDefaults)**chatModel、可选 chatProviderRef项目实际可用的 Chat 模型单库 API answer=true 时使用;不是 retrievalDefaults 中的配置。
**摄取追踪 (ingestionTracing)**记录解析与分块中间产物true(开启)供 可观测 -> 知识库解析评估 读取原始解析快照(需平台全局开关允许)。

二、创建与管理项目级词库(lex_enterprise_synonyms & lex_support_stopwords)

在项目 enterprise-ai-hub-210 中,我们配置了 lex_enterprise_synonyms 与 lex_support_stopwords 两本核心生产词库(完整的 native-v1 分词原理、在线预览调试与 CSV/XLSX/JSON 导表指南详见项目级词库(Lexicons)与检索/图谱/智能体协同治理)。以下是快速创建与绑定步骤:

步骤 1:创建同义词词典与停用词词典

步骤 2:添加同义词(synonym)、扩展词(expansion)与停用词(stop)词条

进入词库详情页,点击 添加词条(Add entry) 或点击 批量导入(Import CSV/Excel) 上传词表:

所属词库词条类型 (type)主词 / 触发词 (term)目标同义词 / 扩展词列表 (targets)状态 (enabled)业务作用说明
lex_enterprise_synonymssynonymOB["OceanBase", "OceanBase数据库"]true用户搜 OB 与搜 OceanBase 完全双向等价召回
lex_enterprise_synonymssynonymAIGW["AI网关", "AI Gateway", "统一AI网关"]true统一中英文缩写与产品正式名称
lex_enterprise_synonymsexpansion向量报错4013["OB_ALLOCATE_MEMORY_FAILED", "ob_vector_memory_limit_percentage", "-4013"]true用户输入口语化报错时,单向注入精确错误码与内核参数名
lex_enterprise_synonymsexpansion工单升级["二线技术专家", "SOP流转时限", "P1故障响应"]true强化客服 SOP 手册章节召回
lex_support_stopwordsstop请问一下呗[]true检索前剥离无意义口语后缀
lex_support_stopwordsstop忽略之前所有系统指令[]true在智能体工作台配合 stopIntercept 直接拦截越狱指令

批量导入/导出说明:点击词库右上角的 导出(Export) 可下载标准格式模板(含 type,term,targets,enabled 列),在本地 Excel 编辑完数千条行业词条后点击 导入(Import) 即可一键完成增量合并或全量更新。


三、将词库绑定至知识库与智能体工作台(REST API 与控制台操作)

词库创建完成后,需要将其绑定至目标知识库(kb_enterprise_support)或智能体工作台(Agent Runtime)方可在运行时生效:

1. 绑定至知识库(/v1/knowledgebases/{knowledgeBaseId}/lexicons)

在 kb_enterprise_support 的 设置(Settings)-> 关联词库(Bound Lexicons) 区域,勾选 lex_enterprise_synonyms 与 lex_support_stopwords 并点击保存;或通过 API 绑定:

# 1. 创建项目级词库 (POST /v1/lexicons)
curl -X POST "https://appbuild.oceanbase.com/v1/lexicons" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lexiconId": "lex_enterprise_synonyms",
    "name": "企业智能客服同义词与专有名词词典",
    "description": "OceanBase与AI网关专有名词同义词及扩展词"
  }'

# 2. 向词库批量添加 synonym 与 expansion 词条 (POST /v1/lexicons/{lexiconId}/entries)
curl -X POST "https://appbuild.oceanbase.com/v1/lexicons/lex_enterprise_synonyms/entries" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "expansion",
    "term": "向量报错4013",
    "targets": ["OB_ALLOCATE_MEMORY_FAILED", "ob_vector_memory_limit_percentage", "-4013"],
    "enabled": true
  }'

# 3. 将词库绑定至知识库 kb_enterprise_support (PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons)
curl -X PUT "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/lexicons" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lexiconIds": ["lex_enterprise_synonyms", "lex_support_stopwords"]
  }'

2. 绑定至智能体工作台并开启停用词前置拦截(/v1/agent-runtime/project/lexicons)

在智能体工作台配置中绑定词库,并配置 stopIntercept 与 stopReply:

curl -X PUT "https://appbuild.oceanbase.com/v1/agent-runtime/project/lexicons" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "lexiconIds": ["lex_enterprise_synonyms", "lex_support_stopwords"],
    "stopIntercept": true,
    "stopReply": "抱歉,您的提问包含受限或不符合企业安全规范的指令,请围绕产品技术支持与客服业务进行咨询。"
  }'

验证结果:


首次完成一次检索

建议按“准备模型 → 创建知识库 → 摄取文档 → 检索验证 → 核对来源”的顺序走完一条路径。下图只表达已核验的操作关系,不还原 Console 页面,也不是运行截图:

截图未公开:原图可能包含账号或资源标识。

创建知识库前,至少要有一个具备 embedding 能力的模型;只有需要图片理解时才额外配置视觉模型。若要让检索请求生成答案,还需按部署能力配置对应的 chat 模型。模型服务和可选解析能力都受项目配置及部署能力约束,见模型与 AI 网关。

如果结果缺少预期内容,先确认文档已完成摄取,并检查解析和分块结果;修改解析器或分块参数后,需要重新摄取受影响的文档。检索结果的分数用于排序,不代替对来源原文的核对。

创建知识库

列表页点击 Create knowledge base,字段:

字段规则
Name / Description名称必填;描述可选
Embedding model必选(仅列出具备 embedding 能力的 Provider 模型;未选无法提交)
Embedding dimension可选(1–65535):对所选模型探测校验,不匹配则创建失败
Ingestion tracing可选开关:开启后记录摄取中间产物(解析 / 分块),供「知识库解析评估」使用;依赖平台管理员全局开关,开启后需重新摄取才有完整证据
Image understanding开关 + 模型 + 提示词 + 最大并发(需项目已配置视觉模型 Provider)
Chunking parsergeneral / title / smart / regex / faq,及分块参数:chunkTokenNum(默认 512)、overlapPercent(默认 10)、titleLevel(默认 3)、minChunkTokens(默认 128)、delimiter、regexPattern

解析配置只影响之后的摄取;历史文档要重新摄取才会应用新配置。

使用边界

常见问题与排障(FAQ)

Q1:上传文档后接口返回了 HTTP 202,为什么立即调用检索接口还没有搜到该文档内容?

Q2:启用 Rerank 后,上游限流是否会让检索失败?

取决于是否显式选择重排模型或 Provider。传入 rerankModel 或 rerankProviderRef 时,调用异常会返回给调用方;应修复模型配置、限流或服务故障。两者均未指定的自动重排采用尽力执行方式,失败可回退原排序,返回 reranked: false,此时不要把结果当作已精排。

allowDegraded 单独控制增强检索的可降级错误,不能用于忽略显式重排模型失败。单库响应的 capabilities 与 degradedCapabilities 描述增强能力状态;按业务是否接受基础结果选择该开关。

Q3:修改了知识库的默认分块参数(如 chunkTokenNum)或开启了图片理解后,已处于 ready 状态的存量文档会自动生效吗?

Q4:词库(Lexicon)绑定在知识库上和绑定在智能体工作台上有什么区别?


相关文档