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

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

@@ -1,5 +1,32 @@
 # Changelog
 
+## [unreleased]
+
+### 🐛 Bug Fixes
+
+- `FastembedLateInteractionRanker` reordered the top_k fallback to happen after validation (#3746)
+- `FastEmbedder` reordered the top_k fallback to happen after validation (#3745)
+
+### 📚 Documentation
+
+- Fix TypeError in FastembedSparseDocumentEmbedder usage example (#3731)
+
+
+## [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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fastembed-haystack
-Version: 2.4.0
+Version: 2.6.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.4.0 → fastembed_haystack-2.6.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_document_embedder.py

@@ -57,6 +57,21 @@ class FastembedDocumentEmbedder:
     print(f"Document Embedding: {result['documents'][0].embedding}")
     print(f"Embedding Dimension: {len(result['documents'][0].embedding)}")
     ```
+
+    Running on GPU:
+    ```python
+    # NVIDIA GPU (requires onnxruntime-gpu)
+    doc_embedder = FastembedDocumentEmbedder(
+        model="BAAI/bge-small-en-v1.5",
+        model_kwargs={"providers": ["CUDAExecutionProvider"]},
+    )
+
+    # Intel GPU / XPU (requires onnxruntime-openvino)
+    doc_embedder = FastembedDocumentEmbedder(
+        model="BAAI/bge-small-en-v1.5",
+        model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+    )
+    ```
     """
 
     def __init__(
@@ -95,7 +110,8 @@ class FastembedDocumentEmbedder:
         :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`.
+                such as `providers` (e.g. `["CUDAExecutionProvider"]` for NVIDIA GPU or
+                `["OpenVINOExecutionProvider"]` for Intel GPU/XPU), `cuda`, or `device_ids`.
         """
 
         self.model_name = model

{fastembed_haystack-2.4.0 → fastembed_haystack-2.6.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)}")
     ```
     """
 

{fastembed_haystack-2.4.0 → fastembed_haystack-2.6.0}/src/haystack_integrations/components/embedders/fastembed/fastembed_text_embedder.py

@@ -27,6 +27,21 @@ class FastembedTextEmbedder:
 
     embedding = text_embedder.run(text)["embedding"]
     ```
+
+    Running on GPU:
+    ```python
+    # NVIDIA GPU (requires onnxruntime-gpu)
+    text_embedder = FastembedTextEmbedder(
+        model="BAAI/bge-small-en-v1.5",
+        model_kwargs={"providers": ["CUDAExecutionProvider"]},
+    )
+
+    # Intel GPU / XPU (requires onnxruntime-openvino)
+    text_embedder = FastembedTextEmbedder(
+        model="BAAI/bge-small-en-v1.5",
+        model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+    )
+    ```
     """
 
     def __init__(
@@ -58,7 +73,8 @@ class FastembedTextEmbedder:
                 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`.
+                such as `providers` (e.g. `["CUDAExecutionProvider"]` for NVIDIA GPU or
+                `["OpenVINOExecutionProvider"]` for Intel GPU/XPU), `cuda`, or `device_ids`.
         """
 
         self.model_name = model

{fastembed_haystack-2.4.0 → fastembed_haystack-2.6.0}/src/haystack_integrations/components/rankers/fastembed/late_interaction_ranker.py

@@ -38,6 +38,21 @@ class FastembedLateInteractionRanker:
 
     # Berlin
     ```
+
+    Running on GPU:
+    ```python
+    # NVIDIA GPU (requires onnxruntime-gpu)
+    ranker = FastembedLateInteractionRanker(
+        model_name="colbert-ir/colbertv2.0",
+        model_kwargs={"providers": ["CUDAExecutionProvider"]},
+    )
+
+    # Intel GPU / XPU (requires onnxruntime-openvino)
+    ranker = FastembedLateInteractionRanker(
+        model_name="colbert-ir/colbertv2.0",
+        model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+    )
+    ```
     """
 
     def __init__(
@@ -52,6 +67,7 @@ class FastembedLateInteractionRanker:
         meta_fields_to_embed: list[str] | None = None,
         meta_data_separator: str = "\n",
         score_threshold: float | None = None,
+        model_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
         Creates an instance of the 'FastembedLateInteractionRanker'.
@@ -75,6 +91,9 @@ class FastembedLateInteractionRanker:
             to the Document content.
         :param score_threshold: If provided, only documents with a score above the threshold are returned.
             Note that ColBERT scores are unnormalized sums and typically range from 3 to 25.
+        :param model_kwargs: Dictionary containing additional keyword arguments to pass to the Fastembed model,
+                such as `providers` (e.g. `["CUDAExecutionProvider"]` to run on an NVIDIA GPU or
+                `["OpenVINOExecutionProvider"]` to run on an Intel GPU), `cuda`, or `device_ids`.
         """
         if top_k <= 0:
             msg = f"top_k must be > 0, but got {top_k}"
@@ -90,6 +109,7 @@ class FastembedLateInteractionRanker:
         self.meta_fields_to_embed = meta_fields_to_embed or []
         self.meta_data_separator = meta_data_separator
         self.score_threshold = score_threshold
+        self.model_kwargs = model_kwargs
         self._model: LateInteractionTextEmbedding | None = None
 
     def to_dict(self) -> dict[str, Any]:
@@ -111,6 +131,7 @@ class FastembedLateInteractionRanker:
             meta_fields_to_embed=self.meta_fields_to_embed,
             meta_data_separator=self.meta_data_separator,
             score_threshold=self.score_threshold,
+            model_kwargs=self.model_kwargs,
         )
 
     @classmethod
@@ -130,11 +151,13 @@ class FastembedLateInteractionRanker:
         Initializes the component.
         """
         if self._model is None:
+            model_kwargs = self.model_kwargs or {}
             self._model = LateInteractionTextEmbedding(
                 model_name=self.model_name,
                 cache_dir=self.cache_dir,
                 threads=self.threads,
                 local_files_only=self.local_files_only,
+                **model_kwargs,
             )
 
     def _prepare_fastembed_input_docs(self, documents: list[Document]) -> list[str]:
@@ -189,10 +212,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.4.0 → fastembed_haystack-2.6.0}/src/haystack_integrations/components/rankers/fastembed/ranker.py

@@ -35,6 +35,21 @@ class FastembedRanker:
 
     # Berlin
     ```
+
+    Running on GPU:
+    ```python
+    # NVIDIA GPU (requires onnxruntime-gpu)
+    ranker = FastembedRanker(
+        model_name="Xenova/ms-marco-MiniLM-L-6-v2",
+        model_kwargs={"providers": ["CUDAExecutionProvider"]},
+    )
+
+    # Intel GPU / XPU (requires onnxruntime-openvino)
+    ranker = FastembedRanker(
+        model_name="Xenova/ms-marco-MiniLM-L-6-v2",
+        model_kwargs={"providers": ["OpenVINOExecutionProvider"]},
+    )
+    ```
     """
 
     def __init__(
@@ -49,6 +64,7 @@ class FastembedRanker:
         meta_fields_to_embed: list[str] | None = None,
         meta_data_separator: str = "\n",
         score_threshold: float | None = None,
+        model_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
         Creates an instance of the 'FastembedRanker'.
@@ -71,6 +87,9 @@ class FastembedRanker:
             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.
+        :param model_kwargs: Dictionary containing additional keyword arguments to pass to the Fastembed model,
+                such as `providers` (e.g. `["CUDAExecutionProvider"]` to run on an NVIDIA GPU or
+                `["OpenVINOExecutionProvider"]` to run on an Intel GPU), `cuda`, or `device_ids`.
         """
         if top_k <= 0:
             msg = f"top_k must be > 0, but got {top_k}"
@@ -86,6 +105,7 @@ class FastembedRanker:
         self.meta_fields_to_embed = meta_fields_to_embed or []
         self.meta_data_separator = meta_data_separator
         self.score_threshold = score_threshold
+        self.model_kwargs = model_kwargs
         self._model: TextCrossEncoder | None = None
 
     def to_dict(self) -> dict[str, Any]:
@@ -107,6 +127,7 @@ class FastembedRanker:
             meta_fields_to_embed=self.meta_fields_to_embed,
             meta_data_separator=self.meta_data_separator,
             score_threshold=self.score_threshold,
+            model_kwargs=self.model_kwargs,
         )
 
     @classmethod
@@ -126,11 +147,13 @@ class FastembedRanker:
         Initializes the component.
         """
         if self._model is None:
+            model_kwargs = self.model_kwargs or {}
             self._model = TextCrossEncoder(
                 model_name=self.model_name,
                 cache_dir=self.cache_dir,
                 threads=self.threads,
                 local_files_only=self.local_files_only,
+                **model_kwargs,
             )
 
     def _prepare_fastembed_input_docs(self, documents: list[Document]) -> list[str]:
@@ -179,10 +202,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.4.0 → fastembed_haystack-2.6.0}/tests/test_fastembed_late_interaction_ranker.py

@@ -54,6 +54,19 @@ class TestFastembedLateInteractionRanker:
         assert ranker.meta_fields_to_embed == ["test_field"]
         assert ranker.meta_data_separator == " | "
 
+    def test_init_with_model_kwargs_parameters(self):
+        """
+        Test initialization of FastembedLateInteractionRanker with model_kwargs parameters.
+        """
+        model_kwargs = {"providers": ["CUDAExecutionProvider"]}
+
+        ranker = FastembedLateInteractionRanker(
+            model_name="colbert-ir/colbertv2.0",
+            model_kwargs=model_kwargs,
+        )
+
+        assert ranker.model_kwargs == model_kwargs
+
     def test_init_with_incorrect_input(self):
         """
         Test for checking incorrect input format on init.
@@ -90,6 +103,7 @@ class TestFastembedLateInteractionRanker:
                 "meta_fields_to_embed": [],
                 "meta_data_separator": "\n",
                 "score_threshold": None,
+                "model_kwargs": None,
             },
         }
 
@@ -107,6 +121,7 @@ class TestFastembedLateInteractionRanker:
             local_files_only=True,
             meta_fields_to_embed=["test_field"],
             meta_data_separator=" | ",
+            model_kwargs={"providers": ["CUDAExecutionProvider"]},
         )
         ranker_dict = ranker.to_dict()
         assert ranker_dict == {
@@ -123,6 +138,7 @@ class TestFastembedLateInteractionRanker:
                 "meta_fields_to_embed": ["test_field"],
                 "meta_data_separator": " | ",
                 "score_threshold": None,
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
 
@@ -173,6 +189,7 @@ class TestFastembedLateInteractionRanker:
                 "local_files_only": True,
                 "meta_fields_to_embed": ["test_field"],
                 "meta_data_separator": " | ",
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
         ranker = default_from_dict(FastembedLateInteractionRanker, ranker_dict)
@@ -185,6 +202,7 @@ class TestFastembedLateInteractionRanker:
         assert ranker.local_files_only
         assert ranker.meta_fields_to_embed == ["test_field"]
         assert ranker.meta_data_separator == " | "
+        assert ranker.model_kwargs == {"providers": ["CUDAExecutionProvider"]}
 
     def test_run_incorrect_input_format(self):
         """
@@ -222,6 +240,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.
@@ -278,6 +315,26 @@ class TestFastembedLateInteractionRanker:
             ranker.warm_up()
             mock_cls.assert_called_once()
 
+    def test_warm_up_forwards_model_kwargs(self):
+        """
+        Test that model_kwargs (e.g. GPU providers) are forwarded to the underlying Fastembed model.
+        """
+        ranker = FastembedLateInteractionRanker(
+            model_name="colbert-ir/colbertv2.0",
+            model_kwargs={"providers": ["CUDAExecutionProvider"]},
+        )
+        with patch(
+            "haystack_integrations.components.rankers.fastembed.late_interaction_ranker.LateInteractionTextEmbedding"
+        ) as mock_cls:
+            ranker.warm_up()
+            mock_cls.assert_called_once_with(
+                model_name="colbert-ir/colbertv2.0",
+                cache_dir=None,
+                threads=None,
+                local_files_only=False,
+                providers=["CUDAExecutionProvider"],
+            )
+
     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.4.0 → fastembed_haystack-2.6.0}/tests/test_fastembed_ranker.py

@@ -57,6 +57,19 @@ class TestFastembedRanker:
         assert ranker.meta_data_separator == " | "
         assert ranker.score_threshold == 0.5
 
+    def test_init_with_model_kwargs_parameters(self):
+        """
+        Test initialization of FastembedRanker with model_kwargs parameters.
+        """
+        model_kwargs = {"providers": ["CUDAExecutionProvider"]}
+
+        ranker = FastembedRanker(
+            model_name="BAAI/bge-reranker-base",
+            model_kwargs=model_kwargs,
+        )
+
+        assert ranker.model_kwargs == model_kwargs
+
     def test_init_with_incorrect_input(self):
         """
         Test for checking incorrect input format on init
@@ -92,6 +105,7 @@ class TestFastembedRanker:
                 "meta_fields_to_embed": [],
                 "meta_data_separator": "\n",
                 "score_threshold": None,
+                "model_kwargs": None,
             },
         }
 
@@ -110,6 +124,7 @@ class TestFastembedRanker:
             meta_fields_to_embed=["test_field"],
             meta_data_separator=" | ",
             score_threshold=0.5,
+            model_kwargs={"providers": ["CUDAExecutionProvider"]},
         )
         ranker_dict = ranker.to_dict()
         assert ranker_dict == {
@@ -125,6 +140,7 @@ class TestFastembedRanker:
                 "meta_fields_to_embed": ["test_field"],
                 "meta_data_separator": " | ",
                 "score_threshold": 0.5,
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
 
@@ -176,6 +192,7 @@ class TestFastembedRanker:
                 "meta_fields_to_embed": ["test_field"],
                 "meta_data_separator": " | ",
                 "score_threshold": 0.5,
+                "model_kwargs": {"providers": ["CUDAExecutionProvider"]},
             },
         }
         ranker = default_from_dict(FastembedRanker, ranker_dict)
@@ -189,6 +206,7 @@ class TestFastembedRanker:
         assert ranker.meta_fields_to_embed == ["test_field"]
         assert ranker.meta_data_separator == " | "
         assert ranker.score_threshold == 0.5
+        assert ranker.model_kwargs == {"providers": ["CUDAExecutionProvider"]}
 
     def test_run_incorrect_input_format(self):
         """
@@ -226,6 +244,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.
@@ -295,6 +319,24 @@ class TestFastembedRanker:
 
         mock_warm_up.assert_called_once()
 
+    @patch("haystack_integrations.components.rankers.fastembed.ranker.TextCrossEncoder")
+    def test_warm_up_forwards_model_kwargs(self, mocked_cross_encoder):
+        """
+        Test that model_kwargs (e.g. GPU providers) are forwarded to the underlying Fastembed model.
+        """
+        ranker = FastembedRanker(
+            model_name="BAAI/bge-reranker-base",
+            model_kwargs={"providers": ["CUDAExecutionProvider"]},
+        )
+        ranker.warm_up()
+        mocked_cross_encoder.assert_called_once_with(
+            model_name="BAAI/bge-reranker-base",
+            cache_dir=None,
+            threads=None,
+            local_files_only=False,
+            providers=["CUDAExecutionProvider"],
+        )
+
     @pytest.mark.integration
     def test_run(self):
         ranker = FastembedRanker(model_name="Xenova/ms-marco-MiniLM-L-6-v2", top_k=2)