Skip to content
Nappai Documentation

HuggingFace Embeddings

The HuggingFace Embeddings component turns plain text into numerical vectors (embeddings) that can be used for searching, clustering, or feeding into other AI models. It does this by sending your text to a Hugging Face Inference API model and returning the resulting vector.

How it Works

When you add this component to a workflow, it connects to the Hugging Face Inference API.

  1. Credential – You first select a pre‑configured HuggingFace API credential. The API key stored in that credential is used to authenticate your requests.
  2. API URL – The component sends a request to the URL you provide (default is http://localhost:8080).
  3. Model Name – You choose which Hugging Face model to use (default is BAAI/bge-large-en-v1.5).
  4. The component sends your input text to the API, receives the embedding vector, and outputs it as Embeddings.

The process is all handled behind the scenes; you only need to set the URL, model, and credential.

Inputs

Mapping Mode

This component has a special mode called Mapping Mode. When you enable this mode using the toggle switch, an additional input called Mapping Data is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • API URL: The endpoint of the Hugging Face Inference API. Leave the default (http://localhost:8080) if you are running a local server, or enter the URL of a hosted API.
  • Model Name: The name of the Hugging Face model you want to use for embeddings. The default is BAAI/bge-large-en-v1.5, but you can choose any model that supports embeddings.

Credential
Before using the component, you must configure a HuggingFace API credential in Nappai’s credential section. The credential must contain a HuggingFace Api Key (password). Once configured, select that credential in the component’s Credential field. The API key is then used automatically to authenticate your requests.

Outputs

  • Embeddings: A vector representation of the input text. This output can be fed into other components such as similarity search, clustering, or downstream AI models.

Usage Example

  1. Set up the credential

    • Go to Credentials → Add Credential → HuggingFace API.
    • Enter your Hugging Face API key and save.

  2. Add the component

    • Drag HuggingFace Embeddings into your workflow.
    • In the Credential field, select the credential you just created.
    • Leave API URL and Model Name at their defaults, or change them if you are using a different endpoint or model.

  3. Provide text

    • Connect the output of a text‑processing component (e.g., a Text Input or Document Splitter) to the Embeddings input of this component.

  4. Run the workflow

    • The component will send the text to the Hugging Face API and return the embeddings.
    • Use the embeddings in subsequent steps, such as a Similarity Search component.
  • OpenAI Embeddings – Generate embeddings using OpenAI’s models.
  • Local Embeddings – Create embeddings locally without external API calls.
  • Similarity Search – Find the most similar documents based on embeddings.
  • Document Splitter – Split large documents into smaller chunks before embedding.

Tips and Best Practices

  • Choose the right model – Larger models like BAAI/bge-large-en-v1.5 give better quality but may be slower.
  • Test with small data first – Verify that embeddings look reasonable before scaling up.
  • Use Mapping Mode for batch processing – Enable Mapping Mode to process many records at once.
  • Keep credentials secure – Store your API key in Nappai’s credential store and never expose it in the workflow.
  • Monitor API usage – Hugging Face may have rate limits; check your account quota.

Security Considerations

  • The API key is stored in a secure credential and never exposed in the workflow UI.
  • Ensure that the credential is only shared with users who need access.
  • If you are using a public API URL, make sure the endpoint is trusted and uses HTTPS to protect data in transit.