sentence-transformers-haystack 0.1.0__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. sentence_transformers_haystack-0.1.2/CHANGELOG.md +20 -0
  2. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/PKG-INFO +4 -2
  3. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/README.md +2 -0
  4. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/pyproject.toml +1 -0
  5. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/embedding_backend/backend.py +12 -1
  6. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/sentence_transformers_document_embedder.py +21 -1
  7. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/sentence_transformers_text_embedder.py +20 -1
  8. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/rankers/sentence_transformers/sentence_transformers_similarity.py +5 -5
  9. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_hybrid_rag_e2e.py +11 -3
  10. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_diversity.py +4 -1
  11. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_doc_image_embedder.py +3 -1
  12. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_document_embedder.py +14 -0
  13. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_embedding_backend.py +33 -0
  14. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_similarity.py +34 -3
  15. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_text_embedder.py +51 -2
  16. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/.gitignore +0 -0
  17. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/LICENSE.txt +0 -0
  18. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/pydoc/config_docusaurus.yml +0 -0
  19. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/py.typed +0 -0
  20. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/__init__.py +0 -0
  21. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/embedding_backend/__init__.py +0 -0
  22. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/embedding_backend/sparse_backend.py +0 -0
  23. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/sentence_transformers_doc_image_embedder.py +0 -0
  24. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/sentence_transformers_sparse_document_embedder.py +0 -0
  25. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/embedders/sentence_transformers/sentence_transformers_sparse_text_embedder.py +0 -0
  26. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/rankers/py.typed +0 -0
  27. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/rankers/sentence_transformers/__init__.py +0 -0
  28. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/src/haystack_integrations/components/rankers/sentence_transformers/sentence_transformers_diversity.py +0 -0
  29. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/__init__.py +0 -0
  30. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/conftest.py +0 -0
  31. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_files/images/apple.jpg +0 -0
  32. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_files/images/haystack-logo.png +0 -0
  33. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_files/images/image_metadata.png +0 -0
  34. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_files/pdf/sample_pdf_1.pdf +0 -0
  35. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_sparse_document_embedder.py +0 -0
  36. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_sparse_embedding_backend.py +0 -0
  37. {sentence_transformers_haystack-0.1.0 → sentence_transformers_haystack-0.1.2}/tests/test_sentence_transformers_sparse_text_embedder.py +0 -0
