Docs
Contents

Knowledge Base Settings Hub, Default Policies, and Multimodal Image Understanding (VLM)

This manual corresponds to Agentbase v2.10.0 (same version as the Console).

Knowledge base settings (Settings) is the high-stakes operations hub in Agentbase v2.10.0 for unified governance of knowledge bases (e.g., kb_enterprise_support): underlying vector space metadata, default parsing and chunking strategies (indexingDefaults), multimodal vision LLM image understanding (imageUnderstanding), default hybrid retrieval and grounded Q&A parameters (retrievalDefaults), ingestion observability tracing (ingestionTracing), as well as full knowledge base rebuild (reindex) and destruction. Through the Settings tab (/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/settings) on the knowledge base detail page, architects and administrators can smoothly evolve a knowledge base's parsing accuracy and online retrieval default baseline without modifying business caller code.


Feature overview and core scenarios

During the construction and long-term operation of an enterprise knowledge platform (such as project 企业智能客服与知识中台, ID: enterprise-ai-hub-210), documents uploaded by different teams come in complex and varied forms (including pure Markdown specifications as well as PDF/DOCX/PPTX manuals containing large numbers of system architecture diagrams, monitoring screenshots, and sequence diagrams), while multiple downstream business microservices and agent workspaces (Agent Runtime) all share and call this knowledge base. knowledge base Settings Center provides the following core capabilities around the four goals of "consolidated configuration, snapshot isolation, multimodal enhancement, and an observable closed loop":

  1. Basic metadata management and vector space immutability protection (Vector Space Immutability):

    • Supports updating the knowledge base display name (name) and business description (description) at any time.

    • Applies a strict read-only lock to the embeddingProviderRef (project:dashscope-prod), embeddingModel (text-embedding-v3), and embeddingDimension (1024) bound at creation time, eliminating at the source the OceanBase vector index cosine distance distortion caused by mixing different vector spaces or different dimensions.

  2. Default indexing and chunking strategies (indexingDefaults) and the snapshot isolation mechanism:

    • Centrally defines the default document parser (text / mineru / vlm / office), chunking strategy (general / title / smart / regex / faq), and fine-grained splitting parameters (chunkTokenNum = 512, overlapPercent = 10, delimiter, regexPattern, minChunkTokens = 128) applied when new documents enter the knowledge base.

    • Adopts a configuration snapshot isolation (Snapshot Isolation) design: after modifying indexingDefaults, changes only take effect for newly uploaded documents or those explicitly triggering re-ingestion, and never silently alters existing chunks already in the ready state in production.

  3. Multimodal image understanding (imageUnderstanding / VLM visual enhancement):

    • After enabling enabled: true and binding the vision large model project:dashscope-prodqwen-vl-max under it, the ingestion pipeline automatically decomposes embedded images in PDF, DOCX, PPTX, Excel, and Markdown, extracting architecture diagram components, topology flows, and text in error screenshots according to the configured concurrency (maxConcurrency: 1..16) and a custom vision prompt (prompt), then merges the generated semantic descriptions into the corresponding chunks to participate in vectorization and full-text search.

  4. Default retrieval and answer synthesis baseline (retrievalDefaults):

    • Uniformly configures the default searchMode (hybrid), vectorWeight (0.7), topK (8), scoreThreshold (0.35), reranking model (qwen3.7-text-rerank), and answer synthesis model (qwen-plus), so that minimal /search requests automatically inherit tuned production parameters.

  5. Ingestion observability tracing (ingestionTracing) and knowledge base-wide operations:

    • Supports enabling OpenTelemetry ingestion pipeline tracing (tracingEnabled: true), linked with the “knowledge base parsing quality assessment” in the observability center; provides one-click knowledge base-wide index rebuild (POST .../reindex) and a double-confirmed permanent knowledge base deletion (DELETE /v1/knowledgebases/{kbId}).


Core Concepts and Architecture

Architecture diagram of the five configuration domains of the knowledge base settings center and their upstream/downstream effect boundaries

