Docs
Contents

Knowledge Base Overview

Knowledge Base is the end-to-end retrieval-augmented generation (RAG) engine built by Agentbase for enterprise unstructured and semi-structured knowledge assets. Through the Knowledge Base entry in the left navigation of the Console, enterprises can uniformly ingest Markdown, PDF, Office documents, Excel spreadsheets, and data from Yuque external spaces into the knowledge base, combining Lexicon synonym and stopword governance, multi-way hybrid retrieval (searchMode=hybrid), semantic reranking (Rerank), advanced derived indexes (GraphRAG, RAPTOR, LLM Wiki), and immutable version management, providing a highly accurate, traceable enterprise knowledge foundation for the Agent Runtime and business applications.


Feature overview and core scenarios

In enterprise intelligent customer service and technical support scenarios (e.g., project 企业智能客服与知识中台, ID: enterprise-ai-hub-210), traditional single-path vector retrieval often faces challenges such as missed retrieval of proper nouns, difficulty summarizing cross-section global questions, and online fluctuations caused by knowledge updates. The Agentbase knowledge base provides an end-to-end workflow:

  1. Multimodal rich document asynchronous ingestion and precise chunking:

    • Supports local batch upload, file binding from Storage buckets (e.g., kb_enterprise_docs), and incremental synchronization of Yuque data sources.

    • Includes three built-in document parsers—text, vlm (vision large model parsing), and mineru (complex PDF layout/formula/table restoration)—as well as five chunking strategies: general, title, smart, regex, and faq.

    • Document ingestion uses an asynchronous task mechanism: the ingestion trigger API returns HTTP 202 status code, and check the ingestion job and document separately. Search only after both are ready and the document activeGeneration matches the job generation.

  2. Project-level Lexicon collaborative governance:

    • Supports creating synonym/expansion term dictionaries (e.g., lex_enterprise_synonyms) and stopword/blocklist dictionaries (e.g., lex_support_stopwords), which can be bound with one click to the knowledge base (kb_enterprise_support) and the Agent Runtime, automatically completing business jargon rewriting, synonym expansion, and blocking of violating questions before retrieval.

  3. Multi-way hybrid retrieval and resilient reranking (Hybrid Search & Rerank):

    • Supports three searchMode modes: hybrid (hybrid retrieval), vector (vector retrieval), and fulltext (full-text retrieval); the fusion ratio of vector and full-text scores can be finely tuned via vectorWeight.

    • Reranking can be optionally enabled; when explicit rerankModel or rerankProviderRef calls fail, an error is returned; if automatic reranking fails when neither is specified, the system can fall back and return reranked: false. The per-library allowDegraded controls degradable errors of enhanced indexes; answer=true synthesizes answers using retrieval evidence, and readers still need to verify sources.

  4. Three major advanced derived indexes (GraphRAG / RAPTOR / Wiki):

    • Automatically builds an entity-relationship knowledge graph (GraphRAG), a hierarchical recursive clustering summary tree (RAPTOR), and structured encyclopedia pages (Wiki, e.g., automatically compiling and generating 10 technical support encyclopedia pages) based on ready (ready) document chunks.

  5. Immutable version publishing and Agent Runtime linkage:

    • Supports draft working copies (Draft), readiness gate validation (Readiness Gate), sealing (Seal), publishing (Publish), and one-click rollback (Rollback), and allows directly mounting knowledge bases and lexicons in the Agent Runtime for multi-turn interactive Q&A.


Core Concepts and Architecture

Enterprise End-to-End RAG and Knowledge Governance Architecture Diagram

Knowledge Base Overview: 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

Core Concepts and Terminology Table

