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:
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), andmineru(complex PDF layout/formula/table restoration)—as well as five chunking strategies:general,title,smart,regex, andfaq.Document ingestion uses an asynchronous task mechanism: the ingestion trigger API returns HTTP
202status code, and check the ingestion job and document separately. Search only after both arereadyand the documentactiveGenerationmatches the jobgeneration.
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.
Multi-way hybrid retrieval and resilient reranking (Hybrid Search & Rerank):
Supports three
searchModemodes:hybrid(hybrid retrieval),vector(vector retrieval), andfulltext(full-text retrieval); the fusion ratio of vector and full-text scores can be finely tuned viavectorWeight.Reranking can be optionally enabled; when explicit
rerankModelorrerankProviderRefcalls fail, an error is returned; if automatic reranking fails when neither is specified, the system can fall back and returnreranked: false. The per-libraryallowDegradedcontrols degradable errors of enhanced indexes;answer=truesynthesizes answers using retrieval evidence, and readers still need to verify sources.
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.
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 Concept | Key Fields / API Identifiers | Detailed Description |
|---|---|---|
| Knowledge base instance | knowledgeBaseId | The 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 job | ingestionId / HTTP 202 | The 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 identifier | documentTag / subProductId | Precise 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. |
| Lexicon | lexiconId | A 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 mode | searchMode | Supports hybrid (default, vector + full-text hybrid retrieval), vector (pure semantic vector retrieval), and fulltext (keyword full-text retrieval). |
| Hybrid vector weight | vectorWeight | Under 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 degradation | allowDegraded | Per-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 indexes | graphrag / raptor / wiki | Three 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 Name | Manual Chapter Link | Frontend Console Route Path | Core REST API Endpoint | Server SDK Methods (Node.js / Python) | Required RBAC Roles / API Key Scope | Cross-Module Dependencies |
|---|---|---|---|---|---|---|
| Knowledge Base Overview and Instance Management | overview.md | /console/project-default-enterprise-ai-hub-210/knowledge-base | GET/POST /v1/knowledgebases | knowledgeBase.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 Management | documents.md | /console/.../kb-kb_enterprise_support | POST /v1/knowledgebases/{kbId}/documentsGET .../documents/{docId}/ingestions/{ingestionId} | knowledgeBase.createDocument()getIngestion() | owner, admin, developerScope: 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 Synchronization | datasources.md | /console/.../kb-kb_enterprise_support/datasources | POST .../yuque/personal-datasourcesPOST .../datasources/{id}/syncs | Use the console or a user session for personal sources; see the SDK reference for team sync | Personal sources require a user session or JWT; knowledgebases.write | Automatically triggers ingestion after synchronization and marks derived indexes as stale (data_source_sync) |
| Advanced Knowledge Index Build Governance | indexing.md | /console/.../kb-kb_enterprise_support/indexes | GET .../index-capabilitiesPATCH .../index-capabilities/{cap}POST .../index-operations | knowledgeBase.updateIndexCapability()createIndexOperation() | owner, admin, developerScope: 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 Reports | graph.md | /console/.../kb-kb_enterprise_support/graph | GET .../graphGET .../graph/entities/{id}/neighborsGET .../graph/community-reports | knowledgeBase.getGraph()getGraphEntityNeighbors()listGraphCommunityReports() | owner, admin, developer, memberScope: knowledgebases.read | Depends on GraphRAG build readiness; enables useKnowledgeGraph: true multi-hop retrieval |
| Knowledge Base Wiki Compilation and Governance | wiki.md | /console/.../kb-kb_enterprise_support/wiki | GET/POST .../wiki/pagesGET .../wiki/conflictsPOST .../wiki/pages/{slug}/export-to-memory | knowledgeBase.listWikiPages()resolveWikiConflict()createWikiPageMemoryExport() | owner, admin, developerScope: GET knowledgebases.read; POST knowledgebases.write | Links with version management (Versions) seal gates and memory export |
| Hybrid Retrieval and Q&A Debugging | search.md | /console/.../kb-kb_enterprise_support/search | POST /v1/knowledgebases/{kbId}/searchPOST /v1/knowledgebases/search | createSearch() / create_search()createMultiSearch() / create_multi_search() | owner, admin, developer, memberScope: knowledgebases.read | Optional reranking and answer generation depend on the configured retrieval settings |
| Immutable Version Management and Rollback | versions.md | /console/.../kb-kb_enterprise_support/versions | POST .../version-adoptionsPOST .../versions/{id}/sealPOST .../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 Binding | lexicons.md | /console/.../knowledge-base/lexicons/console/.../kb-kb_enterprise_support/lexicons | GET/POST /v1/lexiconsPUT .../{kbId}/lexicons | lexicons.create()lexicons.updateKnowledgeBaseBindings() | owner, admin, developerScope: 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 VLM | settings.md | /console/.../kb-kb_enterprise_support/settings | PATCH /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)
In the left navigation pane, click Knowledge Base, then click the Create knowledge base button in the upper right corner.
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 item | Field name | Example configuration value | Description and constraints |
|---|---|---|---|
| Knowledge base name | name | 企业智能客服与技术支持知识库 | Display name; the console generates the knowledge base ID |
| Description | description | 沉淀架构白皮书、客服 SOP、OceanBase 向量排障与 AI 网关规范 | Optional; describes the domains covered by the knowledge base |
| Embedding Model | embeddingModel | text-embedding-v3 (from dashscope-prod) | Required and cannot be changed after creation; the system automatically detects model availability |
| Vector Dimension | embeddingDimension | 1024 | Must strictly match the text-embedding-v3 output dimension; stored in the OceanBase Shared V2 vector table |
| Document Parser | documentParser | vlm (default, requires a vision model); text or mineru where appropriate | Controls how raw files are extracted into structured Markdown text |
| Chunking Parser | chunkingParser | title / smart | Heading-hierarchy-based or intelligent semantic chunking is recommended for technical documents |
| Chunk size and overlap rate | chunkTokenNum / overlapPercent | 512 Tokens / 10% | Balances context integrity with vector focus |
| Image Understanding | imageUnderstanding | Enabled, model set to qwen-vl-max, concurrency 4 | Automatically 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
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.
Creating a document record with
POST /v1/knowledgebases/{knowledgeBaseId}/documentsreturns HTTP201. Starting ingestion withPOST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestionsreturns HTTP202and ingestion job information. The console can start ingestion automatically after upload.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.
Confirm that both the ingestion job and document status are
ready, and that the documentactiveGenerationmatches the jobgeneration, 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)
Bind project-level lexicons:
In the project's Lexicons section, create a synonym dictionary
lex_enterprise_synonyms(for example, mappingOB向量报错4013and向量内存不足to the standard termOB_ALLOCATE_MEMORY_FAILED) and a stopword dictionarylex_support_stopwords.Call
PUT /v1/knowledgebases/kb_enterprise_support/lexiconsor check the binding of these two lexicons on the knowledge base settings page.
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).
Step 4: Perform hybrid retrieval (searchMode=hybrid) and link the agent workbench
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:
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.
Figure: The creation form in a 2.12.0 test environment.
Main fields:
| Field | Rule |
|---|---|
| Name / Description | Name is required; description is optional |
| Embedding model | Required. 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 dimension | Optional. 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 understanding | Switch + model + prompt + maximum concurrency (requires the project to have a vision model Provider configured) |
| Chunking parser | general / 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
Image understanding requires a project-level vision model Provider; embedding input exceeding limits fails explicitly.
Model and embedding calls use the Provider configured by the project on the Models page (see Models and AI Gateway).
Evidence chains and evaluation of retrieval results in Observability are covered in Observability.
FAQ (Frequently Asked Questions and Troubleshooting)
Q1: After the ingestion API returns HTTP 202, why can't I immediately retrieve the document?
Root cause analysis: HTTP
202means the ingestion task has been successfully enqueued and asynchronous processing has begun (file reading -> parser conversion -> chunk splitting -> multimodal image interpretation -> embedding vectorization and storage). Before the task completes, the document may still be processing and its content may not yet be searchable.Resolution: Query the ingestion job and the document separately (see step 2 above). Search after both statuses are
readyand the documentactiveGenerationmatches the jobgeneration.
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?
Root cause analysis: Knowledge-base-level lexicon binding and agent-workbench-level lexicon binding operate on different execution aspects, serving “RAG retrieval and knowledge graph disambiguation” and “conversation-entry compliance blocking” respectively.
Resolution:
Bound to a knowledge base (
/v1/knowledgebases/{kbId}/lexicons): for queries sent to that knowledge base's/search, it applies configured synonym rewriting (synonym) and expansion terms (expansion); direct search does not clean the query using bound stop terms (stop). It can also be used for GraphRAG entity normalization when the corresponding lexicon capability is enabled for the knowledge index (see Project-level Lexicon Governance).Bound to an agent workbench (
/v1/agent-runtime/project/lexicons): it not only applies to RAG retrieval initiated from the workbench, but also supports pre-interception of stopwords/sensitive words at the conversation entry (stopIntercept: true) and directly returning a preset blocking reply (stopReply) without consuming LLM inference tokens.
Related Documentation
External data source integration and incremental sync with Yuque
GraphRAG, RAPTOR, and Advanced Knowledge Index Build Governance
Knowledge Graph Visualization Exploration and Community Reports
Knowledge Base Wiki Compilation, Conflict Adjudication, and Memory Export
Knowledge Base Immutable Version Management and Release Rollback
Project-level lexicons and retrieval/knowledge graph/agent collaborative governance
Knowledge Base Settings Hub, Default Policies, and Multimodal Image Understanding (VLM)

