huggingface-api-haystack 1.0.0__tar.gz → 2.0.0__tar.gz

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [integrations/huggingface_api-v1.0.0] - 2026-09-07
+
+### 🚀 Features
+
+- [**breaking**] HF API - add lifecycle handling (#3917)
+
+### 🧪 Testing
+
+- Replace retired Qwen2.5 models in `huggingface_api` live tests (#3866)
+
+### ⚙️ CI
+
+- Improve changelog generation; fix existing changelogs (#3883)
+
+
 ## [integrations/huggingface_api-v0.6.0] - 2026-08-27
 
 ### 🚀 Features

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: huggingface-api-haystack
-Version: 1.0.0
+Version: 2.0.0
 Summary: Haystack integration for Hugging Face API
 Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api#readme
 Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
@@ -22,6 +22,8 @@ Requires-Python: >=3.10
 Requires-Dist: haystack-ai>=3.0.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: huggingface-hub[inference]>=1.0.0
+Provides-Extra: grpc
+Requires-Dist: grpc-requests>=0.1.21; extra == 'grpc'
 Description-Content-Type: text/markdown
 
 # huggingface-api-haystack
@@ -38,7 +40,6 @@ Description-Content-Type: text/markdown
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
 
-To run integration tests locally, you need a Docker container running a Text Embeddings Inference (TEI) server with
-a sparse embedding model. Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.
+To run integration tests locally, you need Docker containers running a few Text Embeddings Inference (TEI) servers. Use the provided `docker-compose.yml` file to start the containers: `docker compose up -d`.
 
 The tests that call the Hugging Face Inference API are skipped unless `HF_TOKEN` is set as an evironment variable.

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/README.md

@@ -12,7 +12,6 @@
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
 
-To run integration tests locally, you need a Docker container running a Text Embeddings Inference (TEI) server with
-a sparse embedding model. Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.
+To run integration tests locally, you need Docker containers running a few Text Embeddings Inference (TEI) servers. Use the provided `docker-compose.yml` file to start the containers: `docker compose up -d`.
 
 The tests that call the Hugging Face Inference API are skipped unless `HF_TOKEN` is set as an evironment variable.

huggingface_api_haystack-2.0.0/docker-compose.yml

@@ -0,0 +1,50 @@
+services:
+  tei-sparse:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3
+    command: ["--model-id", "opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini", "--pooling", "splade"]
+    ports:
+      - "8080:80"
+    environment:
+      - HF_TOKEN
+    volumes:
+      - tei-data:/data
+  tei-grpc:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3-grpc
+    command: ["--model-id", "sentence-transformers/all-MiniLM-L6-v2"]
+    ports:
+      - "8081:80"
+    environment:
+      - HF_TOKEN
+    volumes:
+      - tei-data:/data
+  tei-sparse-grpc:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3-grpc
+    command: ["--model-id", "opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini", "--pooling", "splade"]
+    ports:
+      - "8082:80"
+    environment:
+      - HF_TOKEN
+    volumes:
+      - tei-data:/data
+
+  tei-ranker:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3
+    command: ["--model-id", "cross-encoder/ms-marco-TinyBERT-L2-v2", "--api-key", "tei-test-key"]
+    ports:
+      - "8083:80"
+    environment:
+      - HF_TOKEN
+    volumes:
+      - tei-data:/data
+  tei-ranker-grpc:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9.3-grpc
+    command: ["--model-id", "cross-encoder/ms-marco-TinyBERT-L2-v2", "--api-key", "tei-test-key"]
+    ports:
+      - "8084:80"
+    environment:
+      - HF_TOKEN
+    volumes:
+      - tei-data:/data
+
+volumes:
+  tei-data:

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/pyproject.toml

@@ -25,6 +25,11 @@ classifiers = [
 ]
 dependencies = ["haystack-ai>=3.0.0", "httpx>=0.27.0", "huggingface_hub[inference]>=1.0.0"]
 
+[project.optional-dependencies]
+grpc = [
+  "grpc-requests>=0.1.21",
+]
+
 [project.urls]
 Documentation = "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api#readme"
 Issues = "https://github.com/deepset-ai/haystack-core-integrations/issues"
@@ -58,6 +63,7 @@ dependencies = [
     "pytest-rerunfailures",
     "mypy",
     "pip",
+    "grpc-requests>=0.1.21",
     "numpy",
     "pillow",  # image resizing in multimodal tests
 ]
@@ -79,6 +85,10 @@ non_interactive = true
 check_untyped_defs = true
 disallow_incomplete_defs = true
 
+[[tool.mypy.overrides]]
+module = ["grpc_requests", "grpc_requests.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 line-length = 120
 

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/src/haystack_integrations/common/huggingface_api/utils.py

@@ -4,6 +4,7 @@
 
 from enum import Enum
 
+from haystack.dataclasses import SparseEmbedding
 from haystack.utils import Secret
 from huggingface_hub import HfApi
 from huggingface_hub.errors import RepositoryNotFoundError
@@ -143,3 +144,27 @@ def _validate_model_type(model_id: str, model_type: HFModelType, pipeline_tag: s
 
     if not allowed_model:
         raise ValueError(error_msg)
+
+
+def _parse_grpc_sparse_embedding(items: list[dict[str, int | float]]) -> SparseEmbedding:
+    """Convert sparse gRPC values, restoring defaults omitted by protobuf."""
+    return SparseEmbedding(
+        indices=[int(item.get("index", 0)) for item in items],
+        values=[float(item.get("value", 0.0)) for item in items],
+    )
+
+
+def _build_grpc_embedding_request(text: str, truncate: bool | None, normalize: bool | None) -> dict[str, str | bool]:
+    """Build a gRPC embedding request."""
+    request: dict[str, str | bool] = {"inputs": text}
+    if truncate is not None:
+        request["truncate"] = truncate
+    if normalize is not None:
+        request["normalize"] = normalize
+    return request
+
+
+def _grpc_metadata(token: Secret | None) -> tuple[tuple[str, str], ...]:
+    """Build gRPC authorization metadata."""
+    value = token.resolve_value() if token else None
+    return (("authorization", f"Bearer {value}"),) if value else ()

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/src/haystack_integrations/components/embedders/huggingface_api/__init__.py

@@ -2,13 +2,13 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 from .document_embedder import HuggingFaceAPIDocumentEmbedder
-from .sparse_document_embedder import HuggingFaceAPISparseDocumentEmbedder
-from .sparse_text_embedder import HuggingFaceAPISparseTextEmbedder
+from .sparse_document_embedder import HuggingFaceTEISparseDocumentEmbedder
+from .sparse_text_embedder import HuggingFaceTEISparseTextEmbedder
 from .text_embedder import HuggingFaceAPITextEmbedder
 
 __all__ = [
     "HuggingFaceAPIDocumentEmbedder",
-    "HuggingFaceAPISparseDocumentEmbedder",
-    "HuggingFaceAPISparseTextEmbedder",
     "HuggingFaceAPITextEmbedder",
+    "HuggingFaceTEISparseDocumentEmbedder",
+    "HuggingFaceTEISparseTextEmbedder",
 ]

{huggingface_api_haystack-1.0.0 → huggingface_api_haystack-2.0.0}/src/haystack_integrations/components/embedders/huggingface_api/document_embedder.py

@@ -3,12 +3,14 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from asyncio import Semaphore, gather
+from collections.abc import AsyncIterator
 from dataclasses import replace
 from itertools import chain
 from typing import Any
 
 from haystack import component, default_from_dict, default_to_dict, logging
 from haystack.dataclasses import Document
+from haystack.lazy_imports import LazyImport
 from haystack.utils import Secret
 from haystack.utils.url_validation import is_valid_http_url
 from huggingface_hub import AsyncInferenceClient, InferenceClient
@@ -17,10 +19,17 @@ from tqdm import tqdm
 from haystack_integrations.common.huggingface_api.utils import (
     HFEmbeddingAPIType,
     HFModelType,
+    _build_grpc_embedding_request,
     _check_valid_model,
     _check_valid_model_async,
+    _grpc_metadata,
 )
 
+with LazyImport("Run 'pip install \"huggingface-api-haystack[grpc]\"' for grpc support.") as grpc_import:
+    from grpc_requests import Client
+    from grpc_requests.aio import AsyncClient
+
+
 logger = logging.getLogger(__name__)
 
 # batched embeddings returned by the API are expected to have shape (batch_size, embedding_dim)
@@ -110,6 +119,7 @@ class HuggingFaceAPIDocumentEmbedder:
         meta_fields_to_embed: list[str] | None = None,
         embedding_separator: str = "\n",
         concurrency_limit: int = 4,
+        use_grpc: bool = False,
     ) -> None:
         """
         Creates a HuggingFaceAPIDocumentEmbedder component.
@@ -119,9 +129,9 @@ class HuggingFaceAPIDocumentEmbedder:
         :param api_params:
             A dictionary with the following keys:
             - `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.
-            - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or
-            `TEXT_EMBEDDINGS_INFERENCE`.
-        :param token: The Hugging Face token to use as HTTP bearer authorization.
+            - `url`: URL of the inference endpoint, or gRPC target. Required when `api_type` is
+            `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.
+        :param token: The Hugging Face token to use as bearer authorization.
             Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
         :param prefix:
             A string to add at the beginning of each text.
@@ -138,7 +148,7 @@ class HuggingFaceAPIDocumentEmbedder:
             if the backend uses Text Embeddings Inference.
             If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
         :param batch_size:
-            Number of documents to process at once.
+            Number of documents to process at once. Only used with HTTP.
         :param progress_bar:
             If `True`, shows a progress bar when running.
         :param meta_fields_to_embed:
@@ -146,15 +156,21 @@ class HuggingFaceAPIDocumentEmbedder:
         :param embedding_separator:
             Separator used to concatenate the metadata fields to the document text.
         :param concurrency_limit:
-            The maximum number of requests that should be allowed to run concurrently.
+            The maximum number of HTTP requests or gRPC streams that should be allowed to run concurrently.
             This parameter is only used in the `run_async` method.
+        :param use_grpc:
+            Use gRPC instead of HTTP. Requires `huggingface-api-haystack[grpc]`.
         :raises ValueError:
-            If the required `model` or `url` is missing from `api_params`, the `url` is invalid,
-            or the `api_type` is unknown.
+            If the required `model` or `url` is missing from `api_params`, the HTTP `url` is invalid,
+            or the `api_type` is unknown or is `SERVERLESS_INFERENCE_API` with `use_grpc=True`.
         """
         if isinstance(api_type, str):
             api_type = HFEmbeddingAPIType.from_str(api_type)
 
+        if use_grpc and api_type == HFEmbeddingAPIType.SERVERLESS_INFERENCE_API:
+            msg = "gRPC is not supported by the Serverless Inference API."
+            raise ValueError(msg)
+
         api_params = api_params or {}
 
         if api_type == HFEmbeddingAPIType.SERVERLESS_INFERENCE_API:
@@ -171,7 +187,7 @@ class HuggingFaceAPIDocumentEmbedder:
                     "parameter in `api_params`."
                 )
                 raise ValueError(msg)
-            if not is_valid_http_url(url):
+            if not use_grpc and not is_valid_http_url(url):
                 msg = f"Invalid URL: {url}"
                 raise ValueError(msg)
             model_or_url = url
@@ -179,6 +195,9 @@ class HuggingFaceAPIDocumentEmbedder:
             msg = f"Unknown api_type {api_type}"
             raise ValueError(msg)
 
+        if use_grpc:
+            grpc_import.check()
+
         self.api_type = api_type
         self.api_params = api_params
         self.token = token
@@ -186,6 +205,7 @@ class HuggingFaceAPIDocumentEmbedder:
         self.suffix = suffix
         self.truncate = truncate
         self.normalize = normalize
+        self.use_grpc = use_grpc
         self.batch_size = batch_size
         self.progress_bar = progress_bar
         self.meta_fields_to_embed = meta_fields_to_embed or []
@@ -194,36 +214,54 @@ class HuggingFaceAPIDocumentEmbedder:
         self._model_or_url = model_or_url
         self._client: InferenceClient | None = None
         self._async_client: AsyncInferenceClient | None = None
+        self._grpc_client: Client | None = None
+        self._async_grpc_client: AsyncClient | None = None
 
     def _client_kwargs(self) -> dict[str, Any]:
         """Build the keyword arguments used to create Hugging Face clients."""
         return {"model": self._model_or_url, "token": self.token.resolve_value() if self.token else None}
 
     def warm_up(self) -> None:
-        """Create the synchronous Hugging Face client."""
+        """Create the synchronous client."""
+        if self.use_grpc:
+            if self._grpc_client is None:
+                self._grpc_client = Client(self._model_or_url)
+            return
+
         if self._client is None:
             if self.api_type == HFEmbeddingAPIType.SERVERLESS_INFERENCE_API:
                 _check_valid_model(self._model_or_url, HFModelType.EMBEDDING, self.token)
             self._client = InferenceClient(**self._client_kwargs())
 
     async def warm_up_async(self) -> None:
-        """Create the asynchronous Hugging Face client."""
+        """Create the asynchronous client."""
+        if self.use_grpc:
+            if self._async_grpc_client is None:
+                self._async_grpc_client = await AsyncClient.create(self._model_or_url)
+            return
+
         if self._async_client is None:
             if self.api_type == HFEmbeddingAPIType.SERVERLESS_INFERENCE_API:
                 await _check_valid_model_async(self._model_or_url, HFModelType.EMBEDDING, self.token)
             self._async_client = AsyncInferenceClient(**self._client_kwargs())
 
     def close(self) -> None:
-        """Close the synchronous Hugging Face client."""
+        """Close the synchronous client."""
         if self._client is not None:
             self._client.close()
             self._client = None
+        if self._grpc_client is not None:
+            self._grpc_client.channel.close()
+            self._grpc_client = None
 
     async def close_async(self) -> None:
-        """Close the asynchronous Hugging Face client."""
+        """Close the asynchronous client."""
         if self._async_client is not None:
             await self._async_client.close()
             self._async_client = None
+        if self._async_grpc_client is not None:
+            await self._async_grpc_client.channel.close()
+            self._async_grpc_client = None
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -241,6 +279,7 @@ class HuggingFaceAPIDocumentEmbedder:
             token=self.token,
             truncate=self.truncate,
             normalize=self.normalize,
+            use_grpc=self.use_grpc,
             batch_size=self.batch_size,
             progress_bar=self.progress_bar,
             meta_fields_to_embed=self.meta_fields_to_embed,
@@ -295,6 +334,32 @@ class HuggingFaceAPIDocumentEmbedder:
                 normalize = None
         return truncate, normalize
 
+    def _embed_batch_grpc(self, texts_to_embed: list[str]) -> list[list[float]]:
+        """Embed all texts through a single gRPC stream."""
+        if not texts_to_embed:
+            return []
+
+        assert self._grpc_client is not None  # noqa: S101
+        responses = self._grpc_client.stream_stream(
+            "tei.v1.Embed",
+            "EmbedStream",
+            (_build_grpc_embedding_request(text, self.truncate, self.normalize) for text in texts_to_embed),
+            metadata=_grpc_metadata(self.token),
+        )
+        embeddings = [
+            response["embeddings"]
+            for response in tqdm(
+                responses,
+                total=len(texts_to_embed),
+                disable=not self.progress_bar,
+                desc="Calculating embeddings",
+            )
+        ]
+        if len(embeddings) != len(texts_to_embed):
+            msg = f"Expected {len(texts_to_embed)} embeddings, got {len(embeddings)}"
+            raise ValueError(msg)
+        return embeddings
+
     def _embed_batch(self, texts_to_embed: list[str], batch_size: int) -> list[list[float]]:
         """
         Embed a list of texts in batches.
@@ -323,6 +388,41 @@ class HuggingFaceAPIDocumentEmbedder:
 
         return all_embeddings
 
+    async def _embed_batch_grpc_async(self, texts_to_embed: list[str]) -> list[list[float]]:
+        """Embed texts through concurrent gRPC streams."""
+        if not texts_to_embed:
+            return []
+
+        # Split texts evenly into ordered streams, up to the concurrency limit.
+        stream_count = min(max(1, self.concurrency_limit), len(texts_to_embed))
+        streams = [
+            texts_to_embed[len(texts_to_embed) * i // stream_count : len(texts_to_embed) * (i + 1) // stream_count]
+            for i in range(stream_count)
+        ]
+
+        pbar = tqdm(total=stream_count, disable=not self.progress_bar, desc="Calculating embeddings")
+
+        async def _runner(texts: list[str]) -> list[list[float]]:
+            async def _requests() -> AsyncIterator[dict[str, Any]]:
+                for text in texts:
+                    yield _build_grpc_embedding_request(text, self.truncate, self.normalize)
+
+            assert self._async_grpc_client is not None  # noqa: S101
+            responses = await self._async_grpc_client.stream_stream(
+                "tei.v1.Embed", "EmbedStream", _requests(), metadata=_grpc_metadata(self.token)
+            )
+            embeddings = [response["embeddings"] async for response in responses]
+            if len(embeddings) != len(texts):
+                msg = f"Expected {len(texts)} embeddings, got {len(embeddings)}"
+                raise ValueError(msg)
+            pbar.update(1)
+            return embeddings
+
+        try:
+            return [*chain(*await gather(*(_runner(texts) for texts in streams)))]
+        finally:
+            pbar.close()
+
     async def _embed_batch_async(self, texts_to_embed: list[str], batch_size: int) -> list[list[float]]:
         """
         Embed a list of texts in batches asynchronously.
@@ -383,7 +483,6 @@ class HuggingFaceAPIDocumentEmbedder:
             - `documents`: A list of documents with embeddings.
         """
         self.warm_up()
-        assert self._client is not None  # noqa: S101
 
         if not isinstance(documents, list) or (documents and not isinstance(documents[0], Document)):
             msg = (
@@ -394,7 +493,10 @@ class HuggingFaceAPIDocumentEmbedder:
 
         texts_to_embed = self._prepare_texts_to_embed(documents=documents)
 
-        embeddings = self._embed_batch(texts_to_embed=texts_to_embed, batch_size=self.batch_size)
+        if self.use_grpc:
+            embeddings = self._embed_batch_grpc(texts_to_embed)
+        else:
+            embeddings = self._embed_batch(texts_to_embed=texts_to_embed, batch_size=self.batch_size)
 
         new_documents = []
         for doc, emb in zip(documents, embeddings, strict=True):
@@ -419,7 +521,6 @@ class HuggingFaceAPIDocumentEmbedder:
             - `documents`: A list of documents with embeddings.
         """
         await self.warm_up_async()
-        assert self._async_client is not None  # noqa: S101
 
         if not isinstance(documents, list) or (documents and not isinstance(documents[0], Document)):
             msg = (
@@ -430,7 +531,10 @@ class HuggingFaceAPIDocumentEmbedder:
 
         texts_to_embed = self._prepare_texts_to_embed(documents=documents)
 
-        embeddings = await self._embed_batch_async(texts_to_embed=texts_to_embed, batch_size=self.batch_size)
+        if self.use_grpc:
+            embeddings = await self._embed_batch_grpc_async(texts_to_embed)
+        else:
+            embeddings = await self._embed_batch_async(texts_to_embed=texts_to_embed, batch_size=self.batch_size)
 
         new_documents = []
         for doc, emb in zip(documents, embeddings, strict=True):