fastembed-haystack 2.2.0__tar.gz → 2.4.0__tar.gz

{fastembed_haystack-2.2.0 → fastembed_haystack-2.4.0}/CHANGELOG.md

@@ -1,20 +1,41 @@
 # Changelog
 
-## [integrations/fastembed-v2.1.0] - 2026-02-13
+## [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
+
+- Update `FastembedRanker` to auto call `warm_up` on first run (#2834)
+- Add FastembedLateInteractionRanker for ColBERT late-interaction reranking (#3135)
+
+### 🐛 Bug Fixes
+
+- Replace in-place dataclass mutations with dataclasses.replace() (#3112)
 
 ### 📚 Documentation
 
 - *(fastembed)* Remove explicit warm_up from examples (#2830)
+- Simplify pydoc configs (#2855)
+
+### 🧪 Testing
+
+- Track test coverage for all integrations (#3065)
+
+### 🧹 Chores
+
+- Add ANN type annotations to faiss, fastembed, firecrawl, github, google_ai (#2988)
+- Enforce ruff docstring rules (D102/D103/D205/D209/D213/D417/D419) in integrations 11-20 (#3009)
 
 ### 🌀 Miscellaneous
 
-- Automatically call warm_up() if model is not loaded in FastembedRanker
-- Remove explicit call to warm_up() in ranker_example.py
-- Add unit tests
 - Fix typing issue
 - Fix tying
-- Update docstrings
-- Remove explicit warm_up calls from integration tests
 
 ## [integrations/fastembed-v2.0.0] - 2026-01-12
 

{fastembed_haystack-2.2.0 → fastembed_haystack-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastembed-haystack
-Version: 2.2.0
+Version: 2.4.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.2.0 → fastembed_haystack-2.4.0}/pyproject.toml

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

{fastembed_haystack-2.2.0 → fastembed_haystack-2.4.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.2.0 → fastembed_haystack-2.4.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.2.0 → fastembed_haystack-2.4.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_sparse_document_embedder.py

@@ -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.2.0 → fastembed_haystack-2.4.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.2.0 → fastembed_haystack-2.4.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.2.0 → fastembed_haystack-2.4.0}/src/haystack_integrations/components/rankers/fastembed/ranker.py

@@ -48,6 +48,7 @@ class FastembedRanker:
         local_files_only: bool = False,
         meta_fields_to_embed: list[str] | None = None,
         meta_data_separator: str = "\n",
+        score_threshold: float | None = None,
     ) -> None:
         """
         Creates an instance of the 'FastembedRanker'.
@@ -68,6 +69,8 @@ class FastembedRanker:
             with the document content for reranking.
         :param meta_data_separator: Separator used to concatenate the meta fields
             to the Document content.
+        :param score_threshold: If provided, only documents with a score above the threshold are returned.
+            Applied after `top_k`, so the output may contain fewer than `top_k` documents.
         """
         if top_k <= 0:
             msg = f"top_k must be > 0, but got {top_k}"
@@ -82,6 +85,7 @@ class FastembedRanker:
         self.local_files_only = local_files_only
         self.meta_fields_to_embed = meta_fields_to_embed or []
         self.meta_data_separator = meta_data_separator
+        self.score_threshold = score_threshold
         self._model: TextCrossEncoder | None = None
 
     def to_dict(self) -> dict[str, Any]:
@@ -102,6 +106,7 @@ class FastembedRanker:
             local_files_only=self.local_files_only,
             meta_fields_to_embed=self.meta_fields_to_embed,
             meta_data_separator=self.meta_data_separator,
+            score_threshold=self.score_threshold,
         )
 
     @classmethod
@@ -201,4 +206,8 @@ class FastembedRanker:
 
         top_k_documents = [replace(doc, score=score) for doc, score in sorted_doc_scores[:top_k]]
 
+        score_threshold = self.score_threshold
+        if score_threshold is not None:
+            top_k_documents = [doc for doc in top_k_documents if doc.score is not None and doc.score >= score_threshold]
+
         return {"documents": top_k_documents}

{fastembed_haystack-2.2.0 → fastembed_haystack-2.4.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.2.0 → fastembed_haystack-2.4.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.2.0 → fastembed_haystack-2.4.0}/tests/test_fastembed_ranker.py

@@ -28,6 +28,7 @@ class TestFastembedRanker:
         assert not ranker.local_files_only
         assert ranker.meta_fields_to_embed == []
         assert ranker.meta_data_separator == "\n"
+        assert ranker.score_threshold is None
 
     def test_init_with_parameters(self):
         """
@@ -43,6 +44,7 @@ class TestFastembedRanker:
             local_files_only=True,
             meta_fields_to_embed=["test_field"],
             meta_data_separator=" | ",
+            score_threshold=0.5,
         )
         assert ranker.model_name == "BAAI/bge-reranker-base"
         assert ranker.top_k == 64
@@ -53,6 +55,7 @@ class TestFastembedRanker:
         assert ranker.local_files_only
         assert ranker.meta_fields_to_embed == ["test_field"]
         assert ranker.meta_data_separator == " | "
+        assert ranker.score_threshold == 0.5
 
     def test_init_with_incorrect_input(self):
         """
@@ -88,6 +91,7 @@ class TestFastembedRanker:
                 "local_files_only": False,
                 "meta_fields_to_embed": [],
                 "meta_data_separator": "\n",
+                "score_threshold": None,
             },
         }
 
@@ -105,6 +109,7 @@ class TestFastembedRanker:
             local_files_only=True,
             meta_fields_to_embed=["test_field"],
             meta_data_separator=" | ",
+            score_threshold=0.5,
         )
         ranker_dict = ranker.to_dict()
         assert ranker_dict == {
@@ -119,6 +124,7 @@ class TestFastembedRanker:
                 "local_files_only": True,
                 "meta_fields_to_embed": ["test_field"],
                 "meta_data_separator": " | ",
+                "score_threshold": 0.5,
             },
         }
 
@@ -138,6 +144,7 @@ class TestFastembedRanker:
                 "local_files_only": False,
                 "meta_fields_to_embed": [],
                 "meta_data_separator": "\n",
+                "score_threshold": None,
             },
         }
         ranker = default_from_dict(FastembedRanker, ranker_dict)