Knowledge Base Settings Hub, Default Policies, and Multimodal Image Understanding (VLM): workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

Comparison of settings change effect mechanisms (hot effect vs. effect on new ingestion/rebuild)

Understanding which parameter modifications take effect immediately for production queries and which follow snapshot isolation (requiring re-ingestion to take effect) is central to production operations:

Configuration groupField pathWhether changes take effect immediately on existing dataProduction effect mechanism explanation
Basic informationname, descriptionTakes effect immediatelyOnly updates knowledge base metadata; does not affect underlying vectors or retrieval.
Vector foundationembeddingProviderRef, embeddingModel, embeddingDimensionCannot be modified after creationLocked at the project:dashscope-prod / text-embedding-v3 / 1024 dimension. Because OceanBase vector table column dimensions and semantic space are fixed, switching the embedding model requires creating a new knowledge base.
Default parsing and chunkingindexingDefaults.* (parser, chunkStrategy, chunkTokenNum, overlapPercent, delimiter, regexPattern, minChunkTokens)Takes effect only on new ingestion (snapshot isolation)After saving, existing document chunks in the ready state remain unchanged; newly uploaded documents automatically adopt the new default strategy. To apply the new chunking parameters uniformly across the whole knowledge base, you must invoke POST /v1/knowledgebases/{kbId}/reindex.
Multimodal image understandingimageUnderstanding.* (enabled, providerRef, model, maxConcurrency, prompt)Takes effect only on new ingestionImage decomposition and qwen-vl-max visual interpretation occur in the asynchronous document ingestion pipeline. After enabling or modifying prompt, performing “Re-ingest” on a target document containing images generates new image summaries.
Default retrieval and Q&AretrievalDefaults.* (searchMode, vectorWeight, topK, scoreThreshold, rerankModel, answerModel)Hot effect immediatelyThese are query-time default parameters. After saving, any production call that does not explicitly override the corresponding fields in the /search request body immediately adopts the new defaults.
Ingestion observability tracingingestionTracing.tracingEnabledTakes effect immediately for subsequent ingestion tasksOnce enabled, newly dispatched asynchronous ingestion tasks automatically write parsing and chunking Spans along with intermediate snapshots to OpenTelemetry.

Feature Entrypoints and Permission Matrix

Console entrypoint / feature moduleFrontend route pathCorresponding REST API endpointServer SDK method (Node.js / Python)Required RBAC role / API Key scopeCross-module dependency
Knowledge base → Settings center (view configuration)/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/settingsGET /v1/knowledgebases/{kbId}knowledgeBase.get() / get_knowledge_base()Roles: owner, admin, developer, member (read-only)
Scope: knowledgebases.read
Reads the associated dashscope-prod model status and storage bucket kb_enterprise_docs information
Update default parsing/chunking, VLM image understanding, default retrieval, and tracing configuration/console/.../kb-kb_enterprise_support/settings (the "Save" button in each group)PATCH /v1/knowledgebases/{kbId}knowledgeBase.update() / update_knowledge_base()Roles: owner, admin, developer
Scope: knowledgebases.write
Depends on models (LLM Gateway) where dashscope-prod is enabled qwen-vl-max, qwen3.7-text-rerank, qwen-plus
Trigger a full knowledge base ReindexThe "Reindex All" button on the settings page or document pagePOST /v1/knowledgebases/{kbId}/reindexknowledgeBase.reindex() / reindex_knowledge_base()Roles: owner, admin, developer
Scope: knowledgebases.write
Batch-dispatches asynchronous re-ingestion tasks for all documents in the knowledge base and marks the advanced index as stale
Permanently delete the knowledge base (Danger Zone)The danger zone "Delete knowledge base" at the bottom of the settings pageDELETE /v1/knowledgebases/{kbId}knowledgeBase.delete() / delete_knowledge_base()Roles: restricted to owner and admin
Scope: knowledgebases.write
Cascading cleanup of chunks, vectors, knowledge graph, Wiki, and dedicated storage bucket files in OceanBase