Core ConceptKey Fields / API IdentifiersDetailed Description
Knowledge base instanceknowledgeBaseIdThe top-level container for knowledge documents, chunks, vector indexes, derived knowledge graphs, and version snapshots (e.g., kb_enterprise_support). A unique Embedding model (text-embedding-v3, 1024 dimensions) is bound at creation time.
Asynchronous ingestion jobingestionId / HTTP 202The asynchronous ingestion pipeline record created when ingestion or a rebuild is triggered. The ingestion API returns 202 Accepted, and in the background it goes through parsing, chunking, image understanding, and vectorization, ultimately setting the document status to ready.
Document locator identifierdocumentTag / subProductIdPrecise filtering metadata introduced in v2.10.0. The documentTag format is {subProductId}_{sectionCode}_{fileKey}, supporting precise filtering in document lists, single-library/cross-library retrieval, and Wiki conflict lists.
LexiconlexiconIdA project-level vocabulary governance component that supports synonyms (synonym), expansion terms (expansion), and stopwords (stop). It can be bound to both the knowledge base and the Agent Runtime.
Retrieval modesearchModeSupports hybrid (default, vector + full-text hybrid retrieval), vector (pure semantic vector retrieval), and fulltext (keyword full-text retrieval).
Hybrid vector weightvectorWeightUnder searchMode=hybrid, controls the weighting ratio between vector similarity scores and full-text BM25 scores (value range 0.0–1.0; e.g., 0.7 means 70% vector weight + 30% full-text weight).
Enhanced retrieval degradationallowDegradedPer-library default is true; when GraphRAG / RAPTOR / Wiki encounters a degradable error, normal results are preserved and recorded via capabilities / degradedCapabilities. When set to false, related errors are returned to the caller.
Derived knowledge indexesgraphrag / raptor / wikiThree types of advanced index capabilities built on top of the base Chunk vector index, addressing multi-hop entity-relationship reasoning, cross-document macro summarization, and structured encyclopedia consolidation respectively.

Feature Entrypoints and Permission Matrix

Master Table of Ten Submodule Navigation, REST APIs, and Permission Matrix

Submodule NameManual Chapter LinkFrontend Console Route PathCore REST API EndpointServer SDK Methods (Node.js / Python)Required RBAC Roles / API Key ScopeCross-Module Dependencies
Knowledge Base Overview and Instance Managementoverview.md/console/project-default-enterprise-ai-hub-210/knowledge-baseGET/POST /v1/knowledgebasesknowledgeBase.list() / create()owner, admin, developer (read-only members view only)
Scope:knowledgebases.read / write
Requires an available embedding model in the project; use the configured model and dimensions
Document and Asynchronous Ingestion Managementdocuments.md/console/.../kb-kb_enterprise_support/documentsPOST /v1/knowledgebases/{kbId}/documents
GET .../ingestions/{ingestionId}
knowledgeBase.createDocument()
getIngestion()
owner, admin, developer
Scope:knowledgebases.write
Uses the knowledge base default bucket or a specified accessible bucket, and a selected parser
External Data Sources and Yuque Synchronizationdatasources.md/console/.../kb-kb_enterprise_support/datasourcesPOST .../yuque/personal-datasources
POST .../datasources/{id}/syncs
Use the console or a user session for personal sources; see the SDK reference for team syncPersonal sources require a user session or JWT; knowledgebases.writeAutomatically triggers ingestion after synchronization and marks derived indexes as stale (data_source_sync)
Advanced Knowledge Index Build Governanceindexing.md/console/.../kb-kb_enterprise_support/indexesGET/PATCH .../index-capabilities/{cap}
POST .../index-operations
knowledgeBase.updateIndexCapability()
createIndexOperation()
owner, admin, developer
Scope:knowledgebases.write
Required models and build prerequisites depend on the index type; see the indexing guide
Knowledge Graph Visualization and Community Reportsgraph.md/console/.../kb-kb_enterprise_support/graphGET .../graph
GET .../graph/entities/{id}/neighbors
GET .../graph/community-reports
knowledgeBase.getGraph()
getGraphEntityNeighbors()
listGraphCommunityReports()
owner, admin, developer, member
Scope:knowledgebases.read
Depends on GraphRAG build readiness; enables useKnowledgeGraph: true multi-hop retrieval
Knowledge Base Wiki Compilation and Governancewiki.md/console/.../kb-kb_enterprise_support/wikiGET/POST .../wiki/pages
GET .../wiki/conflicts
POST .../export-to-memory
knowledgeBase.listWikiPages()
resolveWikiConflict()
exportWikiPageToMemory()
owner, admin, developer
Scope:knowledgebases.write
Links with version management (Versions) seal gates and memory export
Hybrid Retrieval and Q&A Debuggingsearch.md/console/.../kb-kb_enterprise_support/searchPOST /v1/knowledgebases/{kbId}/search
POST /v1/knowledgebases/search
createSearch() / create_search()
createMultiSearch() / create_multi_search()
owner, admin, developer, member
Scope:knowledgebases.read
Optional reranking and answer generation depend on the configured retrieval settings
Immutable Version Management and Rollbackversions.md/console/.../kb-kb_enterprise_support/versionsPOST .../version-adoptions
POST .../versions/{id}/seal
POST .../publish & rollback
knowledgeBase.createVersion()
sealVersion()
publishVersion()
owner, admin (and authorized publishers)
Scope:knowledgebases.write
Isolates draft (DRAFT) from online active version (Current) via copy-on-write
Project-Level Lexicon and Multi-Endpoint Bindinglexicons.md/console/.../knowledge-base/lexicons
/console/.../kb-kb_enterprise_support/lexicons
GET/POST /v1/lexicons
PUT .../kb_enterprise_support/lexicons
knowledgeBase.createLexicon()
updateKnowledgeBaseLexicons()
owner, admin, developer
Scope:lexicons.write
native-v1 The tokenizer simultaneously powers retrieval rewriting, GraphRAG disambiguation, and agents stopIntercept
Knowledge Base Settings and Multimodal VLMsettings.md/console/.../kb-kb_enterprise_support/settingsPATCH /v1/knowledgebases/{kbId}
POST /v1/knowledgebases/{kbId}/reindex
knowledgeBase.update()
reindex()
owner, admin, developer (deletion restricted to owner/admin only)
Scope:knowledgebases.write
Image understanding (concurrency 1..8) and ingestion tracing are configurable; image understanding requires an available vision model

