Hugging Face Embedder

Call a Hugging Face feature-extraction endpoint with HuggingfaceCustomEmbedder.

HuggingfaceCustomEmbedder defaults to intfloat/multilingual-e5-large. Set dimensions=1024 so Agno records that model’s expected vector width.

huggingface_embedder.py

from agno.knowledge.embedder.huggingface import HuggingfaceCustomEmbedder

embedder = HuggingfaceCustomEmbedder(dimensions=1024)

passage_vector = embedder.get_embedding(
    "passage: The quick brown fox jumps over the lazy dog."
)
query_vector = embedder.get_embedding("query: Which animal jumps?")

print(f"Passage output length: {len(passage_vector)}")
print(f"Query output length: {len(query_vector)}")

The default E5 model expects passage: for indexed passages and query: for retrieval queries. HuggingfaceCustomEmbedder does not add these prefixes. Add them before calling the embedder. The adapter also returns the feature-extraction response without pooling or flattening it. Confirm that your endpoint returns one flat vector before using it with a vector database.

The dimensions field does not request pooling or a specific output size from Hugging Face. It configures the expected width used by Agno’s vector database integrations.

Run the Example

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
2. Export the API key

   export HUGGINGFACE_API_KEY=your_hugging_face_api_key_here
   
3. Install dependencies

   uv pip install -U agno huggingface-hub
   
4. Run the example

   python huggingface_embedder.py
   

Developer Resources

• HuggingfaceCustomEmbedder reference
• Embedders overview
• Hugging Face InferenceClient
• Multilingual E5 model card