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

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 (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) 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, lines 52-84), which delegates to RetrievalManager.retrieve() (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) to retrieve chunks based on embedding similarity.

Sparse BM25 Search: SparseRetriever.retrieve() (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) 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), 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, 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): Wraps individual knowledge bases, managing chunking, vector DB initialization, and document upload.
• KBSQLiteDatabase (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): 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

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)

{
  "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

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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}