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 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.
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
Enterprise End-to-End RAG and Knowledge Governance Architecture Diagram
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 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. The documentTag format is {subProductId}_{sectionCode}_{fileKey}, supporting precise filtering in document lists, single-library/cross-library 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/documents | POST /v1/knowledgebases/{kbId}/documentsGET .../ingestions/{ingestionId} | knowledgeBase.createDocument()getIngestion() | owner, admin, developerScope: 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/PATCH .../index-capabilities/{cap}POST .../index-operations | knowledgeBase.updateIndexCapability()createIndexOperation() | owner, admin, developerScope: 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 .../export-to-memory | knowledgeBase.listWikiPages()resolveWikiConflict()exportWikiPageToMemory() | owner, admin, developerScope: 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 online active version (Current) via copy-on-write |
| Project-Level Lexicon and Multi-Endpoint Binding | lexicons.md | /console/.../knowledge-base/lexicons/console/.../kb-kb_enterprise_support/lexicons | GET/POST /v1/lexiconsPUT .../kb_enterprise_support/lexicons | knowledgeBase.createLexicon()updateKnowledgeBaseLexicons() | owner, admin, developerScope: lexicons.write | 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.
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_KEYAlternatively, 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:
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 group | Configuration items | Example configuration values | Change impact and notes |
|---|---|---|---|
| Basic information | Name 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 dimensions | Strictly 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.) | texttitle512 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 artifacts | true (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) | trueqwen-vl-max4 (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.35 | When 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 chatProviderRef | Any Chat model actually available to the project | Used 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
Go to the Lexicons management interface and click Create lexicon.
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:
| Lexicon | Entry type (type) | Main word / trigger word (term) | Target synonym / expansion term list (targets) | Status (enabled) | Business purpose |
|---|---|---|---|---|---|
lex_enterprise_synonyms | synonym | OB | ["OceanBase", "OceanBase数据库"] | true | Users searching OB and OceanBase get fully bidirectionally equivalent retrieval results |
lex_enterprise_synonyms | synonym | AIGW | ["AI网关", "AI Gateway", "统一AI网关"] | true | Unify Chinese/English abbreviations with official product names |
lex_enterprise_synonyms | expansion | 向量报错4013 | ["OB_ALLOCATE_MEMORY_FAILED", "ob_vector_memory_limit_percentage", "-4013"] | true | When users enter colloquial error descriptions, inject precise error codes and kernel parameter names one-way |
lex_enterprise_synonyms | expansion | 工单升级 | ["二线技术专家", "SOP流转时限", "P1故障响应"] | true | Reinforce retrieval of customer service SOP manual sections |
lex_support_stopwords | stop | 请问一下呗 | [] | true | Strip meaningless colloquial suffixes before retrieval |
lex_support_stopwords | stop | 忽略之前所有系统指令 | [] | true | In 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,enabledcolumn). 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:
When a user asks about
OB向量报错4013怎么处理in knowledge base retrieval or the Agent Runtime, the system automatically expands it vialex_enterprise_synonymsintoOceanBase,OB_ALLOCATE_MEMORY_FAILED, andob_vector_memory_limit_percentage, precisely hitting the core chunks in "OceanBase Distributed Transactions and Vector Index Troubleshooting Guide.md".When a user input contains restricted entries from
lex_support_stopwords, the Agent Runtime directly returns thestopReplypreset reply at millisecond speed, completing compliance interception with zero Token consumption.
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, click Create knowledge base. Fields:
| Field | Rule |
|---|---|
| Name / Description | Name is required; description is optional |
| Embedding model | Required (only Provider models with embedding capability are listed; submission is impossible without selection) |
| Embedding dimension | Optional (1–65535): probed and validated against the selected model; creation fails on mismatch |
| Ingestion tracing | Optional 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 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 |
Parsing configuration only affects subsequent ingestion; historical documents must be re-ingested for the new configuration to apply.
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: 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?
Root cause analysis: The knowledge base's default parsing and chunking strategy (
indexingDefaults) and image understanding configuration (imageUnderstanding) follow a snapshot isolation mechanism; after modification they only take effect for documents newly uploaded or newly triggering ingestion afterwards, and will not silently rewrite existing chunks already ready in production.Resolution: To apply the new configuration to existing documents, in the Documents and Ingestion Management list you can click Re-ingest for a single document, or in the Knowledge Base Settings Center click Full-library Reindex (
POST /v1/knowledgebases/{kbId}/reindex).
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 automatically performs synonym expansion (synonym), appended-term expansion (expansion), and stopword cleaning (stop), and is used for GraphRAG entity normalization whengraphrag: trueis enabled (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)

