Docs
Contents

Knowledge Base

Overview and use cases

Knowledge Bases provide a managed RAG pipeline: upload/import documents → parse and chunk → Embedding → store in vector database → retrieval (vector / fulltext / hybrid, optional rerank). Starting in 2.6.0, rich-document RAG supports PDF (text layer / per-page VLM / MinerU), Office documents (DOC/DOCX/PPT/PPTX direct extraction or parse after PDF conversion), tables (CSV/TSV/XLS/XLSX structured extraction), image assets, and optional image understanding; Python Server SDK 15.4.0 completes the full Knowledge Bases surface.

Prerequisites

Models and parsers

The project must have a usable LLM Gateway embedding model configured (optional rerank / VLM): when creating a KB, exact matching is done by model name; creation fails if the Gateway lacks the model or the Provider is not activated.

documentParser accepts text / vlm / mineru (default vlm; vlm must be paired with a usable visionModel; the legacy value auto will be rejected; do not automatically switch parsers when MinerU is unavailable).

Permission scopes

Permission scopePurpose
Knowledge baseknowledgebases.read (read/retrieval), knowledgebases.write (write/ingestion)
Project lexiconLexicon management requires lexicons.read (read lexicons, entries, references, and previews) and lexicons.write (create/update/delete lexicons and entries, import entries)

Knowledge base lexicon binding (GET/PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons) validates both read/write permission on the target knowledge base and read permission on the bound lexicon; browsers use the user Session and do not hold the project API Key.

Usage workflow

1. Create a knowledge base

create({ name, embeddingModel, ... }) creates the KB — embeddingModel cannot be changed after creation; if probing fails, creation fails (switch model names or activate the Provider first).

Starting with 2.9.0, optional embeddingDimension (1–65535: validates against the selected model via probing; creation fails if it does not match the model's output dimensions) and tracingEnabled (ingestion tracing switch, recording parsing / chunking intermediate artifacts for parse evaluation; depends on a platform administrator's global switch, and after enabling it, documents must be re-ingested to have complete evidence).

2. Ingest documents and wait for ready

Ingest documents: createDocument + createIngestion({ documentId, ... }) (or batch createDocumentsBatch); the ingestion state machine is queued → running → ready | failed | cancelled, poll getIngestion. createIngestion returning HTTP 202 only means the task was accepted, not that it is immediately retrievable; confirm the ingestion is ready and that the Document's status=ready, activeGeneration match this ingestion's generation before retrieving by the new generation.

The parser configuration (parserId + parserConfig) determines the chunking method; common parameters are in the next section.

3. Configure image understanding (optional)

(Optional) Image understanding: configure enabled / model / providerRef / prompt / limit parameters in imageUnderstanding — this is an independent step after parsing that generates descriptions for informative images and adds them to the retrieval text, but does not modify the original chunk's content/span/locator.

4. Configure and bind the lexicon (optional)

(Optional) Lexicon configuration and binding: create a project lexicon via /v1/lexicons (e.g., an enterprise synonym lexicon lex_enterprise_synonyms, a customer-service stopword lexicon lex_support_stopwords), call /v1/lexicons/{lexiconId}/entries to maintain the three types of entries synonym / expansion / stop (or batch import JSON/CSV/XLSX via /v1/lexicons/{lexiconId}/import), use /v1/lexicons/{lexiconId}/preview to preview native-v1 tokenization and query rewriting effects, and finally call PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons to bind to the target knowledge base (e.g., kb_enterprise_support) and enable enabled: true.

5. Retrieval and answer synthesis

Retrieval: createSearch (single library) and createMultiSearch (multi-library), passing query, searchMode (default hybrid; the parameter name is searchMode, not mode), limit, similarityThreshold, vectorWeight, rerank / rerankModel.

Starting with 2.9.0, you can pass answer: true to enable answer synthesis: the chat model from the knowledge base's indexingDefaults performs grounded synthesis over merged evidence (up to 12 evidence rows, answer ≤1024 tokens), and the result carries answer (status / text / model / latency).