@@ -0,0 +1,20 @@
1
+ # Changelog
2
+
3
+ ## [integrations/sentence_transformers-v0.1.1] - 2026-07-07
4
+
5
+ ### 🐛 Bug Fixes
6
+
7
+ - Support quantization ranges for int8/uint8 sentence-transformers… (#3543)
8
+
9
+ ### 🧪 Testing
10
+
11
+ - Force Transformers and Sentence Transformers integration tests to run on CPU (#3550)
12
+
13
+
14
+ ## [integrations/sentence_transformers-v0.1.0] - 2026-06-16
15
+
16
+ ### 🚀 Features
17
+
18
+ - Move Sentence Transformers from Haystack (#3443)
19
+
20
+ <!-- generated by git-cliff -->
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: sentence-transformers-haystack
3
- Version: 0.1.0
3
+ Version: 0.1.2
4
4
  Summary: Haystack integration for sentence_transformers
5
5
  Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/sentence_transformers#readme
6
6
  Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
@@ -39,3 +39,5 @@ Description-Content-Type: text/markdown
39
39
  ## Contributing
40
40
 
41
41
  Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
42
+
43
+ To run integration tests locally, you need to export the `OPENAI_API_KEY` environment variable.
@@ -11,3 +11,5 @@
11
11
  ## Contributing
12
12
 
13
13
  Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
14
+
15
+ To run integration tests locally, you need to export the `OPENAI_API_KEY` environment variable.
@@ -135,6 +135,7 @@ ignore = [
135
135
  "PLR0912",
136
136
  "PLR0913",
137
137
  "PLR0915",
138
+ "PLR0917",
138
139
  # Allow `Any` type - used legitimately for dynamic types and SDK boundaries
139
140
  "ANN401",
140
141
  ]
@@ -5,10 +5,11 @@
5
5
  import json
6
6
  from typing import Any, ClassVar, Literal
7
7
 
8
+ import numpy as np
8
9
  from haystack.utils.auth import Secret
9
10
  from PIL.Image import Image
10
11
 
11
- from sentence_transformers import SentenceTransformer
12
+ from sentence_transformers import SentenceTransformer, quantize_embeddings
12
13
 
13
14
 
14
15
  class _SentenceTransformersEmbeddingBackendFactory:
@@ -106,4 +107,14 @@ class _SentenceTransformersEmbeddingBackend:
106
107
  )
107
108
 
108
109
  def embed(self, data: list[str] | list[Image], **kwargs: Any) -> list[list[float]]:
110
+ quantization_ranges = kwargs.pop("quantization_ranges", None)
111
+ precision = kwargs.get("precision", "float32")
112
+ if quantization_ranges is not None and precision in ("int8", "uint8"):
113
+ kwargs["precision"] = "float32"
114
+ embeddings = self.model.encode(data, **kwargs)
115
+ quantized = quantize_embeddings(embeddings, precision=precision, ranges=np.asarray(quantization_ranges))
116
+ if isinstance(quantized, list):
117
+ msg = "Unexpected multi-vector output from quantize_embeddings"
118
+ raise TypeError(msg)
119
+ return quantized.tolist()
109
120
  return self.model.encode(data, **kwargs).tolist()
@@ -5,7 +5,7 @@
5
5
  from dataclasses import replace
6
6
  from typing import Any, Literal
7
7
 
8
- from haystack import Document, component, default_from_dict, default_to_dict
8
+ from haystack import Document, component, default_from_dict, default_to_dict, logging
9
9
  from haystack.utils import ComponentDevice, Secret
10
10
  from haystack.utils.hf import deserialize_hf_model_kwargs, serialize_hf_model_kwargs
11
11
 
@@ -14,6 +14,8 @@ from haystack_integrations.components.embedders.sentence_transformers.embedding_
14
14
  _SentenceTransformersEmbeddingBackendFactory,
15
15
  )
16
16
 
17
+ logger = logging.getLogger(__name__)
18
+
17
19
 
18
20
  @component
19
21
  class SentenceTransformersDocumentEmbedder:
@@ -63,6 +65,7 @@ class SentenceTransformersDocumentEmbedder:
63
65
  encode_kwargs: dict[str, Any] | None = None,
64
66
  backend: Literal["torch", "onnx", "openvino"] = "torch",
65
67
  revision: str | None = None,
68
+ quantization_ranges: list[list[float]] | None = None,
66
69
  ) -> None:
67
70
  """
68
71
  Creates a SentenceTransformersDocumentEmbedder component.
@@ -124,6 +127,13 @@ class SentenceTransformersDocumentEmbedder:
124
127
  :param revision:
125
128
  The specific model version to use. It can be a branch name, a tag name, or a commit id,
126
129
  for a stored model on Hugging Face.
130
+ :param quantization_ranges:
131
+ Calibration ranges to use when `precision` is "int8" or "uint8", with shape `(2, embedding_dim)`:
132
+ minimum values in the first row and maximum values in the second.
133
+ Scalar quantization calibrates the min/max range from the batch being encoded, which is degenerate
134
+ for small batches and inconsistent across batches. Pass ranges computed from a representative
135
+ sample of embeddings to get consistent quantized embeddings, compatible with query embeddings
136
+ quantized with the same ranges.
127
137
  """
128
138
 
129
139
  self.model = model
@@ -147,6 +157,14 @@ class SentenceTransformersDocumentEmbedder:
147
157
  self.embedding_backend: _SentenceTransformersEmbeddingBackend | None = None
148
158
  self.precision = precision
149
159
  self.backend = backend
160
+ self.quantization_ranges = quantization_ranges
161
+ if precision in ("int8", "uint8") and quantization_ranges is None:
162
+ logger.warning(
163
+ "Using precision '{precision}' without `quantization_ranges` calibrates the quantization range "
164
+ "from each batch itself, which is degenerate for small batches and inconsistent across batches. "
165
+ "Pass `quantization_ranges` computed from a representative sample of embeddings.",
166
+ precision=precision,
167
+ )
150
168
 
151
169
  def _get_telemetry_data(self) -> dict[str, Any]:
152
170
  """
@@ -183,6 +201,7 @@ class SentenceTransformersDocumentEmbedder:
183
201
  precision=self.precision,
184
202
  encode_kwargs=self.encode_kwargs,
185
203
  backend=self.backend,
204
+ quantization_ranges=self.quantization_ranges,
186
205
  )
187
206
  if serialization_dict["init_parameters"].get("model_kwargs") is not None:
188
207
  serialize_hf_model_kwargs(serialization_dict["init_parameters"]["model_kwargs"])
@@ -262,6 +281,7 @@ class SentenceTransformersDocumentEmbedder:
262
281
  show_progress_bar=self.progress_bar,
263
282
  normalize_embeddings=self.normalize_embeddings,
264
283
  precision=self.precision,
284
+ quantization_ranges=self.quantization_ranges,
265
285
  **(self.encode_kwargs if self.encode_kwargs else {}),
266
286
  )
267
287
 
@@ -4,7 +4,7 @@
4
4
 
5
5
  from typing import Any, Literal
6
6
 
7
- from haystack import component, default_from_dict, default_to_dict
7
+ from haystack import component, default_from_dict, default_to_dict, logging
8
8
  from haystack.utils import ComponentDevice, Secret
9
9
  from haystack.utils.hf import deserialize_hf_model_kwargs, serialize_hf_model_kwargs
10
10
 
@@ -13,6 +13,8 @@ from haystack_integrations.components.embedders.sentence_transformers.embedding_
13
13
  _SentenceTransformersEmbeddingBackendFactory,
14
14
  )
15
15
 
16
+ logger = logging.getLogger(__name__)
17
+
16
18
 
17
19
  @component
18
20
  class SentenceTransformersTextEmbedder:
@@ -57,6 +59,7 @@ class SentenceTransformersTextEmbedder:
57
59
  encode_kwargs: dict[str, Any] | None = None,
58
60
  backend: Literal["torch", "onnx", "openvino"] = "torch",
59
61
  revision: str | None = None,
62
+ quantization_ranges: list[list[float]] | None = None,
60
63
  ) -> None:
61
64
  """
62
65
  Create a SentenceTransformersTextEmbedder component.
@@ -114,6 +117,12 @@ class SentenceTransformersTextEmbedder:
114
117
  :param revision:
115
118
  The specific model version to use. It can be a branch name, a tag name, or a commit id,
116
119
  for a stored model on Hugging Face.
120
+ :param quantization_ranges:
121
+ Calibration ranges to use when `precision` is "int8" or "uint8", with shape `(2, embedding_dim)`:
122
+ minimum values in the first row and maximum values in the second.
123
+ Scalar quantization calibrates the min/max range from the batch being encoded, which is degenerate
124
+ for a single text and produces meaningless embeddings. Pass ranges computed from a representative
125
+ sample of embeddings to get consistent quantized embeddings.
117
126
  """
118
127
 
119
128
  self.model = model
@@ -135,6 +144,14 @@ class SentenceTransformersTextEmbedder:
135
144
  self.embedding_backend: _SentenceTransformersEmbeddingBackend | None = None
136
145
  self.precision = precision
137
146
  self.backend = backend
147
+ self.quantization_ranges = quantization_ranges
148
+ if precision in ("int8", "uint8") and quantization_ranges is None:
149
+ logger.warning(
150
+ "Using precision '{precision}' without `quantization_ranges` produces meaningless embeddings for "
151
+ "single texts, because the calibration range is computed from the batch itself. "
152
+ "Pass `quantization_ranges` computed from a representative sample of embeddings.",
153
+ precision=precision,
154
+ )
138
155
 
139
156
  def _get_telemetry_data(self) -> dict[str, Any]:
140
157
  """
@@ -169,6 +186,7 @@ class SentenceTransformersTextEmbedder:
169
186
  precision=self.precision,
170
187
  encode_kwargs=self.encode_kwargs,
171
188
  backend=self.backend,
189
+ quantization_ranges=self.quantization_ranges,
172
190
  )
173
191
  if serialization_dict["init_parameters"].get("model_kwargs") is not None:
174
192
  serialize_hf_model_kwargs(serialization_dict["init_parameters"]["model_kwargs"])
@@ -240,6 +258,7 @@ class SentenceTransformersTextEmbedder:
240
258
  show_progress_bar=self.progress_bar,
241
259
  normalize_embeddings=self.normalize_embeddings,
242
260
  precision=self.precision,
261
+ quantization_ranges=self.quantization_ranges,
243
262
  **(self.encode_kwargs if self.encode_kwargs else {}),
244
263
  )[0]
245
264
  return {"embedding": embedding}