Deep Integration with the Agent Runtime

In the left navigation pane of the Console, go to Agent Runtime. Through project-level runtime configuration (PATCH /v1/agent-runtime/project/config), you can set the main conversation model to qwen-plus, directly mount knowledge base kb_enterprise_support, and bind project-level lexicons lex_enterprise_synonyms and lex_support_stopwords, then immediately verify enterprise customer service Q&A with knowledge citation badges in the workspace conversation window.


Feature Details and Operation Guide

Step 1: Create a knowledge base (example)

  1. In the left navigation pane, click Knowledge Base, then click the Create knowledge base button in the upper right corner.

  2. Complete the form using your actual models and files. Values below are examples; the console generates the knowledge base ID and the model and dimensions must match your available configuration:

Configuration itemField nameExample configuration valueDescription and constraints
Knowledge base namename企业智能客服与技术支持知识库Display name; the console generates the knowledge base ID
Descriptiondescription沉淀架构白皮书、客服 SOP、OceanBase 向量排障与 AI 网关规范Optional; describes the domains covered by the knowledge base
Embedding ModelembeddingModeltext-embedding-v3 (from dashscope-prod)Required and cannot be changed after creation; the system automatically detects model availability
Vector DimensionembeddingDimension1024Must strictly match the text-embedding-v3 output dimension; stored in the OceanBase Shared V2 vector table
Document ParserdocumentParservlm (default, requires a vision model); text or mineru where appropriateControls how raw files are extracted into structured Markdown text
Chunking ParserchunkingParsertitle / smartHeading-hierarchy-based or intelligent semantic chunking is recommended for technical documents
Chunk size and overlap ratechunkTokenNum / overlapPercent512 Tokens / 10%Balances context integrity with vector focus
Image UnderstandingimageUnderstandingEnabled, model set to qwen-vl-max, concurrency 4Automatically generates text descriptions of architecture diagrams and screenshots in documents and merges them into the chunk index