Starting with 2.10.0, retrieval accepts documentTag (server 2.12.0 supports multiple tags and segment-aligned filtering of structured locators) and subProductId (AND semantics) to narrow chunk / GraphRAG / Wiki retrieval; createMultiSearch additionally supports metadataFilter (keyed by knowledge base, with "*" as fallback) and offset (pagination after fusion ranking). Document registration (createDocument) / update (updateDocument) can write documentTag / subProductId; only creation supports sectionCode, and listDocuments supports documentTag / subProductId filtering. When either filter is non-empty, the list endpoint ignores queries (including pagination, sorting, and other queries), while status / stage / enabled still apply.

6. Verify against the original source

Source tracing: result chunks carry content, source (source URI), and locator (section/text offset); reading the source via getDocumentSource supports Range/206 and only requires knowledgebases.read.

7. Full rebuild

Full rebuild: createReindex (returns 202, a bounded bulk re-ingestion entry point; it does not change embeddingModel).

8. Build enhanced indexes (optional)

(Optional) enhanced indexes: configure and enable GraphRAG / RAPTOR / Wiki via updateIndexCapability → build asynchronously with createIndexOperation → poll the operation until its terminal state; for Wiki pages / versions / proposals / conflicts and knowledge graph browsing, see wiki.md.

Integration flow diagram

The diagram below summarizes the complete path of "create knowledge base → ingest documents → wait until ready → retrieve → verify against source", so you can match it against the SDK call steps above. Models, Documents, Search, and View source in the diagram are Console entry points; when integrating via SDK, use the methods in this document plus Documents and Ingestion and Retrieval and Source Tracing.

Diagram of knowledge base creation, ingestion, and first retrieval; not a live screenshot

Flow diagram, not a live screenshot. Confirm documents are ready before retrieving and verifying sources; open the full-size image to view text details.

View the flow diagram in full size

Resource model and enhanced capabilities

Resource relationships

Resource model: KB (embeddingModel required at creation; the server probes the LLM Gateway once for embeddings to obtain the dimension automatically, and automatically creates the accompanying vector store and Storage resources) → Document → generation (each successful ingestion produces one generation; retrieval only returns the active generation) → ingestion (async task) → chunk (the basic unit of retrieval); data sources (datasource, currently Yuque) can sync documents into the same pipeline.

Enhanced indexes

Starting with 2.7.0, enhanced indexes are added on top of basic RAG: GraphRAG (entity knowledge graph), RAPTOR (summary tree), and LLM Wiki (canonical Wiki pages, versions, proposals, and conflict governance), plus the accompanying index capability configuration and async build operations — for the management plane and examples by language, see Wiki and GraphRAG (Index Governance); on the retrieval side, enhanced results are accessed via useKnowledgeGraph / useWiki / allowDegraded.

Project-level lexicon

2.10.0 (aligned with the release-2.10.2 baseline) adds project-level lexicon (Lexicon) binding to knowledge bases: manage synonym (synonym), associated expansion term (expansion), and stopword (stop) lexicon entries via /v1/lexicons, and bind the lexicon to a knowledge base via /v1/knowledgebases/{knowledgeBaseId}/lexicons.

Once binding is enabled, single- and cross-knowledge-base retrieval automatically performs synonym normalization and expansion term augmentation based on the native-v1 tokenization strategy before entering vector/full-text retrieval (no need to rebuild document vectors); if lexiconEnabled is enabled in the knowledge index configuration, GraphRAG knowledge graph construction also reuses the bound lexicon to apply deterministic canonical-name normalization to extracted entities and relation endpoints.

Key parameters and returns

FAQ: Can knowledge base retrieval use mode?

No. The retrieval mode field name for KnowledgeBases.createSearch and createMultiSearch is searchMode; mode cannot substitute for this SDK/API request field. When asked "why use searchMode", the reason is that the parameter name defined by the API contract is searchMode.

Errors and boundaries

SDK Category Differences

Examples by language

