AgentbaseDocs
文档目录

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


核心概念与架构

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

flowchart TB
    subgraph SettingsCenter["知识库设置中心 (PATCH /v1/knowledgebases/kb_enterprise_support)"]
        BasicLock["1. 基础信息与向量底座锁定\n• name / description (可热改)\n• knowledgeBaseId='kb_enterprise_support' (只读)\n• embeddingProviderRef='project:dashscope-prod' (锁定)\n• embeddingModel='text-embedding-v3', dimension=1024 (锁定)"]
        IndexDefs["2. 默认解析与分块策略 (indexingDefaults)\n• parser: text / mineru / vlm / office\n• chunkStrategy: general / title / smart / regex / faq\n• chunkTokenNum=512, overlapPercent=10, minChunkTokens=128\n• delimiter / regexPattern"]
        ImgVLM["3. 多模态图片理解 (imageUnderstanding)\n• enabled=true\n• providerRef='project:dashscope-prod', model='qwen-vl-max'\n• maxConcurrency=4 (1..16) + 自定义架构图解读 prompt"]
        RetrDefs["4. 默认检索与合成策略 (retrievalDefaults)\n• searchMode='hybrid', vectorWeight=0.7\n• topK=8, scoreThreshold=0.35\n• rerankModel='qwen3.7-text-rerank', answerModel='qwen-plus'"]
        TraceAndOps["5. 摄取可观测性与整库运维\n• ingestionTracing.tracingEnabled=true (OpenTelemetry Spans)\n• 整库重建 (POST /reindex) / 永久删除 (DELETE)"]
    end

    subgraph IngestionRuntime["摄取时生效边界 (Ingestion-Time, 快照隔离)"]
        NewDocs["新上传文档 / 语雀增量同步文档\n或显式触发 Re-ingest / POST /reindex 的存量文档"]
        OtelEval["可观测中心 (Observability)\n知识库解析追踪 Span 与解析质量评估"]
    end

    subgraph QueryRuntime["查询时即时生效边界 (Query-Time, 毫秒级热生效)"]
        OnlineSearch["单库与跨库检索 (POST /search)\n及智能体工作台 (Agent Runtime) 在线问答"]
    end

    IndexDefs & ImgVLM -->|配置快照注入| NewDocs
    TraceAndOps -->|开启 tracingEnabled| OtelEval
    TraceAndOps -->|触发整库重建| NewDocs
    RetrDefs & BasicLock -->|无需重建,立即生效| OnlineSearch

设置项变更生效机制对比(热生效 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(只读)<br/>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<br/>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<br/>Scope:knowledgebases.write为库内所有文档批量派发异步重新摄取任务,并将高级索引标记为 stale
永久删除知识库(Danger Zone)设置页底部危险操作区「删除知识库(Delete knowledge base)」DELETE /v1/knowledgebases/{kbId}knowledgeBase.delete() / delete_knowledge_base()角色:仅限 owner、admin<br/>Scope:knowledgebases.write级联清理 OceanBase 中的分块、向量、图谱、Wiki 及专属存储桶文件

功能详解与操作指南

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


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

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

配置项字段路径 (indexingDefaults.*)可选值 / 范围标杆生产配置值详细用途说明
默认文档解析器parser / documentParsertext / mineru / vlm / officetext(复杂 PDF 推荐 mineru)• text:原生文本/Markdown 极速提取<br/>• mineru:复杂 PDF 多栏版面、跨页表格与公式深度还原<br/>• vlm:整页交由视觉大模型解析<br/>• 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) 后,这些图片不再是检索盲区:

     请作为资深云原生与数据库架构师,详细提取图片中的系统架构组件名称、调用方向箭头、配置参数名、错误码(如 -4013 / -4024)、监控指标数值以及表格行列对应关系,输出高信息密度的结构化中文描述,切勿遗漏关键英文标识符。

四、配置默认检索与问答合成参数(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)与整库运维操作

完整的知识库设置更新与整库重建 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)却发现检索出来的分块还是原来的长度?


相关文档