# How AstrBot's Knowledge Base Retrieval System Works: A Four-Stage Pipeline

> Discover how AstrBot's knowledge base retrieval system works with its four-stage pipeline: dense search FAISS, sparse BM25, RRF, and LLM reranking for precise context delivery.

- Repository: [AstrBot AI/AstrBot](https://github.com/AstrBotDevs/AstrBot)
- Tags: deep-dive
- Published: 2026-03-12

---

**AstrBot's knowledge base retrieval system uses a four-stage pipeline combining dense vector search (FAISS), sparse BM25 search, reciprocal rank fusion, and optional LLM reranking to deliver relevant context to the LLM.**

AstrBot implements a sophisticated knowledge base retrieval system that transforms short keyword queries into formatted context blocks for large language models. This system, defined in the AstrBotDevs/AstrBot repository, orchestrates multiple retrieval strategies to ensure high relevance across different types of queries. Understanding how this pipeline works helps developers customize retrieval behavior and optimize response quality.

## The Four-Stage Knowledge Base Retrieval Pipeline

The retrieval process follows a strict sequence from query entry to context injection. Each stage is implemented in specific modules within the `astrbot/core/knowledge_base/` directory.

### Stage 1: Query Entry via the astr_kb_search Tool

When the LLM requires factual grounding, it invokes the `astr_kb_search` tool defined in `KnowledgeBaseQueryTool`. The `call` method in [`astrbot/core/astr_main_agent_resources.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/astr_main_agent_resources.py) (lines 50-75) immediately delegates to `retrieve_knowledge_base()`, passing the query string and session identifier.

### Stage 2: Configuration Lookup and Session Management

The `retrieve_knowledge_base()` function (lines 94-125 in [`astrbot/core/astr_main_agent_resources.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/astr_main_agent_resources.py)) determines which knowledge bases to search and what parameters to apply. It first checks for session-level configuration using `sp.session_get`. If the session explicitly disables knowledge bases (`kb_ids = []`), the function returns early with no results. Otherwise, it resolves knowledge base names to IDs via `KnowledgeBaseManager.get_kb` and extracts parameters like `top_k` and `top_k_fusion` from the configuration.

### Stage 3: Hybrid Retrieval Engine

The core retrieval logic executes in `KnowledgeBaseManager.retrieve()` ([`astrbot/core/knowledge_base/kb_mgr.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/kb_mgr.py), lines 52-84), which delegates to `RetrievalManager.retrieve()` ([`astrbot/core/knowledge_base/retrieval/manager.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/retrieval/manager.py), lines 61-95). This stage implements a hybrid search strategy combining multiple algorithms:

**Dense Vector Search**: For each knowledge base, the system queries the attached FAISS vector database (`FaissVecDB` in [`astrbot/core/db/vec_db/faiss_impl.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/db/vec_db/faiss_impl.py)) to retrieve chunks based on embedding similarity.

**Sparse BM25 Search**: `SparseRetriever.retrieve()` ([`astrbot/core/knowledge_base/retrieval/sparse_retriever.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/retrieval/sparse_retriever.py), lines 55-137) pulls raw text chunks from the vector DB's document storage, tokenizes them using **jieba**, and builds a BM25 index via `rank_bm25.BM25Okapi` to score the query against stored documents.

**Reciprocal Rank Fusion**: `RankFusion.fuse()` ([`astrbot/core/knowledge_base/retrieval/rank_fusion.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/retrieval/rank_fusion.py)) merges dense and sparse results using the RRF algorithm. This calculates a fused score based on the reciprocal of each result's rank in the individual lists, producing a unified ranking without requiring score normalization between the different search modalities.

**Optional Reranking**: If the knowledge base configures a `RerankProvider` ([`astrbot/core/provider/provider.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/provider/provider.py)), the top-k results undergo LLM-based reranking. The provider's `rerank` method re-sorts the fused results to improve relevance before returning the final list.

### Stage 4: Context Formatting and Prompt Injection

Finally, `KnowledgeBaseManager._format_context()` ([`astrbot/core/knowledge_base/kb_mgr.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/kb_mgr.py), lines 68-78) converts the `RetrievalResult` objects into a human-readable context block. The formatted string includes source knowledge base names, document names, chunk content, and relevance scores, prefixed with the instruction: `以下是相关的知识库内容,请参考这些信息回答用户的问题:`. This block returns to the LLM, completing the retrieval cycle.

## Key Architecture Components

Several specialized classes support the knowledge base retrieval system:

- **KBHelper** ([`astrbot/core/knowledge_base/kb_helper.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/kb_helper.py)): Wraps individual knowledge bases, managing chunking, vector DB initialization, and document upload.
- **KBSQLiteDatabase** ([`astrbot/core/knowledge_base/kb_db_sqlite.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/kb_db_sqlite.py)): Stores metadata for knowledge bases and documents, enabling batch retrieval with metadata enrichment.
- **RerankProvider** ([`astrbot/core/provider/provider.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/provider/provider.py)): Abstract interface for LLM-based reranking implementations.
- **Session Configuration**: The `sp.session_set` and `sp.session_get` mechanisms allow per-conversation knowledge base toggling and parameter overrides.

