知识库设置中心、默认策略与多模态图片理解(VLM)
本手册对应 Agentbase v2.10.0(控制台同版本)。
知识库设置(Settings) 是 Agentbase v2.10.0 知识库(如 kb_enterprise_support)统一管控底层向量空间元信息、默认解析与分块策略(indexingDefaults)、多模态视觉大模型图片理解(imageUnderstanding)、默认混合检索与接地问答参数(retrievalDefaults)、摄取可观测性追踪(ingestionTracing)以及整库重建(reindex)与销毁的高危运维中心。通过知识库详情页的 设置(Settings) 页签(/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/settings),架构师与管理员可以在不修改业务调用方代码的前提下,平滑演进知识库的解析精度与在线检索默认基线。
功能概述与核心场景
在企业级知识中台(如项目 企业智能客服与知识中台,ID:enterprise-ai-hub-210)的建设与长期运维过程中,不同团队上传的文档形态复杂多样(既有纯 Markdown 规范,也有内嵌大量系统架构图、监控截图与时序图的 PDF/DOCX/PPTX 手册),同时下游多个业务微服务与智能体工作台(Agent Runtime)都在共享调用该知识库。知识库设置中心 围绕「配置收口、快照隔离、多模态增强、可观测闭环」四大目标提供以下核心能力:
基础元信息管理与向量空间不可变保护(Vector Space Immutability):
支持随时更新知识库展示名称(
name)与业务描述(description)。对创建时绑定的
embeddingProviderRef(project:dashscope-prod)、embeddingModel(text-embedding-v3) 与embeddingDimension(1024) 实施严格的只读锁定,从根源上杜绝混用不同向量空间或不同维度导致的 OceanBase 向量索引余弦距离失真。
默认索引与分块策略(
indexingDefaults)及快照隔离机制:集中定义新文档入库时默认采用的文档解析器(
text/mineru/vlm/office)、分块策略(general/title/smart/regex/faq)及细粒度切分参数(chunkTokenNum = 512、overlapPercent = 10、delimiter、regexPattern、minChunkTokens = 128)。采用配置快照隔离(Snapshot Isolation)设计:修改
indexingDefaults后仅对新上传或显式触发重摄取的文档生效,绝不静默篡改线上已处于ready状态的存量分块。
多模态图片理解(
imageUnderstanding/ VLM 视觉增强):开启
enabled: true并绑定project:dashscope-prod下的视觉大模型qwen-vl-max后,摄取流水线会自动拆解 PDF、DOCX、PPTX、Excel 与 Markdown 中的内嵌图片,按设定的并发度(maxConcurrency: 1..16)与自定义视觉提示词(prompt)提取架构图组件、拓扑流向与报错截图文字,并将生成的语义描述合入对应分块参与向量化与全文检索。
默认检索与问答合成基线(
retrievalDefaults):统一配置缺省的
searchMode(hybrid)、vectorWeight(0.7)、topK(8)、scoreThreshold(0.35)、重排模型(qwen3.7-text-rerank)与答案合成模型(qwen-plus),让极简/search请求自动继承经过调优的生产参数。
摄取可观测性追踪(
ingestionTracing)与整库运维操作:支持开启 OpenTelemetry 摄取链路追踪(
tracingEnabled: true),联动可观测中心的「知识库解析质量评估」;提供一键整库重建索引(POST .../reindex)与双重确认的永久删除知识库(DELETE /v1/knowledgebases/{kbId})。
核心概念与架构
知识库设置中心五大配置域与上下游生效边界架构图
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
设置项变更生效机制对比(热生效 vs 新摄取/重建生效)
理解哪些参数修改后立即对线上查询生效、哪些参数遵循快照隔离(需重新摄取生效)是生产运维的核心:
| 配置分组 | 字段路径 | 修改后是否立即对存量数据生效 | 生产生效机制说明 |
|---|---|---|---|
| 基础信息 | name, description | 立即生效 | 仅更新知识库元数据,不影响底层向量与检索。 |
| 向量底座 | embeddingProviderRef, embeddingModel, embeddingDimension | 创建后不可修改 | 锁死在 project:dashscope-prod / text-embedding-v3 / 1024 维。因为 OceanBase 向量表列维度与语义空间固定,更换向量模型必须新建知识库。 |
| 默认解析与分块 | indexingDefaults.*(parser, chunkStrategy, chunkTokenNum, overlapPercent, delimiter, regexPattern, minChunkTokens) | 仅对新摄取生效(快照隔离) | 保存后,已处于 ready 状态的存量文档分块保持原样不变;新上传文档自动采用新默认策略。若需全库统一应用新分块参数,须调用 POST /v1/knowledgebases/{kbId}/reindex。 |
| 多模态图片理解 | imageUnderstanding.*(enabled, providerRef, model, maxConcurrency, prompt) | 仅对新摄取生效 | 图片拆解与 qwen-vl-max 视觉解读发生在文档异步摄取流水线中。开启或修改 prompt 后,对目标含图文档执行「重新摄取(Re-ingest)」即可生成新图片摘要。 |
| 默认检索与问答 | retrievalDefaults.*(searchMode, vectorWeight, topK, scoreThreshold, rerankModel, answerModel) | 立即热生效 | 属于查询期(Query-Time)缺省参数。保存后,任何未在 /search 请求体中显式覆盖对应字段的线上调用立即采用新默认值。 |
| 摄取可观测追踪 | ingestionTracing.tracingEnabled | 对后续摄取任务立即生效 | 开启后,新派发的异步摄取任务会自动向 OpenTelemetry 写入解析与分块 Span 及中间快照。 |
功能入口与权限矩阵
| 控制台入口 / 功能模块 | 前端路由路径 | 对应 REST API 端点 | Server SDK 方法(Node.js / Python) | 所需 RBAC 角色 / API Key Scope | 跨模块依赖关系 |
|---|---|---|---|---|---|
| 知识库 → 设置中心(查看配置) | /console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/settings | GET /v1/knowledgebases/{kbId} | knowledgeBase.get() / get_knowledge_base() | 角色:owner、admin、developer、member(只读)Scope: knowledgebases.read | 读取关联的 dashscope-prod 模型状态与存储桶 kb_enterprise_docs 信息 |
| 更新默认解析/分块、VLM 图片理解、默认检索与追踪配置 | /console/.../kb-kb_enterprise_support/settings(各分组「保存 Save」按钮) | PATCH /v1/knowledgebases/{kbId} | knowledgeBase.update() / update_knowledge_base() | 角色:owner、admin、developerScope: knowledgebases.write | 依赖 模型(LLM Gateway) 中 dashscope-prod 已启用 qwen-vl-max、qwen3.7-text-rerank、qwen-plus |
| 触发整库重建索引(Reindex) | 设置页或文档页「整库重建索引(Reindex All)」按钮 | POST /v1/knowledgebases/{kbId}/reindex | knowledgeBase.reindex() / reindex_knowledge_base() | 角色:owner、admin、developerScope: knowledgebases.write | 为库内所有文档批量派发异步重新摄取任务,并将高级索引标记为 stale |
| 永久删除知识库(Danger Zone) | 设置页底部危险操作区「删除知识库(Delete knowledge base)」 | DELETE /v1/knowledgebases/{kbId} | knowledgeBase.delete() / delete_knowledge_base() | 角色:仅限 owner、adminScope: knowledgebases.write | 级联清理 OceanBase 中的分块、向量、图谱、Wiki 及专属存储桶文件 |
功能详解与操作指南
一、查看基础信息与向量底座锁定状态
登录控制台,进入项目
企业智能客服与知识中台 (enterprise-ai-hub-210)-> 知识库 ->企业智能客服与技术支持知识库 (kb_enterprise_support)-> 点击顶部 设置(Settings) 页签。在顶部的 基础信息与向量模型(General & Embedding Lock) 卡片中:
可随时编辑 名称(
name)(如企业智能客服与技术支持知识库)与 描述(description);查看只读锁定的向量空间三元组:
知识库 ID(
knowledgeBaseId):kb_enterprise_support向量模型提供商引用(
embeddingProviderRef):project:dashscope-prod向量模型与维度(
embeddingModel/embeddingDimension):text-embedding-v3(1024维,OceanBaseShared V2HNSW 向量索引)。
二、配置默认解析与分块策略(indexingDefaults)
向下滚动至 默认索引与分块策略(Indexing Defaults) 卡片,可为后续上传或同步入库的文档设定标准切片规则:
| 配置项 | 字段路径 (indexingDefaults.*) | 可选值 / 范围 | 标杆生产配置值 | 详细用途说明 |
|---|---|---|---|---|
| 默认文档解析器 | parser / documentParser | text / mineru / vlm / office | text(复杂 PDF 推荐 mineru) | • text:原生文本/Markdown 极速提取• mineru:复杂 PDF 多栏版面、跨页表格与公式深度还原• vlm:整页交由视觉大模型解析• office:针对 Word/PPT/Excel 结构化提取 |
| 默认分块策略 | chunkStrategy / chunkingParser | general / title / smart / regex / faq | title | 技术白皮书与排障手册推荐按 title(标题层级)或 smart(智能语义边界)切分 |
| 目标分块大小 | chunkTokenNum | 64~4096 Tokens | 512 | 单个 Chunk 的目标 Token 长度,须小于 text-embedding-v3 的最大输入限制 |
| 相邻分块重叠率 | overlapPercent | 0~50(%) | 10 | 相邻分块之间保留 10%(约 51 Tokens)的重叠上下文,防止跨段语义被切断 |
| 最小合并分块阈值 | minChunkTokens | 16~1024 Tokens | 128 | 在 title 或 smart 模式下,不足 128 Tokens 的短小段落会自动与相邻段落合并 |
| 自定义分隔符 | delimiter | 字符串(如 \n\n) | "\n\n" | 在 general 模式下优先按该分隔符断句 |
| 正则表达式切分式 | regexPattern | 合法正则表达式 | 按需配置(仅 regex 模式必填) | 在 regex 模式下按匹配边界精确切分标准化法条或日志块 |
快照隔离提示:点击 保存 后,系统仅更新知识库级默认模板。若某篇特殊文档(如《常问 FAQ 汇总表.xlsx》)需要单独使用
faq分块器,可在上传该文档时或在 文档(Documents) 列表单篇设置中局部覆盖,单篇配置优先级高于indexingDefaults。
三、开启多模态图片理解(imageUnderstanding / VLM 视觉增强)
企业技术文档(如《Agentbase企业架构白皮书.md》或 PDF 版《OceanBase分布式事务与向量索引排障指南》)中往往包含大量架构拓扑图、状态机流程图与控制台报错截图。开启 多模态图片理解(Image Understanding) 后,这些图片不再是检索盲区:
在设置页找到 多模态图片理解(Image Understanding) 卡片,打开 启用图片理解(
enabled) 开关。按照以下标杆参数完成视觉模型绑定:
视觉模型提供商(
providerRef):选择project:dashscope-prod(已在 LLM Gateway 中启用vlm能力的阿里云百炼连接);视觉大模型(
model):选择qwen-vl-max;最大图片解析并发数(
maxConcurrency):取值范围1~16,生产推荐设置为4(即单篇文档摄取时最多同时发起 4 路qwen-vl-max视觉解读请求,兼顾摄取速度与上游 RPM 配额安全);自定义图片解读提示词(
prompt):请作为资深云原生与数据库架构师,详细提取图片中的系统架构组件名称、调用方向箭头、配置参数名、错误码(如 -4013 / -4024)、监控指标数值以及表格行列对应关系,输出高信息密度的结构化中文描述,切勿遗漏关键英文标识符。
点击 保存配置。此后,当文档摄取流水线解析 PDF、DOCX、PPTX、Excel 或 Markdown 内嵌图片时,会自动把图片上传至
kb_enterprise_docs存储桶,调用qwen-vl-max生成精准的文字描述,并将该描述锚定在图片所在段落的分块(Chunk)中一并向量化。
四、配置默认检索与问答合成参数(retrievalDefaults)
在 默认检索与问答设置(Retrieval Defaults) 卡片中,可将在 检索测试(Search) 页签验证通过的最佳参数固化为知识库级默认值:
| 配置项 | 字段路径 (retrievalDefaults.*) | 标杆配置值 | 说明与取值范围 |
|---|---|---|---|
| 默认检索模式 | searchMode | "hybrid" | 可选 "hybrid"(向量+全文混合)、"vector"(纯向量)、"fulltext"(纯全文) |
| 默认向量权重 | vectorWeight | 0.7 | 范围 0.0~1.0。0.7 代表 70% 语义向量得分 + 30% 全文 BM25 得分 |
| 默认返回条数 | topK / limit | 8 | 缺省返回的 Top-K 分块数量(范围 1~50) |
| 默认相似度阈值 | scoreThreshold / similarityThreshold | 0.35 | 范围 0.0~1.0,过滤低于 0.35 的低相关噪声分块 |
| 默认重排模型 | rerankModel | "qwen3.7-text-rerank" | 绑定 project:dashscope-prod 下的语义重排模型 |
| 默认问答合成模型 | answerModel / chatModel | "qwen-plus" | 当调用 /search 传入 answer: true 时,默认用于生成接地回答的对话模型 |
五、开启摄取可观测性追踪(ingestionTracing)与整库运维操作
开启摄取可观测性追踪(
ingestionTracing.tracingEnabled: true):在 可观测性与追踪(Ingestion Tracing) 区域,打开
tracingEnabled开关并保存。开启后,每次文档摄取的解析耗时、分块边界快照、图片理解调用延迟与 Embedding Token 消耗均以标准 OpenTelemetry Span 格式写入项目可观测中心,支持在 可观测 → 评估(Evaluations) 中对知识库分块质量执行自动化 LLM-as-a-Judge 评分。
执行整库重建索引(
POST /v1/knowledgebases/{kbId}/reindex):当您修改了
indexingDefaults(如将chunkTokenNum调整为512)并希望存量的 4 篇文档全部按新参数重新切分时,点击 整库重建索引(Reindex All Documents)。
永久删除知识库(
DELETE /v1/knowledgebases/{kbId}):在页面底部 危险操作区(Danger Zone) 点击 删除知识库,在二次确认框中完整输入
kb_enterprise_support后确认删除(不可逆操作)。
完整的知识库设置更新与整库重建 REST API 示例
# 1. 更新知识库全局设置:默认分块策略、多模态图片理解 (qwen-vl-max)、默认检索参数与摄取追踪 (PATCH /v1/knowledgebases/{kbId})
curl -X PATCH "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "企业智能客服与技术支持知识库",
"description": "沉淀架构白皮书、客服 SOP、OceanBase 向量排障与 AI 网关规范",
"indexingDefaults": {
"parser": "text",
"chunkStrategy": "title",
"chunkTokenNum": 512,
"overlapPercent": 10,
"minChunkTokens": 128,
"delimiter": "\n\n"
},
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"prompt": "请详细提取架构图、流程图与报错截图中的组件名称、参数、错误码与调用关系。"
},
"retrievalDefaults": {
"searchMode": "hybrid",
"vectorWeight": 0.7,
"topK": 8,
"scoreThreshold": 0.35,
"rerankModel": "qwen3.7-text-rerank",
"answerModel": "qwen-plus"
},
"ingestionTracing": {
"tracingEnabled": true
}
}'
# 2. 触发整库重建索引,使存量全部文档应用最新的 indexingDefaults 与 imageUnderstanding 配置 (POST /v1/knowledgebases/{kbId}/reindex)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/reindex" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"常见问题与排障(FAQ)
Q1:为什么在知识库设置页无法修改 embeddingModel(text-embedding-v3)或 embeddingDimension(1024)?
原因分析: 知识库在创建时会在底层 OceanBase
Shared V2数据库中初始化固定维度(如VECTOR(1024))的向量列与 HNSW 索引结构。不同 Embedding 模型(或同一模型的不同维度输出)处于完全不兼容的数学特征空间,若允许中途修改向量模型,会导致新旧文档向量在余弦距离计算时产生毫无意义的错乱排序。解决措施: 向量底座遵循创建后不可变(Immutable Vector Space)原则。如果企业决定从
1024维模型迁移至其他维度的向量模型,请新建一个知识库实例并重新导入文档,测试验证通过后在 智能体工作台(Agent Runtime) 中原子切换挂载的知识库 ID。
Q2:在设置页开启了 imageUnderstanding(qwen-vl-max)并将 maxConcurrency 设为 16 后,为什么部分含大量图片的 PDF 文档在摄取时偶发变慢或报上游 429 限流?
原因分析:
maxConcurrency控制单个文档摄取任务同时向project:dashscope-prod发起qwen-vl-max视觉推理请求的并发线程数(上限为16)。如果批量上传多篇含数十张高清截图的 PDF 文档,且每篇并发度均设为16,瞬时叠加的多模态并发请求可能触达上游 DashScope 账号的 RPM/TPM 速率上限。解决措施:
建议在生产环境中将
imageUnderstanding.maxConcurrency调整为稳健的4~8;前往 模型与 AI 网关 → 统一 AI 网关 检查是否配置了多密钥负载均衡或提升上游百炼账号的
qwen-vl-max并发配额,然后对受影响的文档点击 重新摄取(Re-ingest)。
Q3:为什么修改了设置页的 retrievalDefaults.topK(从 5 改为 8)立即在线上生效了,而修改了 indexingDefaults.chunkTokenNum(从 512 改为 800)却发现检索出来的分块还是原来的长度?
原因分析: 这是因为两类参数处于不同的生命周期阶段:
retrievalDefaults属于查询期(Query-Time)缺省参数,每次执行/search时实时读取,因此保存后毫秒级热生效;indexingDefaults属于摄取期(Ingestion-Time)默认模板,受快照隔离保护,修改后不会自动销毁或重切已经入库的存量ready分块。
解决措施: 若希望存量文档也按照新的
chunkTokenNum = 800重新切分,请在保存indexingDefaults后,点击设置页或文档页的 整库重建索引(POST /v1/knowledgebases/{kbId}/reindex)(生产环境建议先在 版本管理 Versions 中创建DRAFT工作副本,在副本内执行重建并验证无误后再封存发布)。
