Docs
文档目录

知识库设置中心、默认策略与多模态图片理解(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)都在共享调用该知识库。知识库设置中心 围绕「配置收口、快照隔离、多模态增强、可观测闭环」四大目标提供以下核心能力:

  1. 基础元信息管理与向量空间不可变保护(Vector Space Immutability):

    • 支持随时更新知识库展示名称(name)与业务描述(description)。

    • 对创建时绑定的 embeddingProviderRef(project:dashscope-prod)、embeddingModel(text-embedding-v3) 与 embeddingDimension(1024) 实施严格的只读锁定,从根源上杜绝混用不同向量空间或不同维度导致的 OceanBase 向量索引余弦距离失真。

  2. 默认索引与分块策略(indexingDefaults)及快照隔离机制:

    • 集中定义新文档入库时默认采用的文档解析器(text / mineru / vlm / office)、分块策略(general / title / smart / regex / faq)及细粒度切分参数(chunkTokenNum = 512、overlapPercent = 10、delimiter、regexPattern、minChunkTokens = 128)。

    • 采用配置快照隔离(Snapshot Isolation)设计:修改 indexingDefaults 后仅对新上传或显式触发重摄取的文档生效,绝不静默篡改线上已处于 ready 状态的存量分块。

  3. 多模态图片理解(imageUnderstanding / VLM 视觉增强):

    • 开启 enabled: true 并绑定 project:dashscope-prod 下的视觉大模型 qwen-vl-max 后,摄取流水线会自动拆解 PDF、DOCX、PPTX、Excel 与 Markdown 中的内嵌图片,按设定的并发度(maxConcurrency: 1..16)与自定义视觉提示词(prompt)提取架构图组件、拓扑流向与报错截图文字,并将生成的语义描述合入对应分块参与向量化与全文检索。

  4. 默认检索与问答合成基线(retrievalDefaults):

    • 统一配置缺省的 searchMode(hybrid)、vectorWeight(0.7)、topK(8)、scoreThreshold(0.35)、重排模型(qwen3.7-text-rerank)与答案合成模型(qwen-plus),让极简 /search 请求自动继承经过调优的生产参数。

  5. 摄取可观测性追踪(ingestionTracing)与整库运维操作:

    • 支持开启 OpenTelemetry 摄取链路追踪(tracingEnabled: true),联动可观测中心的「知识库解析质量评估」;提供一键整库重建索引(POST .../reindex)与双重确认的永久删除知识库(DELETE /v1/knowledgebases/{kbId})。


核心概念与架构

知识库设置中心五大配置域与上下游生效边界架构图

知识库设置中心、默认策略与多模态图片理解(VLM):流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