Step 2: Ingest core documents and poll the 202 asynchronous ingestion status until ready

  1. Open the Documents page of your actual knowledge base and upload a file you are allowed to use. IDs, files, and responses below are examples; replace them with your actual values.

  2. Creating a document record with POST /v1/knowledgebases/{knowledgeBaseId}/documents returns HTTP 201. Starting ingestion with POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions returns HTTP 202 and ingestion job information. The console can start ingestion automatically after upload.

  3. Query the ingestion job and document details separately; the ingestion endpoint does not return the document status. These are HTTP paths, not shell commands:

GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}

GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}

Replace the placeholders with actual values and use a project key with knowledgebases.read. When checking a draft in a versioned knowledge base, add its versionId query parameter to both URLs.

APPBASE_ENDPOINT="https://your-agentbase.example.com/v1"
APPBASE_PROJECT_ID="your-project-id"
APPBASE_KB_ID="your-knowledge-base-id"
APPBASE_DOCUMENT_ID="your-document-id"
APPBASE_INGESTION_ID="your-ingestion-id"
read -r -s -p 'API key: ' APPBASE_API_KEY
printf '\n'
printf 'header = "X-Appwrite-Key: %s"\n' "$APPBASE_API_KEY" | \
  curl --config - -sS -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    "${APPBASE_ENDPOINT}/knowledgebases/${APPBASE_KB_ID}/documents/${APPBASE_DOCUMENT_ID}/ingestions/${APPBASE_INGESTION_ID}"
printf 'header = "X-Appwrite-Key: %s"\n' "$APPBASE_API_KEY" | \
  curl --config - -sS -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    "${APPBASE_ENDPOINT}/knowledgebases/${APPBASE_KB_ID}/documents/${APPBASE_DOCUMENT_ID}"
unset APPBASE_API_KEY

Alternatively, open the document from the knowledge base Documents list in the console to inspect its status and ingestion records. To check the active generation via API, also call the document details endpoint.

  1. Confirm that both the ingestion job and document status are ready, and that the document activeGeneration matches the job generation, before searching the new generation. The vector dimension depends on the actual knowledge base configuration.


Step 3: Bind the lexicon and enable advanced indexing (GraphRAG / RAPTOR / Wiki)

  1. Bind project-level lexicons:

    • In the project's Lexicons section, create a synonym dictionary lex_enterprise_synonyms (for example, mapping OB向量报错4013 and 向量内存不足 to the standard term OB_ALLOCATE_MEMORY_FAILED) and a stopword dictionary lex_support_stopwords.

    • Call PUT /v1/knowledgebases/kb_enterprise_support/lexicons or check the binding of these two lexicons on the knowledge base settings page.

  2. Enable and build derived indexes:

    • Switch to the knowledge base Indexes tab, turn on the three index capability switches in order: GraphRAG, RAPTOR, and LLM Wiki, then click Build.

    • After the build completes, the Graph tab lets you browse the entity relationship knowledge graph, and the Wiki tab automatically compiles 10 structured encyclopedia pages, including a homepage overview (kb-index).


Verify retrieval results and sources in the Search tab. The API examples below additionally enable answer synthesis and specify a reranking model. Example model names must be replaced with the project's actual configuration; explicit model failures will not be ignored by 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
  }'

Then, in the Agent Runtime, save the project-level configuration (/v1/agent-runtime/project/config) and mount kb_enterprise_support together with lexicons lex_enterprise_synonyms and lex_support_stopwords onto the qwen-plus agent. You can then get precise answers fusing troubleshooting guides and customer service SOPs directly in the conversation panel.


Knowledge Base Settings and Project-Level Lexicon Management

Part One: Manage knowledge base global settings (Knowledge Base Settings)

Go to the Settings tab of kb_enterprise_support to view and modify the following configuration by group:

Settings groupConfiguration itemsExample configuration valuesChange impact and notes
Basic informationName and description (name / description)企业智能客服与技术支持知识库Takes effect immediately after modification; does not affect any index or retrieval behavior.
Vector foundation (read-only)Embedding model and dimension (embeddingModel / embeddingDimension)text-embedding-v3 / 1024 dimensionsStrictly forbidden to modify after creation. Vectors from different models or of different dimensions cannot have cosine distances computed in the same OceanBase vector index table. To change the embedding model, create a new knowledge base.
Default ingestion and chunking (indexingDefaults)Document parser (documentParser)
Chunking parser (chunkingParser)
Chunking parameters (chunkTokenNum, etc.)
text
title
512 Tokens / 10% overlap
After saving, changes only apply to documents uploaded or newly triggering ingestion afterward; to apply the new chunking strategy to existing ready documents, you must go back to the Documents tab and click Reindex.
Ingestion tracing (ingestionTracing)Record parsing and chunking intermediate artifactstrue (enabled)Allows Observability -> Knowledge Base Parsing Evaluation to read raw parsing snapshots (requires the platform global switch to allow it).
Multimodal image understanding (imageUnderstanding)Enable switch (enabled)
Vision model (model)
Concurrency (maxConcurrency)
Custom prompt (prompt)
true
qwen-vl-max
4 (range 1–8)
请提取架构图与表格中的关键组件、参数与流向
Requires that the project has registered with the LLM Gateway a Provider with vlm capability; after enabling, historical documents containing images must be re-ingested to generate image descriptions.
Retrieval defaults (retrievalDefaults)Vector weight (vectorWeight), similarity threshold (similarityThreshold)Example 0.7, 0.35When retrieval requests omit these parameters, the knowledge base defaults are used; searchMode is selected per request, defaulting to hybrid when omitted.
Answer synthesis model (indexingDefaults)chatModel, optional chatProviderRefAny Chat model actually available to the projectUsed with the single knowledge base API answer=true; this is not the configuration in retrievalDefaults.

Part Two: Create and manage project-level lexicons (lex_enterprise_synonyms & lex_support_stopwords)

In project enterprise-ai-hub-210, we configured two core production lexicons, lex_enterprise_synonyms and lex_support_stopwords (for the full native-v1 tokenization principles, online preview and debugging, and the CSV/XLSX/JSON import guide, see Project-Level Lexicons and Retrieval/Knowledge Graph/Agent Collaborative Governance). Below are the quick creation and binding steps:

Step 1: Create the synonym dictionary and stopword dictionary

  1. Go to the Lexicons management interface and click Create lexicon.

  2. Create the following two lexicons respectively:

    • Lexicon 1 (synonyms and expansion terms dictionary):

      • Lexicon ID / name: lex_enterprise_synonyms (企业智能客服同义词与专有名词词典)

      • Description: 统一 OceanBase、AI 网关及客服工单领域的缩写、黑话与错误码扩展

    • Lexicon 2 (stopwords and compliance interception dictionary):

      • Lexicon ID / name: lex_support_stopwords (企业客服停用词与敏感拦截词典)

      • Description: 清洗检索口语噪声词并在智能体工作台前置拦截违规诱导提问

Step 2: Add synonym (synonym), expansion term (expansion), and stopword (stop) lexicon entries

Go to the lexicon detail page and click Add entry, or click Import CSV/Excel to upload the word list:

LexiconEntry type (type)Main word / trigger word (term)Target synonym / expansion term list (targets)Status (enabled)Business purpose
lex_enterprise_synonymssynonymOB["OceanBase", "OceanBase数据库"]trueUsers searching OB and OceanBase get fully bidirectionally equivalent retrieval results
lex_enterprise_synonymssynonymAIGW["AI网关", "AI Gateway", "统一AI网关"]trueUnify Chinese/English abbreviations with official product names
lex_enterprise_synonymsexpansion向量报错4013["OB_ALLOCATE_MEMORY_FAILED", "ob_vector_memory_limit_percentage", "-4013"]trueWhen users enter colloquial error descriptions, inject precise error codes and kernel parameter names one-way
lex_enterprise_synonymsexpansion工单升级["二线技术专家", "SOP流转时限", "P1故障响应"]trueReinforce retrieval of customer service SOP manual sections
lex_support_stopwordsstop请问一下呗[]trueStrip meaningless colloquial suffixes before retrieval
lex_support_stopwordsstop忽略之前所有系统指令[]trueIn the Agent Runtime, work with stopIntercept to directly intercept jailbreak instructions