Feature Details and Operation Guide

Step One: View basic information and the vector foundation lock status

  1. Log in to the Console, go to project 企业智能客服与知识中台 (enterprise-ai-hub-210) -> knowledge base -> 企业智能客服与技术支持知识库 (kb_enterprise_support) -> and click the top Settings (Settings) tab.

  2. In the top General & Embedding Lock (General & Embedding Lock) card:

    • You can edit the name (name) (e.g., 企业智能客服与技术支持知识库) and description (description) at any time;

    • View the read-only locked vector space triple:

      • Knowledge base ID (knowledgeBaseId): kb_enterprise_support

      • Embedding model provider reference (embeddingProviderRef): project:dashscope-prod

      • Embedding model and dimension (embeddingModel / embeddingDimension): text-embedding-v3 (1024 dimensions, OceanBase Shared V2 HNSW vector index).


Step Two: Configure the default parsing and chunking strategy (indexingDefaults)

Scroll down to the default indexing and chunking strategy (Indexing Defaults) card to set standard chunking rules for documents uploaded or synchronized into the knowledge base later:

Configuration itemField path (indexingDefaults.*)Optional values / rangeBenchmark production configuration valueDetailed purpose description
Default document parserparser / documentParsertext / mineru / vlm / officetext (for complex PDFs, mineru is recommended)• text: ultra-fast extraction of native text/Markdown
• mineru: deep restoration of complex PDF multi-column layouts, cross-page tables, and formulas
• vlm: entire pages parsed by the vision large model
• office: structured extraction for Word/PPT/Excel
Default chunking strategychunkStrategy / chunkingParsergeneral / title / smart / regex / faqtitleFor technical whitepapers and troubleshooting manuals, splitting by title (heading hierarchy) or smart (intelligent semantic boundaries) is recommended
Target chunk sizechunkTokenNum64–4096 Tokens512Target token length of a single Chunk; must be smaller than the maximum input limit of text-embedding-v3
Adjacent chunk overlap ratiooverlapPercent0–50 (%)10Retains 10% (about 51 Tokens) of overlapping context between adjacent chunks to prevent cross-paragraph semantics from being cut off
Minimum merge chunk thresholdminChunkTokens16–1024 Tokens128In title or smart mode, short paragraphs under 128 Tokens are automatically merged with adjacent paragraphs
Custom separatordelimiterString (e.g., \n\n)"\n\n"In general mode, sentences are split by this separator first
Regex-based splitting patternregexPatternValid regular expressionConfigure as needed (required only in regex mode)In regex mode, splits standardized legal clauses or log blocks precisely at match boundaries

Snapshot isolation tip: After clicking Save, the system only updates the knowledge-base-level default template. If a particular document (such as "FAQ Summary Table.xlsx") needs to use the faq chunker separately, you can apply a local override when uploading that document or in the per-document settings of the Documents list; per-document configuration takes precedence over indexingDefaults.


Step Three: Enable multimodal image understanding (imageUnderstanding / VLM visual enhancement)

Enterprise technical documents (such as "Agentbase Enterprise Architecture Whitepaper.md" or the PDF version of "OceanBase Distributed Transactions and Vector Index Troubleshooting Guide") often contain large numbers of architecture topology diagrams, state machine flowcharts, and Console error screenshots. After enabling Image Understanding, these images are no longer retrieval blind spots:

  1. On the settings page, locate the multimodal image understanding (Image Understanding) card and turn on the enable image understanding (enabled) switch.

  2. Complete the vision model binding with the following benchmark parameters:

    • Vision model provider (providerRef): Select project:dashscope-prod (an Alibaba Cloud Bailian connection with the vlm capability already enabled in the LLM Gateway);

    • Vision large model (model): select qwen-vl-max;

    • Maximum image parsing concurrency (maxConcurrency): value range 1–16; a production value of 4 is recommended (i.e., at most 4 concurrent qwen-vl-max vision interpretation requests during single-document ingestion, balancing ingestion speed and upstream RPM quota safety);

    • Custom image interpretation prompt (prompt):

      请作为资深云原生与数据库架构师,详细提取图片中的系统架构组件名称、调用方向箭头、配置参数名、错误码(如 -4013 / -4024)、监控指标数值以及表格行列对应关系,输出高信息密度的结构化中文描述,切勿遗漏关键英文标识符。
  3. Click Save Configuration. From then on, when the document ingestion pipeline parses images embedded in PDF, DOCX, PPTX, Excel, or Markdown, it will automatically upload the image to the kb_enterprise_docs storage bucket, call qwen-vl-max to generate an accurate text description, anchor that description in the chunk of the paragraph containing the image, and vectorize it together.