@@ -250,14 +250,14 @@ class SentenceTransformersSimilarityRanker:
250
250
  if not documents:
251
251
  return {"documents": []}
252
252
 
253
- top_k = top_k or self.top_k
254
- scale_score = scale_score or self.scale_score
255
- score_threshold = score_threshold or self.score_threshold
256
-
257
- if top_k <= 0:
253
+ if top_k is not None and top_k <= 0:
258
254
  msg = f"top_k must be > 0, but got {top_k}"
259
255
  raise ValueError(msg)
260
256
 
257
+ top_k = self.top_k if top_k is None else top_k
258
+ scale_score = self.scale_score if scale_score is None else scale_score
259
+ score_threshold = self.score_threshold if score_threshold is None else score_threshold
260
+
261
261
  deduplicated_documents = _deduplicate_documents(documents)
262
262
  prepared_query = self.query_prefix + query + self.query_suffix
263
263
  prepared_documents = []
@@ -14,6 +14,7 @@ from haystack.components.retrievers.in_memory import InMemoryBM25Retriever, InMe
14
14
  from haystack.components.writers import DocumentWriter
15
15
  from haystack.dataclasses import ChatMessage
16
16
  from haystack.document_stores.in_memory import InMemoryDocumentStore
17
+ from haystack.utils import ComponentDevice
17
18
 
18
19
  from haystack_integrations.components.embedders.sentence_transformers import (
19
20
  SentenceTransformersDocumentEmbedder,
@@ -41,7 +42,8 @@ def test_hybrid_retrieval_rag_pipeline(tmp_path):
41
42
  ]
42
43
  indexing_pipeline = Pipeline()
43
44
  indexing_pipeline.add_component(
44
- instance=SentenceTransformersDocumentEmbedder(model=EMBEDDING_MODEL), name="document_embedder"
45
+ instance=SentenceTransformersDocumentEmbedder(model=EMBEDDING_MODEL, device=ComponentDevice.from_str("cpu")),
46
+ name="document_embedder",
45
47
  )
46
48
  indexing_pipeline.add_component(instance=DocumentWriter(document_store=document_store), name="document_writer")
47
49
  indexing_pipeline.connect("document_embedder", "document_writer")
@@ -60,13 +62,19 @@ def test_hybrid_retrieval_rag_pipeline(tmp_path):
60
62
 
61
63
  rag_pipeline = Pipeline()
62
64
  rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="bm25_retriever")
63
- rag_pipeline.add_component(instance=SentenceTransformersTextEmbedder(model=EMBEDDING_MODEL), name="text_embedder")
65
+ rag_pipeline.add_component(
66
+ instance=SentenceTransformersTextEmbedder(model=EMBEDDING_MODEL, device=ComponentDevice.from_str("cpu")),
67
+ name="text_embedder",
68
+ )
64
69
  rag_pipeline.add_component(
65
70
  instance=InMemoryEmbeddingRetriever(document_store=document_store), name="embedding_retriever"
66
71
  )
67
72
  rag_pipeline.add_component(instance=DocumentJoiner(), name="joiner")
68
73
  rag_pipeline.add_component(
69
- instance=SentenceTransformersSimilarityRanker(model=RANKER_MODEL, top_k=3), name="ranker"
74
+ instance=SentenceTransformersSimilarityRanker(
75
+ model=RANKER_MODEL, top_k=3, device=ComponentDevice.from_str("cpu")
76
+ ),
77
+ name="ranker",
70
78
  )
71
79
  rag_pipeline.add_component(
72
80
  instance=ChatPromptBuilder(template=prompt_template, required_variables="*"), name="prompt_builder"
@@ -598,7 +598,9 @@ class TestSentenceTransformersDiversityRanker:
598
598
  @pytest.mark.parametrize("similarity", ["dot_product", "cosine"])
599
599
  def test_run_real_world_use_case(self, similarity, del_hf_env_vars_if_empty):
600
600
  ranker = SentenceTransformersDiversityRanker(
601
- model="sentence-transformers-testing/stsb-bert-tiny-safetensors", similarity=similarity
601
+ model="sentence-transformers-testing/stsb-bert-tiny-safetensors",
602
+ similarity=similarity,
603
+ device=ComponentDevice.from_str("cpu"),
602
604
  )
603
605
  query = "What are the reasons for long-standing animosities between Russia and Poland?"
604
606
 
@@ -685,6 +687,7 @@ class TestSentenceTransformersDiversityRanker:
685
687
  model="sentence-transformers-testing/stsb-bert-tiny-safetensors",
686
688
  similarity=similarity,
687
689
  strategy="maximum_margin_relevance",
690
+ device=ComponentDevice.from_str("cpu"),
688
691
  )
