What is HuggingFaceEmbeddings?
HuggingFaceEmbeddings wraps the sentence-transformers library to run embedding models entirely on your machine. It downloads model weights from Hugging Face Hub on first use, then runs inference locally — no API key, no outbound requests, no per-token cost. The default model (sentence-transformers/all-mpnet-base-v2) produces 768-dimensional vectors with strong semantic quality across general English text.
The class accepts any Sentence Transformers-compatible model via model_name, letting you swap in domain-specific fine-tunes, multilingual models (e.g. paraphrase-multilingual-mpnet-base-v2), or lightweight models for edge devices. GPU acceleration is automatic when torch detects CUDA or MPS; pass model_kwargs={"device": "cpu"} to force CPU even on a GPU machine. encode_kwargs controls batch size and normalisation — normalizing vectors to unit length is important if your vector store uses cosine similarity.
In production, pre-warm the model at startup (call embed_query once) so the first real request does not pay the model-load penalty. Cache the HuggingFaceEmbeddings instance as a module-level singleton; instantiating it per-request re-downloads the model on cold containers. The sentence-transformers package has a max sequence length (usually 512 tokens) — documents longer than that are silently truncated, so chunk before embedding.
When to Use
You need local embeddings without API calls. Use for privacy, offline, or when cost matters more than speed.
Use Cases
- • Local embeddings
- • Privacy-sensitive data
- • Offline systems
- • Self-hosted RAG
- • Custom models
- • Cost control
Key Features
- ✓ Local inference
- ✓ No API calls
- ✓ GPU support
- ✓ Hundreds of models
- ✓ Custom fine-tuning
- ✓ Complete privacy
When NOT to Use
For production SLA or highest quality—use OpenAI.
Notes
sentence-transformers max sequence length is 512 tokens
Most sentence-transformers models silently truncate input beyond their context window (usually 512 tokens / ~380 words). If you pass long document chunks, split them before embedding — the model will not raise an error, it will just drop the tail silently.
Model files are cached in ~/.cache/huggingface/hub
The first call downloads model weights to disk. In Docker or serverless environments, mount a persistent volume at /root/.cache/huggingface to avoid re-downloading on every cold start. Set HF_HOME environment variable to change the cache path.
GPU is auto-detected but may not be what you want
Passing model_kwargs={"device": "cuda"} explicitly is safer than relying on auto-detection in multi-GPU or shared-GPU environments. Use "cpu" when running many parallel workers — VRAM contention on a shared GPU is usually slower than CPU with batch processing.
langchain-community vs langchain-huggingface package
The canonical import moved to langchain-huggingface (pip install langchain-huggingface) in mid-2024. The langchain-community import still works but emits a deprecation warning. Prefer: from langchain_huggingface import HuggingFaceEmbeddings in new projects.
Import
from langchain_community.embeddings import HuggingFaceEmbeddingsConfiguration
| Parameter | Type | Default | Purpose |
|---|---|---|---|
| model_name | str | sentence-transformers/all-mpnet-base-v2 | Hugging Face model ID |
Usage Examples
Default Model (all-mpnet-base-v2)
embeddings = HuggingFaceEmbeddings()
vec = embeddings.embed_query('What is AI?')
print(len(vec)) # 768 dimensions, works offlineGPU + Normalised Batch Embeddings
from langchain_community.embeddings import HuggingFaceEmbeddings
embeddings = HuggingFaceEmbeddings(
model_name="BAAI/bge-small-en-v1.5",
model_kwargs={"device": "cuda"},
encode_kwargs={"normalize_embeddings": True},
)
docs = ["LangChain is a framework", "RAG pipelines"]
vecs = embeddings.embed_documents(docs)
print(len(vecs), len(vecs[0])) # 2, 384Custom / Private Model
# Fine-tuned or private model from HF Hub
embeddings = HuggingFaceEmbeddings(
model_name="your-org/custom-embed-model",
model_kwargs={"trust_remote_code": True},
)
vec = embeddings.embed_query('domain specific query')Common Pitfalls
❌ Forget to install sentence-transformers
✅ pip install sentence-transformers
Alternative Embedding Models
| Model | When to Use |
|---|---|
| OpenAIEmbeddings | For highest quality embeddings |
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with HuggingFaceEmbeddings and the wider framework.
HuggingFaceEmbeddings FAQ
What is HuggingFaceEmbeddings in LangChain?
Create embeddings using Hugging Face models locally. HuggingFaceEmbeddings wraps the sentence-transformers library to run embedding models entirely on your machine. It downloads model weights from Hugging Face Hub on first use, then runs inference locally — no API key, no outbound requests, no per-token cost. The default model (sentence-transformers/all-mpnet-base-v2) produces 768-dimensional vectors with strong semantic quality across general English text. The class accepts any Sentence Transformers-compatible model via model…
Which package provides HuggingFaceEmbeddings?
DevShelfHub documents HuggingFaceEmbeddings from the langchain-community package. Pin your installed LangChain version and match imports to the snippet on this page.
When should I use HuggingFaceEmbeddings?
You need local embeddings without API calls. Use for privacy, offline, or when cost matters more than speed.
When should I avoid using HuggingFaceEmbeddings?
For production SLA or highest quality—use OpenAI.
How do I import HuggingFaceEmbeddings in Python?
from langchain_community.embeddings import HuggingFaceEmbeddings
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.