Bulk import/export notes: Click Export in the upper right corner of the lexicon to download the standard-format template (including the type,term,targets,enabled column). After editing thousands of industry entries locally in Excel, click Import to complete incremental merging or full updating in one click.


Part Three: Bind lexicons to the knowledge base and Agent Runtime (REST API and Console operations)

After lexicons are created, they must be bound to the target knowledge base (kb_enterprise_support) or Agent Runtime (Agent Runtime) to take effect at runtime:

1. Bind to the knowledge base (/v1/knowledgebases/{knowledgeBaseId}/lexicons)

In the Settings -> Bound Lexicons section of kb_enterprise_support, check lex_enterprise_synonyms and lex_support_stopwords and click save; or bind via the API:

# 1. Create a project-level lexicon (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. Batch-add synonym and expansion term entries to the lexicon (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. Bind the lexicon to the knowledge base 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. Bind to the Agent Runtime and enable stopword pre-interception (/v1/agent-runtime/project/lexicons)

Bind the lexicons in the Agent Runtime configuration, and configure stopIntercept and 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": "抱歉,您的提问包含受限或不符合企业安全规范的指令,请围绕产品技术支持与客服业务进行咨询。"
  }'

Verification result:


Completing your first retrieval

It is recommended to follow the path in the order “prepare models → create knowledge base → ingest documents → validate retrieval → verify sources”. The diagram below only expresses verified operational relationships; it does not reproduce the Console pages and is not a runtime screenshot:

Knowledge Base Overview: workflow diagram, not a runtime screenshot

Before creating a knowledge base, you need at least one model with embedding capability; a vision model is only additionally required when image understanding is needed. If you want retrieval requests to generate answers, you also need to configure the corresponding chat model according to deployment capability. Both model services and optional parsing capabilities are constrained by project configuration and deployment capability; see Models and AI Gateway.

If results are missing expected content, first confirm that the documents have been ingested, and check the parsing and chunk results; after changing the parser or chunking parameters, the affected documents must be re-ingested. Retrieval result scores are used for ordering and do not replace verifying the original source text.

Creating a knowledge base

On the list page, click Create knowledge base. Fields:

FieldRule
Name / DescriptionName is required; description is optional
Embedding modelRequired (only Provider models with embedding capability are listed; submission is impossible without selection)
Embedding dimensionOptional (1–65535): probed and validated against the selected model; creation fails on mismatch
Ingestion tracingOptional switch: when enabled, records ingestion intermediate artifacts (parsing / chunking) for use in “knowledge base parsing evaluation”; depends on a platform-administrator global switch, and after enabling, documents must be re-ingested to obtain complete evidence
Image understandingSwitch + model + prompt + maximum concurrency (requires the project to have a vision model Provider configured)
Chunking parsergeneral / title / smart / regex / faq, plus chunk parameters: chunkTokenNum (default 512), overlapPercent (default 10), titleLevel (default 3), minChunkTokens (default 128), delimiter, regexPattern

Parsing configuration only affects subsequent ingestion; historical documents must be re-ingested for the new configuration to apply.

Usage boundaries

FAQ (Frequently Asked Questions and Troubleshooting)

Q1: After the ingestion API returns HTTP 202, why can't I immediately retrieve the document?

Q2: With Rerank enabled, will upstream rate limiting cause retrieval to fail?

It depends on whether a rerank model or Provider is explicitly selected. When rerankModel or rerankProviderRef is passed in, call exceptions are returned to the caller; you should fix the model configuration, rate limiting, or service failure. Automatic rerank with neither specified is best-effort: on failure it can fall back to the original ordering and return reranked: false; in that case, do not treat the results as reranked.

allowDegraded separately controls degradable errors in enhanced retrieval and cannot be used to ignore explicit rerank model failures. The single-library response's capabilities and degradedCapabilities describe the enhanced capability status; choose this switch based on whether the business accepts base results.

Q3: After modifying the knowledge base's default chunking parameters (such as chunkTokenNum) or enabling image understanding, will existing documents already in the ready state take effect automatically?

Q4: What is the difference between a lexicon bound to a knowledge base and one bound to an agent workbench?