689
692
 
690
693
  # lambda_threshold=1, the most relevant document should be returned first
@@ -321,7 +321,9 @@ class TestSentenceTransformersDocumentImageEmbedder:
321
321
  ),
322
322
  )
323
323
  def test_live_run(self, test_files_path, del_hf_env_vars_if_empty):
324
- embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
324
+ embedder = SentenceTransformersDocumentImageEmbedder(
325
+ model="sentence-transformers/clip-ViT-B-32", device=ComponentDevice.from_str("cpu")
326
+ )
325
327
 
326
328
  documents = [
327
329
  Document(
@@ -33,6 +33,7 @@ class TestSentenceTransformersDocumentEmbedder:
33
33
  assert embedder.local_files_only is False
34
34
  assert embedder.truncate_dim is None
35
35
  assert embedder.precision == "float32"
36
+ assert embedder.quantization_ranges is None
36
37
 
37
38
  def test_init_with_parameters(self):
38
39
  embedder = SentenceTransformersDocumentEmbedder(
@@ -51,6 +52,7 @@ class TestSentenceTransformersDocumentEmbedder:
51
52
  local_files_only=True,
52
53
  truncate_dim=256,
53
54
  precision="int8",
55
+ quantization_ranges=[[-1.0, -1.0], [1.0, 1.0]],
54
56
  )
55
57
  assert embedder.model == "model"
56
58
  assert embedder.device == ComponentDevice.from_str("cuda:0")
@@ -67,6 +69,12 @@ class TestSentenceTransformersDocumentEmbedder:
67
69
  assert embedder.local_files_only
68
70
  assert embedder.truncate_dim == 256
69
71
  assert embedder.precision == "int8"
72
+ assert embedder.quantization_ranges == [[-1.0, -1.0], [1.0, 1.0]]
73
+
74
+ def test_init_quantized_precision_without_ranges_warns(self, caplog):
75
+ with caplog.at_level("WARNING"):
76
+ SentenceTransformersDocumentEmbedder(model="model", precision="int8")
77
+ assert "quantization_ranges" in caplog.text
70
78
 
71
79
  def test_to_dict(self):
72
80
  component = SentenceTransformersDocumentEmbedder(model="model", device=ComponentDevice.from_str("cpu"))
@@ -94,6 +102,7 @@ class TestSentenceTransformersDocumentEmbedder:
94
102
  "config_kwargs": None,
95
103
  "precision": "float32",
96
104
  "backend": "torch",
105
+ "quantization_ranges": None,
97
106
  },
98
107
  }
99
108
 
@@ -143,6 +152,7 @@ class TestSentenceTransformersDocumentEmbedder:
143
152
  "precision": "int8",
144
153
  "encode_kwargs": {"task": "clustering"},
145
154
  "backend": "torch",
155
+ "quantization_ranges": None,
146
156
  },
147
157
  }
148
158
 
@@ -346,6 +356,7 @@ class TestSentenceTransformersDocumentEmbedder:
346
356
  show_progress_bar=True,
347
357
  normalize_embeddings=False,
348
358
  precision="float32",
359
+ quantization_ranges=None,
349
360
  )
350
361
 
351
362
  def test_embed_metadata_preserves_falsy_values(self):
@@ -366,6 +377,7 @@ class TestSentenceTransformersDocumentEmbedder:
366
377
  show_progress_bar=True,
367
378
  normalize_embeddings=False,
368
379
  precision="float32",
380
+ quantization_ranges=None,
369
381
  )
370
382
 
371
383
  def test_embed_encode_kwargs(self):
@@ -380,6 +392,7 @@ class TestSentenceTransformersDocumentEmbedder:
380
392
  show_progress_bar=True,
381
393
  normalize_embeddings=False,
382
394
  precision="float32",
395
+ quantization_ranges=None,
383
396
  task="retrieval.passage",
384
397
  )
385
398
 
@@ -407,6 +420,7 @@ class TestSentenceTransformersDocumentEmbedder:
407
420
  show_progress_bar=True,
408
421
  normalize_embeddings=False,
