Sentence Transformers

5.3.0 · active · verified Tue Mar 17

Framework for computing dense sentence/text/image embeddings using transformer models. Primary use cases: semantic search, semantic similarity, clustering, and reranking. Wraps transformers and provides SentenceTransformer (embedding), CrossEncoder (reranker), and SparseEncoder (sparse embedding) classes. 15,000+ pretrained models on HF Hub. Now officially maintained by Hugging Face (Tom Aarsen) after transfer from UKP Lab/TU Darmstadt. Package name: sentence-transformers (hyphen). Import name: sentence_transformers (underscore).

Warnings

breaking Python 3.10+ required as of sentence-transformers 5.0. Python 3.9 and below will fail to install.
Fix: Upgrade to Python 3.10+. For Python 3.9, pin: pip install sentence-transformers<5.
breaking sentence-transformers 5.2.2+ dropped the requests dependency in favor of optional httpx, aligning with transformers v5. Code that relied on requests being transitively installed via sentence-transformers may see ImportError on requests.
Fix: If your code uses requests directly, add it explicitly: pip install requests.
breaking Training with sentence-transformers 5.x requires pinning to a compatible transformers version. sentence-transformers 5.2.3 introduced a compatibility fix for transformers v5.2 Trainer changes. Older sentence-transformers 5.x with transformers v5.2 causes training failures at the logging step.
Fix: Upgrade to sentence-transformers>=5.2.3 when using transformers>=5.2.
gotcha encode() returns numpy float32 arrays by default, not torch tensors. Passing embeddings directly to PyTorch operations without converting first causes TypeError. Many tutorials omit this.
Fix: Use convert_to_tensor=True to get torch.Tensor, or call torch.tensor(embeddings) manually.
gotcha CrossEncoder and SentenceTransformer are architecturally different and not interchangeable. CrossEncoder scores (query, doc) pairs — it cannot encode a corpus of documents independently. Using CrossEncoder where SentenceTransformer is needed produces wrong results with no error.
Fix: Use SentenceTransformer for bi-encoder embedding (fast, scalable). Use CrossEncoder for reranking a small candidate set (slow, higher accuracy).
gotcha util.cos_sim() returns values in [-1, 1]. It does NOT return [0, 1]. Thresholding at 0.5 as a "similarity cutoff" is a common mistake — the actual meaningful threshold depends on the model and task.
Fix: Calibrate thresholds empirically for your specific model and domain. For all-MiniLM-L6-v2, 0.3+ is often a reasonable rough threshold for semantic similarity.
gotcha Package name is sentence-transformers (hyphen) but import name is sentence_transformers (underscore). import sentence-transformers raises SyntaxError. from sentence-transformers import ... also fails.
Fix: pip install sentence-transformers (hyphen). from sentence_transformers import SentenceTransformer (underscore).

Install

pip install sentence-transformers Core (inference only)
pip install sentence-transformers[train] With training dependencies
pip install sentence-transformers[onnx] With ONNX backend (CPU inference optimization)
pip install sentence-transformers[onnx-gpu] With ONNX GPU backend
pip install sentence-transformers[openvino] With OpenVINO backend (Intel)

Imports

SentenceTransformer
```
from sentence_transformers import SentenceTransformer
```
Hyphen in package name, underscore in import. The most common install/import confusion for new users.
CrossEncoder
```
from sentence_transformers import CrossEncoder
```
For reranking. CrossEncoder scores pairs (query, doc) — not suitable for encoding corpora. Use SentenceTransformer for that.
util.cos_sim
```
from sentence_transformers import util
```
util.cos_sim(), util.dot_score(), util.semantic_search() are built-in similarity utilities.

Quickstart

encode() returns float32 numpy arrays by default. Pass convert_to_tensor=True for PyTorch tensors. Models are cached in HF_HOME after first download. all-MiniLM-L6-v2 is 384-dim, fast, and good for general use.

from sentence_transformers import SentenceTransformer, util
import numpy as np

# Load model (downloads on first use, ~90MB for MiniLM)
model = SentenceTransformer("all-MiniLM-L6-v2")

# Encode sentences → numpy float32 arrays by default
sentences = [
    "The cat sat on the mat.",
    "A feline rested on a rug.",
    "The stock market crashed today."
]
embeddings = model.encode(sentences)  # shape: (3, 384)
print(embeddings.shape)

# Cosine similarity
cosine_scores = util.cos_sim(embeddings[0], embeddings[1:])
print(cosine_scores)  # similar pair scores higher

# Return torch tensors instead of numpy
embeddings_tensor = model.encode(sentences, convert_to_tensor=True)

# Semantic search
query_embedding = model.encode("Where did the cat sleep?", convert_to_tensor=True)
hits = util.semantic_search(query_embedding, embeddings_tensor, top_k=2)
print(hits)

view raw JSON →