fastembed-haystack 2.3.0__tar.gz → 2.5.0__tar.gz

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [integrations/fastembed-v2.4.0] - 2026-07-30
+
+### 🚀 Features
+
+- *(fastembed)* Allow passing model_kwargs to dense embedders (#3558)
+
+### 🐛 Bug Fixes
+
+- Fix new issues raised by ruff 0.16.0 (#3670)
+
+### 📚 Documentation
+
+- Fix wrong class references in Fastembed sparse embedder messages and docstrings (#3610)
+
+
+## [integrations/fastembed-v2.3.0] - 2026-04-30
+
+### 🚀 Features
+
+- Add score_threshold parameter to FastembedRanker (#3235)
+
+
 ## [integrations/fastembed-v2.2.0] - 2026-04-16
 
 ### 🚀 Features

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastembed-haystack
-Version: 2.3.0
+Version: 2.5.0
 Summary: Haystack 2.x component to embed strings and Documents using fastembed embedding model
 Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/fastembed/README.md

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/pyproject.toml

@@ -132,6 +132,7 @@ ignore = [
   "PLR0912",
   "PLR0913",
   "PLR0915",
+  "PLR0917",
 ]
 
 [tool.ruff.lint.isort]

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/embedders/fastembed/embedding_backend/fastembed_backend.py

@@ -20,14 +20,19 @@ class _FastembedEmbeddingBackendFactory:
         cache_dir: str | None = None,
         threads: int | None = None,
         local_files_only: bool = False,
+        model_kwargs: dict[str, Any] | None = None,
     ) -> "_FastembedEmbeddingBackend":
-        embedding_backend_id = f"{model_name}{cache_dir}{threads}"
+        embedding_backend_id = f"{model_name}{cache_dir}{threads}{local_files_only}{model_kwargs}"
 
         if embedding_backend_id in _FastembedEmbeddingBackendFactory._instances:
             return _FastembedEmbeddingBackendFactory._instances[embedding_backend_id]
 
         embedding_backend = _FastembedEmbeddingBackend(
-            model_name=model_name, cache_dir=cache_dir, threads=threads, local_files_only=local_files_only
+            model_name=model_name,
+            cache_dir=cache_dir,
+            threads=threads,
+            local_files_only=local_files_only,
+            model_kwargs=model_kwargs,
         )
         _FastembedEmbeddingBackendFactory._instances[embedding_backend_id] = embedding_backend
         return embedding_backend
@@ -44,9 +49,16 @@ class _FastembedEmbeddingBackend:
         cache_dir: str | None = None,
         threads: int | None = None,
         local_files_only: bool = False,
+        model_kwargs: dict[str, Any] | None = None,
     ) -> None:
+        model_kwargs = model_kwargs or {}
+
         self.model = TextEmbedding(
-            model_name=model_name, cache_dir=cache_dir, threads=threads, local_files_only=local_files_only
+            model_name=model_name,
+            cache_dir=cache_dir,
+            threads=threads,
+            local_files_only=local_files_only,
+            **model_kwargs,
         )
 
     def embed(self, data: list[str], progress_bar: bool = True, **kwargs: Any) -> list[list[float]]:

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_document_embedder.py

@@ -72,6 +72,7 @@ class FastembedDocumentEmbedder:
         local_files_only: bool = False,
         meta_fields_to_embed: list[str] | None = None,
         embedding_separator: str = "\n",
+        model_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
         Create an FastembedDocumentEmbedder component.
@@ -93,6 +94,8 @@ class FastembedDocumentEmbedder:
         :param local_files_only: If `True`, only use the model files in the `cache_dir`.
         :param meta_fields_to_embed: List of meta fields that should be embedded along with the Document content.
         :param embedding_separator: Separator used to concatenate the meta fields to the Document content.
+        :param model_kwargs: Dictionary containing additional keyword arguments to pass to the Fastembed model,
+                such as `providers` (e.g. `["CUDAExecutionProvider"]` to run on GPU), `cuda`, or `device_ids`.
         """
 
         self.model_name = model
@@ -106,6 +109,7 @@ class FastembedDocumentEmbedder:
         self.local_files_only = local_files_only
         self.meta_fields_to_embed = meta_fields_to_embed or []
         self.embedding_separator = embedding_separator
+        self.model_kwargs = model_kwargs
         self.embedding_backend: _FastembedEmbeddingBackend | None = None
 
     def to_dict(self) -> dict[str, Any]:
@@ -128,6 +132,7 @@ class FastembedDocumentEmbedder:
             local_files_only=self.local_files_only,
             meta_fields_to_embed=self.meta_fields_to_embed,
             embedding_separator=self.embedding_separator,
+            model_kwargs=self.model_kwargs,
         )
 
     def warm_up(self) -> None:
@@ -140,6 +145,7 @@ class FastembedDocumentEmbedder:
                 cache_dir=self.cache_dir,
                 threads=self.threads,
                 local_files_only=self.local_files_only,
+                model_kwargs=self.model_kwargs,
             )
 
     def _prepare_texts_to_embed(self, documents: list[Document]) -> list[str]:

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_sparse_document_embedder.py

@@ -53,7 +53,7 @@ class FastembedSparseDocumentEmbedder:
     result = sparse_doc_embedder.run(document_list)
     print(f"Document Text: {result['documents'][0].content}")
     print(f"Document Sparse Embedding: {result['documents'][0].sparse_embedding}")
-    print(f"Sparse Embedding Dimension: {len(result['documents'][0].sparse_embedding)}")
+    print(f"Number of non-zero elements: {len(result['documents'][0].sparse_embedding.indices)}")
     ```
     """
 
@@ -71,7 +71,7 @@ class FastembedSparseDocumentEmbedder:
         model_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
-        Create an FastembedDocumentEmbedder component.
+        Create a FastembedSparseDocumentEmbedder component.
 
         :param model: Local path or name of the model in Hugging Face's model hub,
             such as `prithivida/Splade_PP_en_v1`.
@@ -162,7 +162,7 @@ class FastembedSparseDocumentEmbedder:
         if not isinstance(documents, list) or (documents and not isinstance(documents[0], Document)):
             msg = (
                 "FastembedSparseDocumentEmbedder expects a list of Documents as input. "
-                "In case you want to embed a list of strings, please use the FastembedTextEmbedder."
+                "In case you want to embed a list of strings, please use the FastembedSparseTextEmbedder."
             )
             raise TypeError(msg)
 

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_sparse_text_embedder.py

@@ -107,13 +107,13 @@ class FastembedSparseTextEmbedder:
 
         :param text: A string to embed.
         :returns: A dictionary with the following keys:
-            - `embedding`: A list of floats representing the embedding of the input text.
+            - `sparse_embedding`: The `SparseEmbedding` of the input text.
         :raises TypeError: If the input is not a string.
         """
         if not isinstance(text, str):
             msg = (
                 "FastembedSparseTextEmbedder expects a string as input. "
-                "In case you want to embed a list of Documents, please use the FastembedDocumentEmbedder."
+                "In case you want to embed a list of Documents, please use the FastembedSparseDocumentEmbedder."
             )
             raise TypeError(msg)
 

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_text_embedder.py

@@ -39,6 +39,7 @@ class FastembedTextEmbedder:
         progress_bar: bool = True,
         parallel: int | None = None,
         local_files_only: bool = False,
+        model_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
         Create a FastembedTextEmbedder component.
@@ -56,6 +57,8 @@ class FastembedTextEmbedder:
                 If 0, use all available cores.
                 If None, don't use data-parallel processing, use default onnxruntime threading instead.
         :param local_files_only: If `True`, only use the model files in the `cache_dir`.
+        :param model_kwargs: Dictionary containing additional keyword arguments to pass to the Fastembed model,
+                such as `providers` (e.g. `["CUDAExecutionProvider"]` to run on GPU), `cuda`, or `device_ids`.
         """
 
         self.model_name = model
@@ -66,6 +69,7 @@ class FastembedTextEmbedder:
         self.progress_bar = progress_bar
         self.parallel = parallel
         self.local_files_only = local_files_only
+        self.model_kwargs = model_kwargs
         self.embedding_backend: _FastembedEmbeddingBackend | None = None
 
     def to_dict(self) -> dict[str, Any]:
@@ -85,6 +89,7 @@ class FastembedTextEmbedder:
             progress_bar=self.progress_bar,
             parallel=self.parallel,
             local_files_only=self.local_files_only,
+            model_kwargs=self.model_kwargs,
         )
 
     def warm_up(self) -> None:
@@ -97,6 +102,7 @@ class FastembedTextEmbedder:
                 cache_dir=self.cache_dir,
                 threads=self.threads,
                 local_files_only=self.local_files_only,
+                model_kwargs=self.model_kwargs,
             )
 
     @component.output_types(embedding=list[float])

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/rankers/fastembed/late_interaction_ranker.py

