llama-index-retrievers-bm25

llama-index-retrievers-bm25 is an official LlamaIndex integration that provides a BM25Retriever for sparse, keyword-based document retrieval. It implements the classic BM25 ranking function on top of the fast bm25s library with PyStemmer-backed stemming and stopword removal, exposing it through LlamaIndex’s standard BaseRetriever interface.

BM25 complements dense vector search by matching exact terms, making it a common building block in hybrid retrieval-augmented generation (RAG) systems. This package lets you index a set of LlamaIndex nodes, retrieve the top-k matches for a query, persist and reload the retriever, and slot it directly into LlamaIndex query engines and retrieval pipelines.

What You Get

• A BM25Retriever implementing LlamaIndex’s BaseRetriever interface
• Fast BM25 scoring backed by the bm25s library
• Configurable stemming and stopword removal via PyStemmer with per-language support
• Persist and load support so a built retriever can be saved and restored
• Drop-in compatibility with LlamaIndex query engines and hybrid retrieval setups

Common Use Cases

• Adding keyword (sparse) retrieval alongside vector search in a RAG pipeline
• Building hybrid retrievers that fuse BM25 and embedding-based results
• Retrieving the most relevant nodes for a query by exact term matching
• Persisting a prebuilt BM25 index and reloading it at serving time

Under The Hood

Architecture - The package ships a single llama_index.retrievers.bm25 module whose base.py defines BM25Retriever as a subclass of LlamaIndex’s BaseRetriever. It ingests BaseNode objects, tokenizes and stems their text, delegates scoring to a bm25s.BM25 model, and maps ranked corpus indices back to nodes returned as NodeWithScore. Persistence writes the retriever state (including similarity_top_k and verbosity) to a JSON file for later reload.

Tech Stack - A Python (>=3.10) package built with Hatchling, depending on bm25s for the BM25 implementation, PyStemmer for stemming, numpy for scoring arrays, and llama-index-core for the retriever and schema abstractions. It lives in the llama-index-integrations tree of the run-llama/llama_index monorepo.

Code Quality - The integration includes a tests/ suite (test_retrievers_bm25_retriever.py) and inherits the monorepo’s tooling: Ruff, Black, mypy type checking with disallow_untyped_defs, codespell, and coverage gating via diff-cover and pytest-cov. Type annotations are enforced throughout the module.

API Design - Construction mirrors other LlamaIndex retrievers: pass nodes (or an existing bm25s.BM25), optionally set stemmer, language, and similarity_top_k, then call the standard retrieve flow. Reusing the BaseRetriever contract means it composes with the rest of LlamaIndex without special glue.