@@ -150,6 +157,7 @@ class TestFastembedRanker:
         assert not ranker.local_files_only
         assert ranker.meta_fields_to_embed == []
         assert ranker.meta_data_separator == "\n"
+        assert ranker.score_threshold is None
 
     def test_from_dict_with_custom_init_parameters(self):
         """
@@ -167,6 +175,7 @@ class TestFastembedRanker:
                 "local_files_only": True,
                 "meta_fields_to_embed": ["test_field"],
                 "meta_data_separator": " | ",
+                "score_threshold": 0.5,
             },
         }
         ranker = default_from_dict(FastembedRanker, ranker_dict)
@@ -179,6 +188,7 @@ class TestFastembedRanker:
         assert ranker.local_files_only
         assert ranker.meta_fields_to_embed == ["test_field"]
         assert ranker.meta_data_separator == " | "
+        assert ranker.score_threshold == 0.5
 
     def test_run_incorrect_input_format(self):
         """
@@ -257,6 +267,20 @@ class TestFastembedRanker:
             parallel=None,
         )
 
+    def test_run_with_score_threshold(self):
+        """
+        Tests that documents below score_threshold are filtered out.
+        """
+        ranker = FastembedRanker(model_name="model_name", score_threshold=0.5)
+        ranker._model = MagicMock()
+        ranker._model.rerank.return_value = [0.9, 0.3, 0.7]
+
+        documents = [Document(content=f"doc {i}") for i in range(3)]
+        result = ranker.run(query="test", documents=documents)
+
+        assert len(result["documents"]) == 2
+        assert all(doc.score >= 0.5 for doc in result["documents"])
+
     def test_run_calls_warm_up(self):
         """
         Unit test to check that warm_up is called when run is called for the first time.

{fastembed_haystack-2.2.0 → fastembed_haystack-2.4.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(