@@ -189,10 +189,10 @@ class FastembedLateInteractionRanker:
         if not documents:
             return {"documents": []}
 
-        top_k = top_k or self.top_k
-        if top_k <= 0:
+        if top_k is not None and top_k <= 0:
             msg = f"top_k must be > 0, but got {top_k}"
             raise ValueError(msg)
+        top_k = self.top_k if top_k is None else top_k
 
         if self._model is None:
             self.warm_up()

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/src/haystack_integrations/components/rankers/fastembed/ranker.py

@@ -179,10 +179,10 @@ class FastembedRanker:
         if not documents:
             return {"documents": []}
 
-        top_k = top_k or self.top_k
-        if top_k <= 0:
+        if top_k is not None and top_k <= 0:
             msg = f"top_k must be > 0, but got {top_k}"
             raise ValueError(msg)
+        top_k = self.top_k if top_k is None else top_k
 
         if self._model is None:
             self.warm_up()

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/tests/test_fastembed_backend.py

@@ -39,6 +39,23 @@ def test_model_initialization(mock_instructor):
     _FastembedEmbeddingBackendFactory._instances = {}
 
 
+@patch("haystack_integrations.components.embedders.fastembed.embedding_backend.fastembed_backend.TextEmbedding")
+def test_dense_model_kwargs_initialization(mock_instructor):
+    model_kwargs = {"providers": ["CUDAExecutionProvider"]}
+
+    _FastembedEmbeddingBackendFactory.get_embedding_backend(
+        model_name="BAAI/bge-small-en-v1.5",
+        model_kwargs=model_kwargs,
+    )
+
+    mock_instructor.assert_called_once_with(
+        model_name="BAAI/bge-small-en-v1.5", cache_dir=None, threads=None, local_files_only=False, **model_kwargs
+    )
+
+    # restore the factory state
+    _FastembedEmbeddingBackendFactory._instances = {}
+
+
 @patch("haystack_integrations.components.embedders.fastembed.embedding_backend.fastembed_backend.TextEmbedding")
 def test_embedding_function_with_kwargs(mock_instructor):  # noqa: ARG001
     embedding_backend = _FastembedEmbeddingBackendFactory.get_embedding_backend(model_name="BAAI/bge-small-en-v1.5")

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/tests/test_fastembed_document_embedder.py