设置项变更生效机制对比(热生效 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/settingsGET /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、developer
Scope:knowledgebases.write
依赖 模型(LLM Gateway) 中 dashscope-prod 已启用 qwen-vl-max、qwen3.7-text-rerank、qwen-plus
触发整库重建索引(Reindex)设置页或文档页「整库重建索引(Reindex All)」按钮POST /v1/knowledgebases/{kbId}/reindexknowledgeBase.reindex() / reindex_knowledge_base()角色:owner、admin、developer
Scope:knowledgebases.write
为库内所有文档批量派发异步重新摄取任务,并将高级索引标记为 stale
永久删除知识库(Danger Zone)设置页底部危险操作区「删除知识库(Delete knowledge base)」DELETE /v1/knowledgebases/{kbId}knowledgeBase.delete() / delete_knowledge_base()角色:仅限 owner、admin
Scope:knowledgebases.write
级联清理 OceanBase 中的分块、向量、图谱、Wiki 及专属存储桶文件

功能详解与操作指南

一、查看基础信息与向量底座锁定状态

  1. 登录控制台,进入项目 企业智能客服与知识中台 (enterprise-ai-hub-210) -> 知识库 -> 企业智能客服与技术支持知识库 (kb_enterprise_support) -> 点击顶部 设置(Settings) 页签。

  2. 在顶部的 基础信息与向量模型(General & Embedding Lock) 卡片中:

    • 可随时编辑 名称(name)(如 企业智能客服与技术支持知识库)与 描述(description);

    • 查看只读锁定的向量空间三元组:

      • 知识库 ID(knowledgeBaseId):kb_enterprise_support

      • 向量模型提供商引用(embeddingProviderRef):project:dashscope-prod

      • 向量模型与维度(embeddingModel / embeddingDimension):text-embedding-v3(1024 维,OceanBase Shared V2 HNSW 向量索引)。


二、配置默认解析与分块策略(indexingDefaults)

向下滚动至 默认索引与分块策略(Indexing Defaults) 卡片,可为后续上传或同步入库的文档设定标准切片规则:

配置项字段路径 (indexingDefaults.*)可选值 / 范围标杆生产配置值详细用途说明
默认文档解析器parser / documentParsertext / mineru / vlm / officetext(复杂 PDF 推荐 mineru)• text:原生文本/Markdown 极速提取
• mineru:复杂 PDF 多栏版面、跨页表格与公式深度还原
• vlm:整页交由视觉大模型解析
• office:针对 Word/PPT/Excel 结构化提取
默认分块策略chunkStrategy / chunkingParsergeneral / title / smart / regex / faqtitle技术白皮书与排障手册推荐按 title(标题层级)或 smart(智能语义边界)切分
目标分块大小chunkTokenNum64~4096 Tokens512单个 Chunk 的目标 Token 长度,须小于 text-embedding-v3 的最大输入限制
相邻分块重叠率overlapPercent0~50(%)10相邻分块之间保留 10%(约 51 Tokens)的重叠上下文,防止跨段语义被切断
最小合并分块阈值minChunkTokens16~1024 Tokens128在 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) 后,这些图片不再是检索盲区:

  1. 在设置页找到 多模态图片理解(Image Understanding) 卡片,打开 启用图片理解(enabled) 开关。

  2. 按照以下标杆参数完成视觉模型绑定:

    • 视觉模型提供商(providerRef):选择 project:dashscope-prod(已在 LLM Gateway 中启用 vlm 能力的阿里云百炼连接);

    • 视觉大模型(model):选择 qwen-vl-max;

    • 最大图片解析并发数(maxConcurrency):取值范围 1~16,生产推荐设置为 4(即单篇文档摄取时最多同时发起 4 路 qwen-vl-max 视觉解读请求,兼顾摄取速度与上游 RPM 配额安全);

    • 自定义图片解读提示词(prompt):

      请作为资深云原生与数据库架构师,详细提取图片中的系统架构组件名称、调用方向箭头、配置参数名、错误码(如 -4013 / -4024)、监控指标数值以及表格行列对应关系,输出高信息密度的结构化中文描述,切勿遗漏关键英文标识符。
  3. 点击 保存配置。此后,当文档摄取流水线解析 PDF、DOCX、PPTX、Excel 或 Markdown 内嵌图片时,会自动把图片上传至 kb_enterprise_docs 存储桶,调用 qwen-vl-max 生成精准的文字描述,并将该描述锚定在图片所在段落的分块(Chunk)中一并向量化。


四、配置默认检索与问答合成参数(retrievalDefaults)

在 默认检索与问答设置(Retrieval Defaults) 卡片中,可将在 检索测试(Search) 页签验证通过的最佳参数固化为知识库级默认值:

配置项字段路径 (retrievalDefaults.*)标杆配置值说明与取值范围
默认检索模式searchMode"hybrid"可选 "hybrid"(向量+全文混合)、"vector"(纯向量)、"fulltext"(纯全文)
默认向量权重vectorWeight0.7范围 0.0~1.0。0.7 代表 70% 语义向量得分 + 30% 全文 BM25 得分
默认返回条数topK / limit8缺省返回的 Top-K 分块数量(范围 1~50)
默认相似度阈值scoreThreshold / similarityThreshold0.35范围 0.0~1.0,过滤低于 0.35 的低相关噪声分块
默认重排模型rerankModel"qwen3.7-text-rerank"绑定 project:dashscope-prod 下的语义重排模型
默认问答合成模型answerModel / chatModel"qwen-plus"当调用 /search 传入 answer: true 时,默认用于生成接地回答的对话模型

五、开启摄取可观测性追踪(ingestionTracing)与整库运维操作

  1. 开启摄取可观测性追踪(ingestionTracing.tracingEnabled: true):

    • 在 可观测性与追踪(Ingestion Tracing) 区域,打开 tracingEnabled 开关并保存。

    • 开启后,每次文档摄取的解析耗时、分块边界快照、图片理解调用延迟与 Embedding Token 消耗均以标准 OpenTelemetry Span 格式写入项目可观测中心,支持在 可观测 → 评估(Evaluations) 中对知识库分块质量执行自动化 LLM-as-a-Judge 评分。

  2. 执行整库重建索引(POST /v1/knowledgebases/{kbId}/reindex):

    • 当您修改了 indexingDefaults(如将 chunkTokenNum 调整为 512)并希望存量的 4 篇文档全部按新参数重新切分时,点击 整库重建索引(Reindex All Documents)。

  3. 永久删除知识库(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)?

Q2:在设置页开启了 imageUnderstanding(qwen-vl-max)并将 maxConcurrency 设为 16 后,为什么部分含大量图片的 PDF 文档在摄取时偶发变慢或报上游 429 限流?

Q3:为什么修改了设置页的 retrievalDefaults.topK(从 5 改为 8)立即在线上生效了,而修改了 indexingDefaults.chunkTokenNum(从 512 改为 800)却发现检索出来的分块还是原来的长度?


相关文档