HuggingFaceAPITextEmbedder

Embed strings using Hugging Face APIs.

info

This component embeds plain text. To embed a list of documents, use HuggingFaceAPIDocumentEmbedder.

Key Features

• Embeds text strings using Hugging Face APIs: free Serverless Inference API, paid Inference Endpoints, and self-hosted Text Embeddings Inference (TEI)
• Use in query pipelines to embed user queries for semantic search
• Returns a vector embedding of the input text

Configuration

1. Drag the HuggingFaceAPITextEmbedder component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Select the API type: serverless_inference_api, inference_endpoints, or text_embeddings_inference.
   2. Enter the API parameters: for serverless_inference_api, enter the model ID; for inference_endpoints or text_embeddings_inference, enter the endpoint URL.
   3. Enter your Hugging Face API token. Connect Haystack Platform to your Hugging Face account first. For details, see Use Hugging Face Models.
4. Go to the Advanced tab to configure prefix, suffix, truncation, and normalization settings.

Connections

HuggingFaceAPITextEmbedder accepts a text string through its text input. It outputs the embedding as a list of floats (embedding).

Connect the Input component's query output to this component's text input. Connect the embedding output to an embedding retriever's query_embedding input.

Embedding Models in Query Pipelines and Indexes

The embedding model you use to embed documents in your indexing pipeline must be the same as the embedding model you use to embed the query in your query pipeline.

This means the embedders for your indexing and query pipelines must match. For example, if you use CohereDocumentEmbedder to embed your documents, you should use CohereTextEmbedder with the same model to embed your queries.

Source Code

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

Usage Examples

Basic Configuration

  query_embedder:
    type: haystack.components.embedders.hugging_face_api_text_embedder.HuggingFaceAPITextEmbedder
    init_parameters:
      api_type: serverless_inference_api
      api_params:
        model: BAAI/bge-small-en-v1.5
      token:
        type: env_var
        env_vars:
        - HF_API_TOKEN
        - HF_TOKEN
        strict: false
      truncate: true
      normalize: false

Using the component in a pipeline

This query pipeline uses HuggingFaceAPITextEmbedder to embed a query and retrieve documents using semantic search:

components:
  query_embedder:
    type: haystack.components.embedders.hugging_face_api_text_embedder.HuggingFaceAPITextEmbedder
    init_parameters:
      api_type: serverless_inference_api
      api_params:
        model: BAAI/bge-small-en-v1.5
      token:
        type: env_var
        env_vars:
          - HF_API_TOKEN
          - HF_TOKEN
        strict: false
      prefix:
      suffix:
      truncate: true
      normalize: false

  embedding_retriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
            - ${OPENSEARCH_HOST}
          http_auth:
            - ${OPENSEARCH_USER}
            - ${OPENSEARCH_PASSWORD}
          use_ssl: true
          verify_certs: false
      top_k: 20

connections:
  - sender: query_embedder.embedding
    receiver: embedding_retriever.query_embedding

inputs:
  query:
    - query_embedder.text
  filters:
    - embedding_retriever.filters

outputs:
  documents: embedding_retriever.documents

Parameters

Inputs

Parameter	Type	Description
text	str	Text to embed.

Outputs

Parameter	Type	Description
embedding	List[float]	The embedding of the input text.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
api_type	Union[HFEmbeddingAPIType, str]		The type of Hugging Face API to use. Options: serverless_inference_api, inference_endpoints, text_embeddings_inference.
api_params	Dict[str, str]		A dictionary containing either model (Hugging Face model ID, required for serverless_inference_api) or url (URL of the inference endpoint, required for inference_endpoints or text_embeddings_inference).
token	Optional[Secret]	Secret.from_env_var(['HF_API_TOKEN', 'HF_TOKEN'], strict=False)	The Hugging Face token to use as HTTP bearer authorization. Check your HF token in your account settings.
prefix	str		A string to add at the beginning of each text.
suffix	str		A string to add at the end of each text.
truncate	Optional[bool]	True	Truncates the input text to the maximum length supported by the model. Applicable when api_type is text_embeddings_inference or inference_endpoints if the backend uses Text Embeddings Inference. Ignored for serverless_inference_api.
normalize	Optional[bool]	False	Normalizes the embeddings to unit length. Applicable when api_type is text_embeddings_inference or inference_endpoints if the backend uses Text Embeddings Inference. Ignored for serverless_inference_api.

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
text	str	Text to embed.

Related Information

• Use Hugging Face Models
• HuggingFaceAPIDocumentEmbedder