## Implementation Examples

### Directly Query the Knowledge Base from Python

```python
from astrbot.core.astr_main_agent_resources import retrieve_knowledge_base
from astrbot.core.context import Context

async def demo_query():
    # Obtain the current AstrBot Context from your agent runtime

    ctx: Context = ...
    query = "What is the capital of France?"
    # Unique message/session identifier (e.g., "qq_123456")

    umo = "qq_123456"

    result = await retrieve_knowledge_base(query=query, umo=umo, context=ctx)
    if result:
        print("Injected KB context:\n", result)
    else:
        print("No KB match found.")

```

This function internally invokes `KnowledgeBaseManager.retrieve`, executing dense and sparse search, rank fusion, optional reranking, and returning the formatted text block.

### Using the LLM Tool (astr_kb_search)

```json
{
  "type": "function",
  "function": {
    "name": "astr_kb_search",
    "arguments": {
      "query": "Python list comprehension syntax"
    }
  }
}

```

When the LLM emits this payload, `KnowledgeBaseQueryTool.call` forwards the request to `retrieve_knowledge_base`. The returned context string automatically appends to the LLM's next prompt, providing factual grounding without manual intervention.

### Customizing Per-Session Knowledge Base Settings

```python
from astrbot.core.session import sp

async def enable_kb_for_session(umo: str, kb_ids: list[str]):
    # Disable the default global KB list and use only the supplied IDs

    await sp.session_set(
        umo,
        "kb_config",
        {"kb_ids": kb_ids, "top_k": 3}
    )

```

Setting `kb_ids` to an empty list disables the knowledge base entirely for that session, causing `retrieve_knowledge_base` to return early with no results.

## Summary

- AstrBot implements a **four-stage pipeline** for knowledge base retrieval: query entry, configuration lookup, hybrid retrieval, and context formatting.
- The system combines **dense vector search** (FAISS) with **sparse BM25 search** (jieba tokenization) and merges results using **Reciprocal Rank Fusion (RRF)**.
- Optional **LLM-based reranking** can improve result relevance before formatting.
- Session-level configuration via `sp.session_set` enables per-conversation control over active knowledge bases and retrieval parameters.
- Core implementation spans [`astrbot/core/astr_main_agent_resources.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/astr_main_agent_resources.py), [`astrbot/core/knowledge_base/kb_mgr.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/kb_mgr.py), and the retrieval submodule.

## Frequently Asked Questions

### How does AstrBot combine dense and sparse search results?

AstrBot uses **Reciprocal Rank Fusion (RRF)** implemented in `RankFusion.fuse()` to merge dense FAISS results with sparse BM25 scores. The algorithm calculates a fused score based on the reciprocal of each result's rank in the individual lists, producing a unified ranking without requiring score normalization between the different search modalities.

### Can I disable the knowledge base for specific sessions?

Yes. You can disable knowledge base retrieval for a specific session by setting `kb_ids` to an empty list using `sp.session_set(umo, "kb_config", {"kb_ids": []})`. When `retrieve_knowledge_base()` detects an empty KB list in the session configuration, it returns early with no results, effectively bypassing the retrieval pipeline for that conversation.

### What tokenizer does AstrBot use for BM25 sparse retrieval?

AstrBot uses **jieba** for Chinese text tokenization in the sparse retrieval module. The `SparseRetriever` class in [`astrbot/core/knowledge_base/retrieval/sparse_retriever.py`](https://github.com/AstrBotDevs/AstrBot/blob/main/astrbot/core/knowledge_base/retrieval/sparse_retriever.py) tokenizes raw text chunks using jieba before building the BM25 index with `rank_bm25.BM25Okapi`, enabling effective keyword matching for Chinese knowledge bases.

### Is reranking mandatory in the knowledge base retrieval system?

No, reranking is optional. The retrieval pipeline only applies LLM-based reranking if the knowledge base configuration includes a valid `RerankProvider` and the provider ID matches the retrieval parameters. If no reranker is configured, the pipeline returns the fused results directly after the RRF stage, making the reranking step completely optional for basic deployments.