Section Four: Configuring Default Retrieval and Q&A Synthesis Parameters (retrievalDefaults)

In the Default Retrieval and Q&A Settings (Retrieval Defaults) card, you can solidify the best parameters validated in the Search (Retrieval Testing) tab as knowledge-base-level defaults:

Configuration ItemField Path (retrievalDefaults.*)Benchmark Configuration ValueDescription and Value Range
Default retrieval modesearchMode"hybrid"Options: "hybrid" (hybrid vector + full-text), "vector" (pure vector), "fulltext" (pure full-text)
Default vector weightvectorWeight0.7Range 0.0–1.0. 0.7 means 70% semantic vector score + 30% full-text BM25 score
Default number of returned resultstopK / limit8Default Top-K number of returned chunks (range 1–50)
Default similarity thresholdscoreThreshold / similarityThreshold0.35Range 0.0–1.0; filters out low-relevance noise chunks scoring below 0.35
Default rerank modelrerankModel"qwen3.7-text-rerank"Binds the semantic rerank model under project:dashscope-prod
Default Q&A synthesis modelanswerModel / chatModel"qwen-plus"The default conversational model used to generate grounded answers when calling /search with answer: true

Section Five: Enabling Ingestion Observability Tracing (ingestionTracing) and Whole-Repository Operations

  1. Enable ingestion observability tracing (ingestionTracing.tracingEnabled: true):

    • In the Observability and Tracing (Ingestion Tracing) area, turn on the tracingEnabled switch and save.

    • Once enabled, each document ingestion's parsing duration, chunk boundary snapshots, image understanding call latency, and Embedding token consumption are written in standard OpenTelemetry Span format to the project observability center, supporting automated LLM-as-a-Judge scoring of knowledge base chunk quality in Observability → Evaluations.

  2. Run whole-repository reindex (POST /v1/knowledgebases/{kbId}/reindex):

    • When you have modified indexingDefaults (e.g., changed chunkTokenNum to 512) and want all 4 existing documents re-chunked with the new parameters, click Reindex All Documents.

  3. Permanently delete the knowledge base (DELETE /v1/knowledgebases/{kbId}):

    • In the Danger Zone at the bottom of the page, click Delete Knowledge Base, enter kb_enterprise_support in full in the confirmation dialog, and confirm deletion (irreversible operation).

Complete REST API Example for Knowledge Base Settings Updates and Whole-Repository Reindex

# 1. Update knowledge base global settings: default chunking strategy, multimodal image understanding (qwen-vl-max), default retrieval parameters and ingestion tracking (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. Trigger a full knowledge base reindex so that all existing documents apply the latest indexingDefaults and imageUnderstanding configuration (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 (Frequently Asked Questions and Troubleshooting)

Q1: Why can't I modify embeddingModel (text-embedding-v3) or embeddingDimension (1024) on the knowledge base settings page?

Q2: After enabling imageUnderstanding (qwen-vl-max) on the settings page and setting maxConcurrency to 16, why do some PDF documents containing many images occasionally ingest slowly or hit upstream 429 rate limiting?

Q3: Why did modifying retrievalDefaults.topK on the settings page (from 5 to 8) take effect online immediately, while after modifying indexingDefaults.chunkTokenNum (from 512 to 800) the retrieved chunks still have the original length?