@@ -80,6 +80,7 @@ class TestFastembedDocumentEmbedder:
                 "local_files_only": False,
                 "embedding_separator": "\n",
                 "meta_fields_to_embed": [],
+                "model_kwargs": None,
             },
         }
 
@@ -99,6 +100,7 @@ class TestFastembedDocumentEmbedder:
             local_files_only=True,
             meta_fields_to_embed=["test_field"],
             embedding_separator=" | ",
+            model_kwargs={"providers": ["CUDAExecutionProvider"]},
         )
         embedder_dict = embedder.to_dict()
         assert embedder_dict == {
@@ -115,6 +117,7 @@ class TestFastembedDocumentEmbedder:
                 "local_files_only": True,
                 "meta_fields_to_embed": ["test_field"],
                 "embedding_separator": " | ",
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
 
@@ -169,6 +172,7 @@ class TestFastembedDocumentEmbedder:
                 "local_files_only": True,
                 "meta_fields_to_embed": ["test_field"],
                 "embedding_separator": " | ",
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
         embedder = default_from_dict(FastembedDocumentEmbedder, embedder_dict)
@@ -183,6 +187,20 @@ class TestFastembedDocumentEmbedder:
         assert embedder.local_files_only
         assert embedder.meta_fields_to_embed == ["test_field"]
         assert embedder.embedding_separator == " | "
+        assert embedder.model_kwargs == {"providers": ["CUDAExecutionProvider"]}
+
+    def test_init_with_model_kwargs_parameters(self):
+        """
+        Test initialization of FastembedDocumentEmbedder with model_kwargs parameters.
+        """
+        model_kwargs = {"providers": ["CUDAExecutionProvider"]}
+
+        embedder = FastembedDocumentEmbedder(
+            model="BAAI/bge-small-en-v1.5",
+            model_kwargs=model_kwargs,
+        )
+
+        assert embedder.model_kwargs == model_kwargs
 
     @patch(
         "haystack_integrations.components.embedders.fastembed.fastembed_document_embedder._FastembedEmbeddingBackendFactory"
@@ -195,7 +213,7 @@ class TestFastembedDocumentEmbedder:
         mocked_factory.get_embedding_backend.assert_not_called()
         embedder.warm_up()
         mocked_factory.get_embedding_backend.assert_called_once_with(
-            model_name="BAAI/bge-small-en-v1.5", cache_dir=None, threads=None, local_files_only=False
+            model_name="BAAI/bge-small-en-v1.5", cache_dir=None, threads=None, local_files_only=False, model_kwargs=None
         )
 
     @patch(
@@ -295,6 +313,28 @@ class TestFastembedDocumentEmbedder:
 
         mock_warm_up.assert_called_once()
 
+    @pytest.mark.integration
+    def test_run_with_model_kwargs(self):
+        """
+        Integration test to check the embedding with model_kwargs parameters.
+        """
+        model_kwargs = {"providers": ["CPUExecutionProvider"], "lazy_load": True}
+
+        embedder = FastembedDocumentEmbedder(
+            model="BAAI/bge-small-en-v1.5",
+            model_kwargs=model_kwargs,
+        )
+        embedder.warm_up()
+
+        doc = Document(content="Parton energy loss in QCD matter")
+
+        result = embedder.run(documents=[doc])
+        embedding = result["documents"][0].embedding
+
+        assert isinstance(embedding, list)
+        assert len(embedding) == 384
+        assert all(isinstance(emb, float) for emb in embedding)
+
     @pytest.mark.integration
     def test_run(self):
         embedder = FastembedDocumentEmbedder(

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/tests/test_fastembed_late_interaction_ranker.py

@@ -222,6 +222,25 @@ class TestFastembedLateInteractionRanker:
         ):
             ranker.run(query=query, documents=list_document, top_k=-3)
 
+        with pytest.raises(
+            ValueError,
+            match="top_k must be > 0, but got 0",
+        ):
+            ranker.run(query=query, documents=list_document, top_k=0)
+
+    def test_run_runtime_top_k_zero_does_not_fall_back_to_instance_top_k(self):
+        """
+        A runtime top_k=0 must raise, not silently fall back to the instance top_k.
+        """
+        ranker = FastembedLateInteractionRanker(model_name="colbert-ir/colbertv2.0", top_k=5)
+        ranker._model = "mock_model"
+
+        with pytest.raises(
+            ValueError,
+            match="top_k must be > 0, but got 0",
+        ):
+            ranker.run(query="query", documents=[Document("Document 1")], top_k=0)
+
     def test_run_empty_document_list(self):
         """
         Test for no error when sending no documents.

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/tests/test_fastembed_ranker.py

@@ -226,6 +226,12 @@ class TestFastembedRanker:
         ):
             ranker.run(query=query, documents=list_document, top_k=-3)
 
+        with pytest.raises(
+            ValueError,
+            match="top_k must be > 0, but got 0",
+        ):
+            ranker.run(query=query, documents=list_document, top_k=0)
+
     def test_run_empty_document_list(self):
         """
         Test for no error when sending no documents.

{fastembed_haystack-2.3.0 → fastembed_haystack-2.5.0}/tests/test_fastembed_text_embedder.py

@@ -65,6 +65,7 @@ class TestFastembedTextEmbedder:
                 "progress_bar": True,
                 "parallel": None,
                 "local_files_only": False,
+                "model_kwargs": None,
             },
         }
 
@@ -81,6 +82,7 @@ class TestFastembedTextEmbedder:
             progress_bar=False,
             parallel=1,
             local_files_only=True,
+            model_kwargs={"providers": ["CUDAExecutionProvider"]},
         )
         embedder_dict = embedder.to_dict()
         assert embedder_dict == {
@@ -94,6 +96,7 @@ class TestFastembedTextEmbedder:
                 "progress_bar": False,
                 "parallel": 1,
                 "local_files_only": True,
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
 
@@ -136,6 +139,7 @@ class TestFastembedTextEmbedder:
                 "suffix": "suffix",
                 "progress_bar": False,
                 "parallel": 1,
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
         embedder = default_from_dict(FastembedTextEmbedder, embedder_dict)
@@ -146,6 +150,20 @@ class TestFastembedTextEmbedder:
         assert embedder.suffix == "suffix"
         assert embedder.progress_bar is False
         assert embedder.parallel == 1
+        assert embedder.model_kwargs == {"providers": ["CUDAExecutionProvider"]}
+
+    def test_init_with_model_kwargs_parameters(self):
+        """
+        Test initialization of FastembedTextEmbedder with model_kwargs parameters.
+        """
+        model_kwargs = {"providers": ["CUDAExecutionProvider"]}
+
+        embedder = FastembedTextEmbedder(
+            model="BAAI/bge-small-en-v1.5",
+            model_kwargs=model_kwargs,
+        )
+
+        assert embedder.model_kwargs == model_kwargs
 
     @patch(
         "haystack_integrations.components.embedders.fastembed.fastembed_text_embedder._FastembedEmbeddingBackendFactory"
@@ -158,7 +176,7 @@ class TestFastembedTextEmbedder:
         mocked_factory.get_embedding_backend.assert_not_called()
         embedder.warm_up()
         mocked_factory.get_embedding_backend.assert_called_once_with(
-            model_name="BAAI/bge-small-en-v1.5", cache_dir=None, threads=None, local_files_only=False
+            model_name="BAAI/bge-small-en-v1.5", cache_dir=None, threads=None, local_files_only=False, model_kwargs=None
         )
 
     @patch(
@@ -216,6 +234,28 @@ class TestFastembedTextEmbedder:
 
         mock_warm_up.assert_called_once()
 
+    @pytest.mark.integration
+    def test_run_with_model_kwargs(self):
+        """
+        Integration test to check the embedding with model_kwargs parameters.
+        """
+        model_kwargs = {"providers": ["CPUExecutionProvider"], "lazy_load": True}
+
+        embedder = FastembedTextEmbedder(
+            model="BAAI/bge-small-en-v1.5",
+            model_kwargs=model_kwargs,
+        )
+        embedder.warm_up()
+
+        text = "Parton energy loss in QCD matter"
+
+        result = embedder.run(text=text)
+        embedding = result["embedding"]
+
+        assert isinstance(embedding, list)
+        assert len(embedding) == 384
+        assert all(isinstance(emb, float) for emb in embedding)
+
     @pytest.mark.integration
     def test_run(self):
         embedder = FastembedTextEmbedder(