409
422
  precision="float32",
423
+ quantization_ranges=None,
410
424
  )
411
425
 
412
426
  @patch(
@@ -4,6 +4,7 @@
4
4
 
5
5
  from unittest.mock import patch
6
6
 
7
+ import numpy as np
7
8
  from haystack.utils.auth import Secret
8
9
 
9
10
  from haystack_integrations.components.embedders.sentence_transformers.embedding_backend.backend import (
@@ -65,3 +66,35 @@ def test_embedding_function_with_kwargs(mock_sentence_transformer):
65
66
  embedding_backend.embed(data=data, normalize_embeddings=True)
66
67
 
67
68
  embedding_backend.model.encode.assert_called_once_with(data, normalize_embeddings=True)
69
+
70
+
71
+ @patch("haystack_integrations.components.embedders.sentence_transformers.embedding_backend.backend.quantize_embeddings")
72
+ @patch("haystack_integrations.components.embedders.sentence_transformers.embedding_backend.backend.SentenceTransformer")
73
+ def test_embedding_function_with_quantization_ranges(mock_sentence_transformer, mock_quantize_embeddings):
74
+ embedding_backend = _SentenceTransformersEmbeddingBackendFactory.get_embedding_backend(model="quantized_model")
75
+ embedding_backend.model.encode.return_value = np.array([[0.1, 0.2]])
76
+ mock_quantize_embeddings.return_value = np.array([[12, 34]], dtype=np.int8)
77
+
78
+ data = ["sentence"]
79
+ ranges = [[-1.0, -1.0], [1.0, 1.0]]
80
+ result = embedding_backend.embed(data=data, precision="int8", quantization_ranges=ranges)
81
+
82
+ embedding_backend.model.encode.assert_called_once_with(data, precision="float32")
83
+ assert mock_quantize_embeddings.call_count == 1
84
+ _, called_kwargs = mock_quantize_embeddings.call_args
85
+ assert called_kwargs["precision"] == "int8"
86
+ assert np.array_equal(called_kwargs["ranges"], np.asarray(ranges))
87
+ assert result == [[12, 34]]
88
+
89
+
90
+ @patch("haystack_integrations.components.embedders.sentence_transformers.embedding_backend.backend.quantize_embeddings")
91
+ @patch("haystack_integrations.components.embedders.sentence_transformers.embedding_backend.backend.SentenceTransformer")
92
+ def test_embedding_function_without_quantization_ranges(mock_sentence_transformer, mock_quantize_embeddings):
93
+ embedding_backend = _SentenceTransformersEmbeddingBackendFactory.get_embedding_backend(model="another_quantized")
94
+ embedding_backend.model.encode.return_value = np.array([[1, 2]], dtype=np.int8)
95
+
96
+ data = ["sentence"]
97
+ embedding_backend.embed(data=data, precision="int8", quantization_ranges=None)
98
+
99
+ embedding_backend.model.encode.assert_called_once_with(data, precision="int8")
100
+ mock_quantize_embeddings.assert_not_called()
@@ -281,6 +281,35 @@ class TestSentenceTransformersSimilarityRanker:
281
281
  with pytest.raises(ValueError):
282
282
  ranker.run(query="test", documents=[Document(content="document")], top_k=-1)
283
283
 
284
+ def test_run_top_k_zero_raises(self):
285
+ ranker = SentenceTransformersSimilarityRanker()
286
+ ranker._cross_encoder = MagicMock()
287
+
288
+ with pytest.raises(ValueError, match="top_k must be > 0, but got 0"):
289
+ ranker.run(query="test", documents=[Document(content="document")], top_k=0)
290
+
291
+ def test_run_scale_score_false_overrides_init(self):
292
+ ranker = SentenceTransformersSimilarityRanker() # scale_score=True by default
293
+ mock_cross_encoder = MagicMock()
294
+ mock_cross_encoder.rank.return_value = [{"corpus_id": 0, "score": 1.0}]
295
+ ranker._cross_encoder = mock_cross_encoder
296
+
297
+ ranker.run(query="test", documents=[Document(content="document")], scale_score=False)
298
+
299
+ _, kwargs = mock_cross_encoder.rank.call_args
300
+ assert isinstance(kwargs["activation_fn"], torch.nn.Identity)
301
+
302
+ def test_run_score_threshold_zero_overrides_init(self):
303
+ ranker = SentenceTransformersSimilarityRanker(score_threshold=0.5)
304
+ mock_cross_encoder = MagicMock()
305
+ mock_cross_encoder.rank.return_value = [{"corpus_id": 0, "score": 0.2}, {"corpus_id": 1, "score": -0.4}]
306
+ ranker._cross_encoder = mock_cross_encoder
307
+
308
+ documents = [Document(content="first"), Document(content="second")]
309
+ result = ranker.run(query="test", documents=documents, score_threshold=0.0)
310
+
311
+ assert [doc.score for doc in result["documents"]] == [0.2]
312
+
284
313
  def test_returns_empty_list_if_no_documents_are_provided(self):
285
314
  ranker = SentenceTransformersSimilarityRanker()
286
315
  ranker._cross_encoder = MagicMock()
@@ -439,7 +468,9 @@ class TestSentenceTransformersSimilarityRanker:
439
468
 
440
469
  @pytest.mark.integration
441
470
  def test_run(self, del_hf_env_vars_if_empty):
442
- ranker = SentenceTransformersSimilarityRanker(model="cross-encoder-testing/reranker-bert-tiny-gooaq-bce")
471
+ ranker = SentenceTransformersSimilarityRanker(
472
+ model="cross-encoder-testing/reranker-bert-tiny-gooaq-bce", device=ComponentDevice.from_str("cpu")
473
+ )
443
474
 
444
475
  query = "City in Bosnia and Herzegovina"
445
476
  docs_before_texts = ["Berlin", "Belgrade", "Sarajevo"]
@@ -464,7 +495,7 @@ class TestSentenceTransformersSimilarityRanker:
464
495
  @pytest.mark.integration
465
496
  def test_run_top_k(self, del_hf_env_vars_if_empty):
466
497
  ranker = SentenceTransformersSimilarityRanker(
467
- model="cross-encoder-testing/reranker-bert-tiny-gooaq-bce", top_k=2
498
+ model="cross-encoder-testing/reranker-bert-tiny-gooaq-bce", top_k=2, device=ComponentDevice.from_str("cpu")
468
499
  )
469
500
 
470
501
  query = "City in Bosnia and Herzegovina"
@@ -487,7 +518,7 @@ class TestSentenceTransformersSimilarityRanker:
487
518
  @pytest.mark.integration
488
519
  def test_run_single_document(self, del_hf_env_vars_if_empty):
489
520
  ranker = SentenceTransformersSimilarityRanker(
490
- model="cross-encoder-testing/reranker-bert-tiny-gooaq-bce", device=None
521
+ model="cross-encoder-testing/reranker-bert-tiny-gooaq-bce", device=ComponentDevice.from_str("cpu")
491
522
  )
492
523
  docs_before = [Document(content="Berlin")]
493
524
  output = ranker.run(query="City in Germany", documents=docs_before)
@@ -30,6 +30,7 @@ class TestSentenceTransformersTextEmbedder:
30
30
  assert embedder.local_files_only is False
31
31
  assert embedder.truncate_dim is None
32
32
  assert embedder.precision == "float32"
33
+ assert embedder.quantization_ranges is None
33
34
 
34
35
  def test_init_with_parameters(self):
35
36
  embedder = SentenceTransformersTextEmbedder(
@@ -46,6 +47,7 @@ class TestSentenceTransformersTextEmbedder:
46
47
  local_files_only=True,
47
48
  truncate_dim=256,
48
49
  precision="int8",
50
+ quantization_ranges=[[-1.0, -1.0], [1.0, 1.0]],
49
51
  )
50
52
  assert embedder.model == "model"
51
53
  assert embedder.device == ComponentDevice.from_str("cuda:0")
@@ -60,6 +62,12 @@ class TestSentenceTransformersTextEmbedder:
60
62
  assert embedder.local_files_only is True
61
63
  assert embedder.truncate_dim == 256
62
64
  assert embedder.precision == "int8"
65
+ assert embedder.quantization_ranges == [[-1.0, -1.0], [1.0, 1.0]]
66
+
67
+ def test_init_quantized_precision_without_ranges_warns(self, caplog):
68
+ with caplog.at_level("WARNING"):
69
+ SentenceTransformersTextEmbedder(model="model", precision="int8")
70
+ assert "quantization_ranges" in caplog.text
63
71
 
64
72
  def test_to_dict(self):
65
73
  component = SentenceTransformersTextEmbedder(model="model", device=ComponentDevice.from_str("cpu"))
@@ -85,6 +93,7 @@ class TestSentenceTransformersTextEmbedder:
85
93
  "config_kwargs": None,
86
94
  "precision": "float32",
87
95
  "backend": "torch",
96
+ "quantization_ranges": None,
88
97
  },
89
98
  }
