[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
refactor: rename hybrid-search weight `gemma` → `vector_weight` (#324)
Abi68cc0da5ff85
diff --git a/packages/leann-core/src/leann/api.py b/packages/leann-core/src/leann/api.pyindex 26f23f2..cf57bb4 100644--- a/packages/leann-core/src/leann/api.py+++ b/packages/leann-core/src/leann/api.py@@ -1165,7 +1165,7 @@ class LeannSearcher:metadata_filters: Optional[dict[str, dict[str, Union[str, int, float, bool, list]]]] = None,batch_size: int = 0,use_grep: bool = False,- gemma: float = 1.0,+ vector_weight: float = 1.0,provider_options: Optional[dict[str, Any]] = None,**kwargs,) -> list[SearchResult]:@@ -1189,12 +1189,26 @@ class LeannSearcher:- Membership: "in", "not_in"- String: "contains", "starts_with", "ends_with"Example: {"chapter": {"<=": 5}, "tags": {"in": ["fiction", "drama"]}}- gemma: Weight of vector search results in hybrid search (0.0-1.0), 1 = pure vector search, 0 = pure keyword search- **kwargs: Backend-specific parameters+ vector_weight: Weight of vector search in hybrid scoring (0.0-1.0).+ 1.0 = pure vector search (default), 0.0 = pure BM25 keyword search,+ anything in between linearly fuses the two.+ **kwargs: Backend-specific parameters. Accepts a deprecated `gemma=` alias+ for `vector_weight`; passing it emits a DeprecationWarning.Returns:List of SearchResult objects with text, metadata, and similarity scores"""+ # Accept the legacy `gemma=` kwarg (typo of "gamma") as a deprecated alias+ # for vector_weight. Pop before forwarding to backend so it doesn't leak.+ if "gemma" in kwargs:+ warnings.warn(+ "search(gemma=...) is deprecated and will be removed in a future release; "+ "use vector_weight= instead.",+ DeprecationWarning,+ stacklevel=2,+ )+ vector_weight = kwargs.pop("gemma")+# Handle grep searchif use_grep:return self._grep_search(query, top_k)@@ -1218,7 +1232,7 @@ class LeannSearcher:logger.warning(f" ✅ Auto-adjusted top_k to {top_k} to match available documents")# Handle pure keyword search- if gemma == 0.0:+ if vector_weight == 0.0:start_time = time.time()bm25_results = self._bm25_search(query, top_k)# Convert BM25 results to the expected format@@ -1303,22 +1317,22 @@ class LeannSearcher:)# Handle hybrid search- if 0.0 < gemma < 1.0:- logger.info(f" 🌟 Hybrid search enabled with gemma={gemma}")- BM25_WEIGHT = 1.0 - gemma+ if 0.0 < vector_weight < 1.0:+ logger.info(f" 🌟 Hybrid search enabled with vector_weight={vector_weight}")+ bm25_weight = 1.0 - vector_weightbm25_results = self._bm25_search(query, top_k)hybrid_scores: dict[str, float] = {}- # Add vector search scores (weighted by gemma)+ # Add vector search scores (weighted by vector_weight)if "labels" in results and "distances" in results:for doc_id, score in zip(results["labels"][0], results["distances"][0]):- hybrid_scores[doc_id] = gemma * score- # Add BM25 scores (weighted by BM25_WEIGHT)+ hybrid_scores[doc_id] = vector_weight * score+ # Add BM25 scores (weighted by bm25_weight)for bm25_result in bm25_results:doc_id = bm25_result.idif doc_id in hybrid_scores:- hybrid_scores[doc_id] += BM25_WEIGHT * bm25_result.score+ hybrid_scores[doc_id] += bm25_weight * bm25_result.scoreelse:- hybrid_scores[doc_id] = BM25_WEIGHT * bm25_result.score+ hybrid_scores[doc_id] = bm25_weight * bm25_result.scoresorted_hybrid = sorted(hybrid_scores.items(), key=lambda x: x[1], reverse=True)[:top_k]results["labels"] = [[doc_id for doc_id, _ in sorted_hybrid]]@@ -1555,9 +1569,17 @@ class LeannChat:metadata_filters: Optional[dict[str, dict[str, Union[str, int, float, bool, list]]]] = None,batch_size: int = 0,use_grep: bool = False,- gemma: float = 1.0,+ vector_weight: float = 1.0,**search_kwargs,):+ if "gemma" in search_kwargs:+ warnings.warn(+ "ask(gemma=...) is deprecated; use vector_weight= instead.",+ DeprecationWarning,+ stacklevel=2,+ )+ vector_weight = search_kwargs.pop("gemma")+if llm_kwargs is None:llm_kwargs = {}search_time = time.time()@@ -1572,7 +1594,7 @@ class LeannChat:expected_zmq_port=expected_zmq_port,metadata_filters=metadata_filters,use_grep=use_grep,- gemma=gemma,+ vector_weight=vector_weight,batch_size=batch_size,**search_kwargs,)diff --git a/tests/test_hybrid_search.py b/tests/test_hybrid_search.pyindex 61a1329..0ef16bf 100644--- a/tests/test_hybrid_search.py+++ b/tests/test_hybrid_search.py@@ -2,7 +2,7 @@Comprehensive tests for hybrid search functionality.This module tests the hybrid search feature that combines vector search-with BM25 keyword search using the gemma parameter.+with BM25 keyword search using the vector_weight parameter."""import os@@ -60,11 +60,11 @@ class TestHybridSearch:searcher.cleanup()def test_pure_vector_search(self, sample_index):- """Test pure vector search (gemma=1.0, default)."""+ """Test pure vector search (vector_weight=1.0, default)."""searcher, texts = sample_index- # Search with gemma=1.0 (pure vector search)- results = searcher.search("canine animal", top_k=3, gemma=1.0)+ # Search with vector_weight=1.0 (pure vector search)+ results = searcher.search("canine animal", top_k=3, vector_weight=1.0)assert len(results) > 0assert len(results) <= 3@@ -75,11 +75,11 @@ class TestHybridSearch:)def test_pure_keyword_search(self, sample_index):- """Test pure keyword search (gemma=0.0)."""+ """Test pure keyword search (vector_weight=0.0)."""searcher, texts = sample_index- # Search with gemma=0.0 (pure BM25 keyword search)- results = searcher.search("database SQL", top_k=3, gemma=0.0)+ # Search with vector_weight=0.0 (pure BM25 keyword search)+ results = searcher.search("database SQL", top_k=3, vector_weight=0.0)assert len(results) > 0assert len(results) <= 3@@ -89,11 +89,11 @@ class TestHybridSearch:assert "database" in top_result_text or "sql" in top_result_textdef test_hybrid_search_balanced(self, sample_index):- """Test balanced hybrid search (gemma=0.5)."""+ """Test balanced hybrid search (vector_weight=0.5)."""searcher, texts = sample_index- # Search with gemma=0.5 (balanced hybrid)- results = searcher.search("programming Python code", top_k=5, gemma=0.5)+ # Search with vector_weight=0.5 (balanced hybrid)+ results = searcher.search("programming Python code", top_k=5, vector_weight=0.5)assert len(results) > 0assert len(results) <= 5@@ -102,11 +102,11 @@ class TestHybridSearch:assert any("python" in r.text.lower() or "programming" in r.text.lower() for r in results)def test_hybrid_search_vector_heavy(self, sample_index):- """Test vector-heavy hybrid search (gemma=0.8)."""+ """Test vector-heavy hybrid search (vector_weight=0.8)."""searcher, texts = sample_index- # Search with gemma=0.8 (mostly vector, some keyword)- results = searcher.search("sunny weather conditions", top_k=3, gemma=0.8)+ # Search with vector_weight=0.8 (mostly vector, some keyword)+ results = searcher.search("sunny weather conditions", top_k=3, vector_weight=0.8)assert len(results) > 0# Should prioritize semantic similarity but consider keywords@@ -117,11 +117,11 @@ class TestHybridSearch:)def test_hybrid_search_keyword_heavy(self, sample_index):- """Test keyword-heavy hybrid search (gemma=0.2)."""+ """Test keyword-heavy hybrid search (vector_weight=0.2)."""searcher, texts = sample_index- # Search with gemma=0.2 (mostly keyword, some vector)- results = searcher.search("bread flour baking", top_k=3, gemma=0.2)+ # Search with vector_weight=0.2 (mostly keyword, some vector)+ results = searcher.search("bread flour baking", top_k=3, vector_weight=0.2)assert len(results) > 0# Should prioritize keyword matches@@ -137,10 +137,10 @@ class TestHybridSearch:"""Test that hybrid search properly combines scores."""searcher, texts = sample_index- # Get results with different gemma values- pure_vector = searcher.search("machine learning AI", top_k=5, gemma=1.0)- pure_keyword = searcher.search("machine learning AI", top_k=5, gemma=0.0)- hybrid = searcher.search("machine learning AI", top_k=5, gemma=0.5)+ # Get results with different vector_weight values+ pure_vector = searcher.search("machine learning AI", top_k=5, vector_weight=1.0)+ pure_keyword = searcher.search("machine learning AI", top_k=5, vector_weight=0.0)+ hybrid = searcher.search("machine learning AI", top_k=5, vector_weight=0.5)# All should return resultsassert len(pure_vector) > 0@@ -157,7 +157,7 @@ class TestHybridSearch:# Search with hybrid and metadata filterresults = searcher.search(- "data information", top_k=5, gemma=0.6, metadata_filters={"doc_num": {"<": 8}}+ "data information", top_k=5, vector_weight=0.6, metadata_filters={"doc_num": {"<": 8}})assert len(results) > 0