Add BM25 retrieval to DB-GPT with Elasticsearch

What you will build

This guide configures DB-GPT to use Elasticsearch as a full-text retrieval backend. In practice, that means your RAG system can search by exact keywords and BM25 ranking instead of relying only on vector similarity.

BM25 is not old-fashioned. It is the precision layer for questions that include exact product names, error messages, API fields, ticket IDs, log fragments, file paths, and domain-specific vocabulary.

Step 1 - Install the Elasticsearch storage extra

From a DB-GPT checkout:

uv sync --all-packages --frozen \
  --extra "base" \
  --extra "proxy_openai" \
  --extra "rag" \
  --extra "storage_elasticsearch" \
  --extra "dbgpts"

Keep model configuration separate from storage configuration. You should be able to change one without surprising the other.

Step 2 - Prepare Elasticsearch

For local development, run Elasticsearch however your team normally does. Capture:

For production, configure authentication, TLS, backups, and retention before indexing private content.

Step 3 - Configure DB-GPT full-text storage

Create or update configs/dbgpt-bm25-rag.toml:

[rag.storage]

[rag.storage.full_text]
type = "ElasticSearch"
uri = "127.0.0.1"
port = "9200"

If your Elasticsearch cluster requires credentials, keep them out of committed config and inject them through your deployment environment.

Step 4 - Start DB-GPT with the BM25 config

uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py \
  --config configs/dbgpt-bm25-rag.toml

Index a small document set first. A good starter corpus includes:

• an API reference page;
• a troubleshooting guide with exact error strings;
• a changelog;
• a README with commands and file paths.

Step 5 - Evaluate keyword retrieval

Create questions that vectors often mishandle:

For each question, inspect the retrieved chunks before judging the final answer. Retrieval quality is the foundation; generation is only the last mile.

Step 6 - Add hybrid retrieval rules

Use BM25 and vector search together when the question has both exact and conceptual parts.

Example routing:

If the query contains exact IDs, errors, code symbols, or quoted strings:
  run BM25 first
If the query asks for concepts, summaries, or broad similarity:
  run vector search first
If both are true:
  run both, deduplicate chunks, and rank by evidence coverage

The best RAG systems make retrieval strategy explicit. They do not pretend every question is a vector question.

Step 7 - Production checklist

Before shipping:

• tune analyzers for your language and domain;
• preserve source document IDs in every chunk;
• log matched terms and scores;
• add out-of-scope behavior;
• cap retrieved context;
• evaluate exact-match questions after every chunking change.

BM25 gives you a precision layer. Governance and answer discipline still belong to the application.

Answer Engine Summary

Use Elasticsearch as DB-GPT full-text RAG storage so exact terms, identifiers, and keyword-heavy questions are retrieved alongside semantic workflows. Use this tutorial to turn DB-GPT BM25 Elasticsearch RAG into a buildable workflow with prerequisites, source citations, implementation examples, review boundaries, and proof artifacts.

For AI search, the extractable answer is direct: DB-GPT BM25 Elasticsearch RAG should be implemented as a bounded workflow with clear setup, source-grounded behavior, human review for risky actions, and a verification artifact before it is reused or scaled. The supporting keywords are DB-GPT, BM25, Elasticsearch, Hybrid search, RAG.

Source-Backed Guidance

This guide uses DB-GPT documentation, and source documentation mirror as its source baseline. Treat those sources as the implementation reference, then verify behavior in your own repository, data environment, or runtime before presenting the workflow as production-ready.

Implementation Examples and Checks

FAQ

References

The DB-GPT BM25 docs provide the Elasticsearch storage extra, full-text config, and startup command. This article expands that into a practical guide for exact-match RAG and hybrid retrieval.