Hybrid Search#

Hybrid search in Dify combines vector (semantic) and full-text/keyword retrieval in a single query, then fuses the results using either weighted score fusion or an external reranking model. It is one of four retrieval methods — alongside semantic_search, full_text_search, and keyword_search — and is the only mode that fans out to both index types simultaneously.

Index Creation#

Both index types are populated at ingestion time via ParagraphIndexProcessor.load() 1:

• Vector index — created by Vector(dataset).create(documents) when the dataset's indexing_technique is HIGH_QUALITY. The Vector factory 2 lazily resolves the configured embedding model via ModelManager and delegates to the backend-specific vector store implementation.
• Keyword index — built by Keyword(dataset).add_texts(documents). The Keyword factory 3 is backed by Jieba (the only currently supported keyword store, selected via dify_config.KEYWORD_STORE) 4.

Both indexes are maintained in sync: clean() deletes from both when segments are removed 5.

Concurrent Retrieval#

RetrievalService._retrieve() 6 uses a ThreadPoolExecutor to fan out the three search methods in parallel 7:

For HYBRID_SEARCH, both embedding_search and full_text_index_search futures are submitted 8. The pool size is configured via dify_config.RETRIEVAL_SERVICE_EXECUTORS 7.

Score threshold deferral: During hybrid search, the vector score threshold is set to 0.0 at retrieval time so raw embedding scores (which are not comparable to fused scores) do not prematurely drop high-quality chunks. Threshold filtering is applied after fusion instead 9.

Deduplication and Result Fusion#

After the parallel futures complete, _retrieve() handles post-processing exclusively for HYBRID_SEARCH 10:

1. Deduplication — _deduplicate_documents() removes duplicates in O(n) order-preserving fashion. For documents with a doc_id, it keeps the copy with the highest score; for documents without one, it keeps the first occurrence by content key 11.

2. Fusion via DataPostProcessor 12 — dispatches to one of two runners based on reranking_mode:

   • WEIGHTED_SCORE → WeightRerankRunner: Computes a linear combination vector_weight × cosine_similarity + keyword_weight × TF-IDF_cosine. Vector scores reuse the stored retrieval score when available; otherwise cosine similarity is recomputed from the raw document vector . Keyword scores are TF-IDF cosine similarities computed on the fly using Jieba extraction 15.

   • RERANKING_MODEL → RerankModelRunner: Deduplicates by doc_id, then calls an external rerank model via invoke_rerank 16. Multimodal reranking (image queries) is also supported via invoke_multimodal_rerank 17.

3. Post-fusion threshold — if no rerank runner is active, a final score-threshold filter is applied to vector scores 18.

Key Files#