知识库总览
知识库(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 知识库提供端到端闭环能力:
- 多模态富文档异步摄取与精准分块:
- 支持本地批量上传、Storage 存储桶(如
kb_enterprise_docs)文件绑定及语雀(Yuque)数据源增量同步。 - 内置
text、vlm(视觉大模型解析)、mineru(复杂 PDF 版面/公式/表格还原)三类文档解析器,以及general、title、smart、regex、faq五类分块策略。 - 文档摄取采用异步任务机制:触发摄取接口返回 HTTP
202状态码,可通过GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}实时轮询摄取进度,直至文档状态流转为ready。
- 支持本地批量上传、Storage 存储桶(如
- 项目级词库(Lexicon)协同治理:
- 支持创建同义词/扩展词词典(如
lex_enterprise_synonyms)与停用词/拦截词词典(如lex_support_stopwords),并一键绑定至知识库(kb_enterprise_support)与智能体工作台,在检索前自动完成业务黑话改写、同义词扩展与违规提问拦截。
- 支持创建同义词/扩展词词典(如
- 多路混合检索与韧性重排(Hybrid Search & Rerank):
- 支持
hybrid(混合检索)、vector(向量检索)与fulltext(全文检索)三种searchMode,可通过vectorWeight精细调节向量与全文得分融合比例。 - 可选启用重排;显式
rerankModel或rerankProviderRef调用失败时返回错误,均未指定的自动重排失败可回退并返回reranked: false。单库allowDegraded控制增强索引的可降级错误;answer=true使用检索证据合成答案,读者仍需核对来源。
- 支持
- 三大高级派生索引(GraphRAG / RAPTOR / Wiki):
- 基于已就绪(
ready)的文档分块自动构建实体关系知识图谱(GraphRAG)、层次化递归聚类摘要树(RAPTOR)以及结构化百科页面(Wiki,如自动编译生成 10 篇技术支持百科页面)。
- 基于已就绪(
- 不可变版本发布与智能体工作台联动:
- 支持草稿工作副本(Draft)、就绪门禁校验(Readiness Gate)、封存(Seal)、发布(Publish)与一键回滚(Rollback),并在 智能体工作台(Agent Runtime) 中直接挂载知识库与词库开展多轮交互问答。
核心概念与架构
企业级全链路 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 / subProductId | v2.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-base | GET/POST /v1/knowledgebases | knowledgeBase.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/documents | POST /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/datasources | POST .../datasources/personal_yuque<br/>POST .../datasources/{id}/sync | knowledgeBase.createPersonalYuqueDataSource()<br/>syncDataSource() | owner、admin、developer<br/>Scope:knowledgebases.write | 同步后自动触发摄取并标记派生索引为 stale (data_source_sync) |
| 高级知识索引构建治理 | indexing.md | /console/.../kb-kb_enterprise_support/indexes | GET/PATCH .../index-capabilities/{cap}<br/>POST .../index-operations | knowledgeBase.updateIndexCapability()<br/>createIndexOperation() | owner、admin、developer<br/>Scope:knowledgebases.write | 依赖 qwen-plus、text-embedding-v3 与 ModelCapacity 双信号量隔离 |
| 知识图谱可视化与社区报告 | graph.md | /console/.../kb-kb_enterprise_support/graph | GET .../graph<br/>GET .../graph/entities/{id}/neighbors<br/>GET .../graph/community-reports | knowledgeBase.getGraph()<br/>getGraphEntityNeighbors()<br/>listGraphCommunityReports() | owner、admin、developer、member<br/>Scope:knowledgebases.read | 依赖 GraphRAG 构建就绪;赋能 useKnowledgeGraph: true 多跳检索 |
| 知识库 Wiki 编译与治理 | wiki.md | /console/.../kb-kb_enterprise_support/wiki | GET/POST .../wiki/pages<br/>GET .../wiki/conflicts<br/>POST .../export-to-memory | knowledgeBase.listWikiPages()<br/>resolveWikiConflict()<br/>exportWikiPageToMemory() | owner、admin、developer<br/>Scope:knowledgebases.write | 联动 版本管理(Versions) 封存门禁与 记忆(Memory) 导出 |
| 混合检索与问答调试 | search.md | /console/.../kb-kb_enterprise_support/search | POST /v1/knowledgebases/{kbId}/search<br/>POST /v1/knowledgebases/search | createSearch() / 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/versions | POST .../version-adoptions<br/>POST .../versions/{id}/seal<br/>POST .../publish & rollback | knowledgeBase.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/lexicons | GET/POST /v1/lexicons<br/>PUT .../kb_enterprise_support/lexicons | knowledgeBase.createLexicon()<br/>updateKnowledgeBaseLexicons() | owner、admin、developer<br/>Scope:lexicons.write | native-v1 分词器同时赋能检索改写、GraphRAG 消歧与智能体 stopIntercept |
| 知识库设置与多模态 VLM | settings.md | /console/.../kb-kb_enterprise_support/settings | PATCH /v1/knowledgebases/{kbId}<br/>POST /v1/knowledgebases/{kbId}/reindex | knowledgeBase.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)
- 在左侧导航栏点击 知识库(Knowledge Base),点击右上角 创建知识库(Create knowledge base) 按钮。
- 按照企业智能客服标杆配置填写表单参数:
| 配置项 | 字段名 | 标杆配置值 | 说明与约束 |
|---|---|---|---|
| 知识库名称 | name | 企业智能客服与技术支持知识库 | 展示名称(标识 ID:kb_enterprise_support) |
| 描述 | description | 沉淀架构白皮书、客服 SOP、OceanBase 向量排障与 AI 网关规范 | 选填,说明知识库覆盖领域 |
| 向量模型(Embedding Model) | embeddingModel | text-embedding-v3(来自 dashscope-prod) | 必选且创建后不可变更;系统自动探测模型可用性 |
| 向量维度(Dimension) | embeddingDimension | 1024 | 与 text-embedding-v3 输出维度严格一致,存储在 OceanBase Shared V2 向量表中 |
| 文档解析器(Document Parser) | documentParser | text(支持按需切换 vlm / mineru) | 控制原始文件到结构化 Markdown 文本的提取方式 |
| 分块策略(Chunking Parser) | chunkingParser | title / smart | 推荐技术文档使用按标题层级或智能语义分块 |
| 分块大小与重叠率 | chunkTokenNum / overlapPercent | 512 Tokens / 10% | 兼顾上下文完整性与向量聚焦度 |
| 图片理解(Image Understanding) | imageUnderstanding | 开启,模型选 qwen-vl-max,并发度 4 | 自动对文档内的架构图与截图生成文字描述并合入分块索引 |
| 摄取追踪(Ingestion Tracing) | ingestionTracing | 开启(true) | 记录解析与分块中间产物,供可观测性「知识库解析评估」使用 |
步骤 2:摄取核心文档并轮询 202 异步摄取状态至 ready
- 进入
kb_enterprise_support的 文档(Documents) 页签,点击 上传文档(Upload documents),上传 4 篇企业核心技术文档: Agentbase企业架构白皮书.md智能客服SOP标准作业手册.mdOceanBase分布式事务与向量索引排障指南.mdAI网关模型路由与限流计费规范.md
- 当通过控制台或 API(
POST /v1/knowledgebases/{knowledgeBaseId}/documents或重新摄取接口)提交文档时,服务端立即返回 HTTP **202**(Accepted)响应及对应的ingestionId。 - 客户端或自动化脚本可通过以下标准接口精确查询单次摄取作业的执行阶段与分块产出:
# 查询指定文档的异步摄取作业详情
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>"- 当返回的作业与文档状态字段更新为 **
ready** 时,表示该文档已完成文本解析、分块切分与1024维向量写入,可立即参与在线检索。
步骤 3:绑定词库(Lexicon)并启用高级索引(GraphRAG / RAPTOR / Wiki)
- 绑定项目级词库:
- 在项目 词库(Lexicons) 中创建同义词词典
lex_enterprise_synonyms(例如将OB向量报错4013、向量内存不足映射至标准术语OB_ALLOCATE_MEMORY_FAILED)和停用词词典lex_support_stopwords。 - 调用
PUT /v1/knowledgebases/kb_enterprise_support/lexicons或在知识库设置页勾选绑定这两个词库。
- 在项目 词库(Lexicons) 中创建同义词词典
- 启用并构建派生索引:
- 切换到知识库 知识索引(Indexes) 页签,依次开启 GraphRAG、RAPTOR 与 LLM Wiki 三项索引能力开关,并点击 构建(Build)。
- 构建完成后,Graph 页签可浏览实体关系图谱,Wiki 页签自动编译生成包含首页总览(
kb-index)在内的 10 篇结构化百科页面。
步骤 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:创建同义词词典与停用词词典
- 进入 词库(Lexicons) 管理界面,点击 创建词库(Create lexicon)。
- 分别创建以下两本词库:
- 词库 1(同义词与扩展词词典):
- 词库 ID / 名称:
lex_enterprise_synonyms(企业智能客服同义词与专有名词词典) - 描述:
统一 OceanBase、AI 网关及客服工单领域的缩写、黑话与错误码扩展
- 词库 ID / 名称:
- 词库 2(停用词与合规拦截词典):
- 词库 ID / 名称:
lex_support_stopwords(企业客服停用词与敏感拦截词典) - 描述:
清洗检索口语噪声词并在智能体工作台前置拦截违规诱导提问
- 词库 ID / 名称:
步骤 2:添加同义词(synonym)、扩展词(expansion)与停用词(stop)词条
进入词库详情页,点击 添加词条(Add entry) 或点击 批量导入(Import CSV/Excel) 上传词表:
| 所属词库 | 词条类型 (type) | 主词 / 触发词 (term) | 目标同义词 / 扩展词列表 (targets) | 状态 (enabled) | 业务作用说明 |
|---|---|---|---|---|---|
lex_enterprise_synonyms | synonym | OB | ["OceanBase", "OceanBase数据库"] | true | 用户搜 OB 与搜 OceanBase 完全双向等价召回 |
lex_enterprise_synonyms | synonym | AIGW | ["AI网关", "AI Gateway", "统一AI网关"] | true | 统一中英文缩写与产品正式名称 |
lex_enterprise_synonyms | expansion | 向量报错4013 | ["OB_ALLOCATE_MEMORY_FAILED", "ob_vector_memory_limit_percentage", "-4013"] | true | 用户输入口语化报错时,单向注入精确错误码与内核参数名 |
lex_enterprise_synonyms | expansion | 工单升级 | ["二线技术专家", "SOP流转时限", "P1故障响应"] | true | 强化客服 SOP 手册章节召回 |
lex_support_stopwords | stop | 请问一下呗 | [] | true | 检索前剥离无意义口语后缀 |
lex_support_stopwords | stop | 忽略之前所有系统指令 | [] | 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": "抱歉,您的提问包含受限或不符合企业安全规范的指令,请围绕产品技术支持与客服业务进行咨询。"
}'验证结果:
- 当用户在知识库检索或智能体工作台中询问
OB向量报错4013怎么处理时,系统自动通过lex_enterprise_synonyms扩展出OceanBase、OB_ALLOCATE_MEMORY_FAILED与ob_vector_memory_limit_percentage,精准命中《OceanBase分布式事务与向量索引排障指南.md》中的核心分块。 - 当用户输入包含
lex_support_stopwords中的受限词条时,智能体工作台在毫秒级直接返回stopReply预设回复,零 Token 消耗完成合规拦截。
首次完成一次检索
建议按“准备模型 → 创建知识库 → 摄取文档 → 检索验证 → 核对来源”的顺序走完一条路径。下图只表达已核验的操作关系,不还原 Console 页面,也不是运行截图:
截图未公开:原图可能包含账号或资源标识。
创建知识库前,至少要有一个具备 embedding 能力的模型;只有需要图片理解时才额外配置视觉模型。若要让检索请求生成答案,还需按部署能力配置对应的 chat 模型。模型服务和可选解析能力都受项目配置及部署能力约束,见模型与 AI 网关。
如果结果缺少预期内容,先确认文档已完成摄取,并检查解析和分块结果;修改解析器或分块参数后,需要重新摄取受影响的文档。检索结果的分数用于排序,不代替对来源原文的核对。
创建知识库
列表页点击 Create knowledge base,字段:
| 字段 | 规则 |
|---|---|
| Name / Description | 名称必填;描述可选 |
| Embedding model | 必选(仅列出具备 embedding 能力的 Provider 模型;未选无法提交) |
| Embedding dimension | 可选(1–65535):对所选模型探测校验,不匹配则创建失败 |
| Ingestion tracing | 可选开关:开启后记录摄取中间产物(解析 / 分块),供「知识库解析评估」使用;依赖平台管理员全局开关,开启后需重新摄取才有完整证据 |
| Image understanding | 开关 + 模型 + 提示词 + 最大并发(需项目已配置视觉模型 Provider) |
| Chunking parser | general / title / smart / regex / faq,及分块参数:chunkTokenNum(默认 512)、overlapPercent(默认 10)、titleLevel(默认 3)、minChunkTokens(默认 128)、delimiter、regexPattern |
解析配置只影响之后的摄取;历史文档要重新摄取才会应用新配置。
使用边界
- 图片理解要求项目级视觉模型 Provider;embedding 输入超限会显式失败。
- 模型与 embedding 调用使用项目在 Models 页配置的 Provider(见模型与 AI 网关)。
- 检索结果在 Observability 中的证据链与评估见可观测。
常见问题与排障(FAQ)
Q1:上传文档后接口返回了 HTTP 202,为什么立即调用检索接口还没有搜到该文档内容?
- 原因分析: HTTP
202表示摄取任务已成功入队并开始异步处理(经历文件读取 -> 解析器转换 -> 分块切分 -> 多模态图片解读 -> Embedding 向量化入库)。在异步任务尚未完成前,文档状态处于queued或processing,尚未写入可检索的ready向量索引。 - 解决措施: 请通过
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}检查摄取进度,待文档与作业状态变为 **ready** 后即可被检索命中。
Q2:启用 Rerank 后,上游限流是否会让检索失败?
取决于是否显式选择重排模型或 Provider。传入 rerankModel 或 rerankProviderRef 时,调用异常会返回给调用方;应修复模型配置、限流或服务故障。两者均未指定的自动重排采用尽力执行方式,失败可回退原排序,返回 reranked: false,此时不要把结果当作已精排。
allowDegraded 单独控制增强检索的可降级错误,不能用于忽略显式重排模型失败。单库响应的 capabilities 与 degradedCapabilities 描述增强能力状态;按业务是否接受基础结果选择该开关。
Q3:修改了知识库的默认分块参数(如 chunkTokenNum)或开启了图片理解后,已处于 ready 状态的存量文档会自动生效吗?
- 原因分析: 知识库的默认解析与分块策略(
indexingDefaults)及图片理解配置(imageUnderstanding)遵循快照隔离机制,修改后仅对之后新上传或新触发摄取的文档生效,不会静默改写线上已就绪的存量分块。 - 解决措施: 若需让存量文档应用新配置,可在 文档与摄取管理 列表中对单篇文档点击 重新摄取(Re-ingest),或在 知识库设置中心 点击 整库重建(Reindex)(
POST /v1/knowledgebases/{kbId}/reindex)。
Q4:词库(Lexicon)绑定在知识库上和绑定在智能体工作台上有什么区别?
- 原因分析: 知识库级词库绑定与智能体工作台级词库绑定处于不同的执行切面,分别服务于「RAG 召回与图谱消歧」与「对话入口合规阻断」。
- 解决措施:
- **绑定在知识库上(
/v1/knowledgebases/{kbId}/lexicons)**:对发往该知识库/search的查询自动执行同义词扩展(synonym)、追加词扩展(expansion)与停用词清洗(stop),并在开启graphrag: true时用于 GraphRAG 实体归一化(详见项目级词库治理)。 - **绑定在智能体工作台上(
/v1/agent-runtime/project/lexicons):不仅对工作台发起的 RAG 检索生效,还支持在对话入口层执行停用词/敏感词前置拦截(stopIntercept: true)**并直接返回预设拦截回复(stopReply),无需消耗大模型推理 Token。
- **绑定在知识库上(