Knowledge base creation examples are on this page; for ingestion and data sources see Documents and Ingestion, and for retrieval and source tracing see Retrieval and Source Tracing. Each card can switch languages (synchronized across the whole page).

Create a knowledge base

KB creation is a synchronous call, while the accompanying VectorsDB / Storage resources become ready asynchronously during provisioning. The Web (user Session) plane has no KB management capability (only Yuque OAuth-related methods), so this card has no Web tab.

import { KnowledgeBases, ID } from 'agentbase-node-sdk';

const kb = new KnowledgeBases(client);

const base = await kb.create({
    knowledgeBaseId: ID.unique(),        // Custom or ID.unique()
    name: '产品手册',
    embeddingModel: 'text-embedding-v3'  // Dimension is probed once from the Gateway at creation time and cannot be changed afterward
});

Lexicon management and knowledge base binding

Use /v1/lexicons to create a project-level lexicon, write synonym/expansion term/stopword entries, and preview native-v1 query rewriting results, then bind the lexicon to a knowledge base via PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons (e.g., kb_enterprise_support). The 2.12.0 releases of the Node Server SDK and Node Console SDK both expose the Lexicons service. The REST examples below apply to backend applications that send requests directly.

Run each code block separately in order and verify its response. Binding replaces the entire binding list; read the current list, preserve needed entries, and confirm the target knowledge base and lexicon IDs first.

Use Bash. Set APPBASE_ENDPOINT to the HTTPS API URL, including /v1, and provide APPBASE_PROJECT_ID and APPBASE_API_KEY for that project. Reads and previews use lexicons.read. Writes use lexicons.write, and binding reads and updates also require the corresponding permissions on the target knowledge base. Define the Bash function below, then run the steps you need separately in the same shell. The function accepts only 2xx responses. For Python, see the backend HTTP example for a client that refuses redirects.

lexicon_request() (
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
  : "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID}"
  : "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the HTTPS API endpoint including /v1}"
  response="$(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" |
    curl --disable --header @- --proto '=https' --silent --show-error --write-out '\n%{http_code}' \
      --request "$1" "${APPBASE_ENDPOINT%/}$2" \
      --header 'Content-Type: application/json' \
      --header "X-Appwrite-Project: $APPBASE_PROJECT_ID" "${@:3}")" || exit 1
  status="${response##*$'\n'}"
  case "$status" in
    2[0-9][0-9]) builtin printf '%s\n' "${response%$'\n'*}" ;;
    *) builtin printf 'HTTP %s\n' "$status" >&2; exit 1 ;;
  esac
)
  1. Create a lexicon (POST /v1/lexicons)

lexicon_request POST "/lexicons" \
  --data '{"lexiconId":"lex_enterprise_synonyms","name":"企业核心产品同义词词典","tokenizerProfile":"native-v1"}'
  1. Create a synonym entry (POST /v1/lexicons/{lexiconId}/entries)

lexicon_request POST "/lexicons/lex_enterprise_synonyms/entries" \
  --data '{"entryType":"synonym","terms":["OceanBase","OB","分布式数据库OB"]}'
  1. Preview query rewriting (POST /v1/lexicons/{lexiconId}/preview)

lexicon_request POST "/lexicons/lex_enterprise_synonyms/preview" \
  --data '{"query":"OB 分布式事务怎么排障?"}'
  1. Query the knowledge base's current lexicon bindings (GET /v1/knowledgebases/{knowledgeBaseId}/lexicons)

lexicon_request GET "/knowledgebases/${APPBASE_KB_ID:?Set APPBASE_KB_ID}/lexicons"
  1. Bind the lexicon to the knowledge base and enable retrieval rewriting (PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons)

Send the complete binding list. The example applies to a knowledge base with an empty binding list. If bindings already exist, merge the entries you want to keep into the request before submitting the update.

lexicon_request PUT "/knowledgebases/${APPBASE_KB_ID:?Set APPBASE_KB_ID}/lexicons" \
  --data '{"enabled":true,"bindings":[{"lexiconId":"lex_enterprise_synonyms","priority":1}]}'

Example Guide