90
99
 
@@ -129,6 +138,7 @@ class TestSentenceTransformersTextEmbedder:
129
138
  "precision": "int8",
130
139
  "encode_kwargs": {"task": "clustering"},
131
140
  "backend": "torch",
141
+ "quantization_ranges": None,
132
142
  },
133
143
  }
134
144
 
@@ -300,9 +310,25 @@ class TestSentenceTransformersTextEmbedder:
300
310
  show_progress_bar=True,
301
311
  normalize_embeddings=False,
302
312
  precision="float32",
313
+ quantization_ranges=None,
303
314
  task="retrieval.query",
304
315
  )
305
316
 
317
+ def test_run_with_quantization_ranges(self):
318
+ ranges = [[-1.0, -1.0], [1.0, 1.0]]
319
+ embedder = SentenceTransformersTextEmbedder(model="model", precision="int8", quantization_ranges=ranges)
320
+ embedder.embedding_backend = MagicMock()
321
+ text = "a nice text to embed"
322
+ embedder.run(text=text)
323
+ embedder.embedding_backend.embed.assert_called_once_with(
324
+ [text],
325
+ batch_size=32,
326
+ show_progress_bar=True,
327
+ normalize_embeddings=False,
328
+ precision="int8",
329
+ quantization_ranges=ranges,
330
+ )
331
+
306
332
  @patch(
307
333
  "haystack_integrations.components.embedders.sentence_transformers.sentence_transformers_text_embedder._SentenceTransformersEmbeddingBackendFactory"
308
334
  )
