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 synonym, expansion and stop-term lexicons that can be bound separately to a knowledge base and an agent. An enabled knowledge base binding can rewrite queries; stop-term interception requires an enabled agent binding and an interception policy. Direct knowledge base search does not intercept stop terms.

  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

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. documentTag supports free-form and structured locator values and segment-aligned filtering across multiple tags in document lists, 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_supportPOST /v1/knowledgebases/{kbId}/documents
GET .../documents/{docId}/ingestions/{ingestionId}
knowledgeBase.createDocument()
getIngestion()
owner, admin, developer
Scope: GET knowledgebases.read; POST 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 .../index-capabilities
PATCH .../index-capabilities/{cap}
POST .../index-operations
knowledgeBase.updateIndexCapability()
createIndexOperation()
owner, admin, developer
Scope: GET knowledgebases.read; PATCH/POST 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 .../wiki/pages/{slug}/export-to-memory
knowledgeBase.listWikiPages()
resolveWikiConflict()
createWikiPageMemoryExport()
owner, admin, developer
Scope: GET knowledgebases.read; POST 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 the active version (Current) after full materialization of the working copy
Project-Level Lexicon and Multi-Endpoint Bindinglexicons.md/console/.../knowledge-base/lexicons
/console/.../kb-kb_enterprise_support/lexicons
GET/POST /v1/lexicons
PUT .../{kbId}/lexicons
lexicons.create()
lexicons.updateKnowledgeBaseBindings()
owner, admin, developer
Scope: GET lexicons.read; POST/PUT lexicons.write, plus appropriate knowledge base and lexicon resource permissions
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.

(
  set +x
  set -e -o pipefail
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'
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | \
  curl --disable --header @- -fsS -i -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
    "${APPBASE_ENDPOINT}/knowledgebases/${APPBASE_KB_ID}/documents/${APPBASE_DOCUMENT_ID}/ingestions/${APPBASE_INGESTION_ID}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | \
  curl --disable --header @- -fsS -i -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:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/search" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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 lexicon management

Use the knowledge base Settings page to adjust document processing and retrieval defaults, inspect lexicon bindings, and review document rebuild prompts. See Knowledge base settings for the steps and cautions such as the storage bucket deletion option.

Lexicons manage synonyms, expansion terms, and stopwords and must be explicitly enabled when bound. See Lexicon management for creation, preview, import, and binding. Overwrite import replaces existing entries; run a dry run and inspect the impact first.

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, select Create knowledge base. The form below shows a test project configuration. Select models and a parser available to your project.

Create knowledge base form

Figure: The creation form in a 2.12.0 test environment.

Main fields:

FieldRule
Name / DescriptionName is required; description is optional
Embedding modelRequired. Select a model from the chosen provider, or enter a model name when none are listed. The server still checks model availability on submission
Embedding dimensionOptional. The console validates model dimensions using model metadata or fallback choices when metadata is unavailable. The server probes the model and rejects a mismatch
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

After creation, configure ingestion tracing (tracingEnabled) in the knowledge base settings; it depends on the platform administrator enabling the global switch. Parsing and tracing settings apply to subsequent ingestion, so existing documents must be re-ingested.

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: Do existing documents update automatically after changing chunking or image understanding?

Changing settings and reprocessing documents are separate steps. Check the rebuild prompt on the settings page; to apply new settings, review the target using Knowledge base settings and Documents and ingestion, submit processing, and wait for completion.

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