HuggingFaceTEISparseDocumentEmbedder

Compute sparse document embeddings using a self-hosted Hugging Face Text Embeddings Inference (TEI) server. Use this component in indexing pipelines to produce sparse vectors for keyword-style retrieval with learned sparse models. This component was previously called HuggingFaceAPISparseDocumentEmbedder.

Key Features

• Connects to a self-hosted Hugging Face TEI server running a sparse embedding model. HTTP calls the /embed_sparse endpoint. Set use_grpc to connect over gRPC instead.
• Produces SparseEmbedding objects stored in each document's sparse_embedding field, enabling sparse retrieval.
• Configurable batch size and concurrent requests for high-throughput indexing.
• Supports metadata embedding alongside document content for richer representations.
• Supports both synchronous and asynchronous operation via run() and run_async().
• No external API key is required—authentication is optional and uses a Hugging Face token if the TEI server requires it.

Configuration

1. Drag the HuggingFaceTEISparseDocumentEmbedder component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Set the api_base_url field to the base URL of your TEI server, for example http://localhost:8080.
   2. Optionally, create a secret with your Hugging Face token and use HF_API_TOKEN as the secret key if the TEI server requires authentication.
4. Go to the Advanced tab to configure batch_size, concurrency_limit, meta_fields_to_embed, timeout, and use_grpc.

Connections

HuggingFaceTEISparseDocumentEmbedder receives a list of documents through its documents input. It outputs the same documents with their sparse_embedding field populated through its documents output.

Connect it after converters (such as TextFileToDocument or HTMLToDocument) or after DocumentSplitter to embed chunks. Connect its documents output to DocumentWriter to store the sparse-embedded documents in a document store that supports sparse retrieval.

Source Code

To check this component's source code, open sparse_document_embedder.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  HuggingFaceTEISparseDocumentEmbedder:
    type: haystack_integrations.components.embedders.huggingface_api.sparse_document_embedder.HuggingFaceTEISparseDocumentEmbedder
    init_parameters:
      api_base_url: http://localhost:8080
      token:
        type: env_var
        env_vars:
        - HF_API_TOKEN
        - HF_TOKEN
        strict: false
      batch_size: 32
      progress_bar: true
      concurrency_limit: 4
      timeout: 30.0
      embedding_separator: "\n"

Using the Component in a Pipeline

This example shows an indexing pipeline that reads text files, splits them into chunks, produces sparse embeddings using a TEI server, and writes the documents to a document store.

# haystack-pipeline
components:
  TextFileToDocument:
    type: haystack.components.converters.txt.TextFileToDocument
    init_parameters:
      encoding: utf-8
      store_full_path: false
  DocumentSplitter:
    type: haystack.components.preprocessors.document_splitter.DocumentSplitter
    init_parameters:
      split_by: sentence
      split_length: 100
      split_overlap: 0
      split_threshold: 0
      splitting_function:
  HuggingFaceTEISparseDocumentEmbedder:
    type: haystack_integrations.components.embedders.huggingface_api.sparse_document_embedder.HuggingFaceTEISparseDocumentEmbedder
    init_parameters:
      api_base_url: http://localhost:8080
      token:
        type: env_var
        env_vars:
        - HF_API_TOKEN
        - HF_TOKEN
        strict: false
      batch_size: 32
      progress_bar: true
      concurrency_limit: 4
      timeout: 30.0
      meta_fields_to_embed:
      embedding_separator: "\n"
  DocumentWriter:
    type: haystack.components.writers.document_writer.DocumentWriter
    init_parameters:
      policy: OVERWRITE
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: Sparse-Index
          max_chunk_bytes: 104857600
          return_embedding: false
          create_index: true
          http_auth:
          use_ssl:
          verify_certs:
          timeout:

connections:
- sender: TextFileToDocument.documents
  receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
  receiver: HuggingFaceTEISparseDocumentEmbedder.documents
- sender: HuggingFaceTEISparseDocumentEmbedder.documents
  receiver: DocumentWriter.documents

max_runs_per_component: 100

metadata: {}

inputs:
  files:
  - TextFileToDocument.sources

Parameters

Inputs

Parameter	Type	Description
documents	List[Document]	A list of Documents to embed.

Outputs

Parameter	Type	Description
documents	List[Document]	Documents with their sparse_embedding field populated.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
api_base_url	str	http://localhost:8080	Base URL of the TEI server, or the gRPC target when use_grpc is on.
token	Optional[Secret]	Secret.from_env_var(['HF_API_TOKEN', 'HF_TOKEN'], strict=False)	Token sent as HTTP bearer authorization to the TEI server, if required.
prefix	str	""	A string to add before each prepared Document text.
suffix	str	""	A string to add after each prepared Document text.
batch_size	int	32	Number of documents sent in each HTTP call. Not used with gRPC.
progress_bar	bool	True	Whether to show a progress bar while embedding. Disable in production to keep logs clean.
meta_fields_to_embed	Optional[List[str]]	None	Metadata fields to embed before the Document content.
embedding_separator	str	\n	Separator used to concatenate metadata fields and Document content.
timeout	Optional[float]	30.0	HTTP request timeout in seconds. Set to None to disable.
headers	Optional[Dict[str, str]]	None	Additional HTTP headers to send with each request.
concurrency_limit	int	4	Maximum concurrent HTTP calls or gRPC streams made by run_async().
use_grpc	bool	False	Connect over gRPC instead of HTTP.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Description
documents	List[Document]	A list of Documents to embed.

Related Information

• Use Hugging Face Models
• HuggingFaceTEISparseTextEmbedder
• HuggingFaceAPITextEmbedder
• Pipeline Components