@@ -397,7 +423,9 @@ class TestSentenceTransformersTextEmbedder:
397
423
  checkpoint = "sentence-transformers-testing/stsb-bert-tiny-safetensors"
398
424
  text = "a nice text to embed"
399
425
 
400
- embedder_trunc = SentenceTransformersTextEmbedder(model=checkpoint, truncate_dim=64)
426
+ embedder_trunc = SentenceTransformersTextEmbedder(
427
+ model=checkpoint, truncate_dim=64, device=ComponentDevice.from_str("cpu")
428
+ )
401
429
  result_trunc = embedder_trunc.run(text=text)
402
430
  embedding_trunc = result_trunc["embedding"]
403
431
 
@@ -413,9 +441,30 @@ class TestSentenceTransformersTextEmbedder:
413
441
  checkpoint = "sentence-transformers-testing/stsb-bert-tiny-safetensors"
414
442
  text = "a nice text to embed"
415
443
 
416
- embedder_def = SentenceTransformersTextEmbedder(model=checkpoint, precision="int8")
444
+ embedder_def = SentenceTransformersTextEmbedder(
445
+ model=checkpoint, precision="int8", device=ComponentDevice.from_str("cpu")
446
+ )
417
447
  result_def = embedder_def.run(text=text)
418
448
  embedding_def = result_def["embedding"]
419
449
 
420
450
  assert len(embedding_def) == 128
421
451
  assert all(isinstance(el, int) for el in embedding_def)
452
+
453
+ @pytest.mark.integration
454
+ def test_run_quantization_with_ranges(self, del_hf_env_vars_if_empty):
455
+ """
456
+ sentence-transformers-testing/stsb-bert-tiny-safetensors maps sentences & paragraphs to a 128 dimensional dense
457
+ vector space
458
+ """
459
+ checkpoint = "sentence-transformers-testing/stsb-bert-tiny-safetensors"
460
+ text = "a nice text to embed"
461
+ ranges = [[-1.0] * 128, [1.0] * 128]
462
+
463
+ embedder = SentenceTransformersTextEmbedder(model=checkpoint, precision="int8", quantization_ranges=ranges)
464
+ result = embedder.run(text=text)
465
+ embedding = result["embedding"]
466
+
467
+ assert len(embedding) == 128
468
+ assert all(isinstance(el, int) for el in embedding)
469
+ # without explicit ranges, a single text produces a degenerate all-equal embedding
470
+ assert len(set(embedding)) > 1