Sentence Transformers (SBERT) Cheat Sheet

sentence-transformers cheat sheet

Sentence Transformers (SBERT) computes dense, sparse and reranking embeddings for text (and, in v5, images/audio/video) — the backbone of semantic search, retrieval, RAG and clustering. Three model families: SentenceTransformer (bi-encoder, dense vectors), CrossEncoder (reranker, scores a pair), and SparseEncoder (learned sparse/lexical vectors, new in v5). Each has a matching Trainer. This sheet targets v5.x.

load & encode search / retrieval reranking (CrossEncoder) sparse (SparseEncoder) training gotcha ★ most common

Verified 2026-08-24 against the official docs at sbert.net (Sentence Transformers 5.x) and the huggingface/sentence-transformers repo. Built on 🌐 Transformers; embedding models are pulled from the Hugging Face Hub.

1Install & load a modelv5.x

pip install "sentence-transformers"★
Pulls in Transformers + PyTorch. Add [train] extras for the training stack.
from sentence_transformers import SentenceTransformer model = SentenceTransformer("all-MiniLM-L6-v2")★
Small, fast, 384-dim — the classic default. Bigger/better: all-mpnet-base-v2, BAAI/bge-*, Qwen/Qwen3-Embedding-*.
SentenceTransformer(id, device="cuda", model_kwargs={"dtype":"auto"})
Choose device/precision; truncate_dim= for Matryoshka models, backend="onnx"/"openvino" for fast CPU inference.
model.get_sentence_embedding_dimension() · model.max_seq_length
Inspect vector size and the token limit (inputs longer than this are truncated).

2encode() & similarity()text → vectors

emb = model.encode(["a sentence", "another"])★
Returns an (n, dim) numpy array (or a torch tensor with convert_to_tensor=True). Batched & parallelized internally.
model.encode(texts, normalize_embeddings=True, batch_size=64, show_progress_bar=True)★
Normalize to unit length so cosine == dot product. Tune batch_size for throughput.
scores = model.similarity(emb1, emb2) # (n1, n2) matrix★
Uses the model's configured metric (cosine by default). similarity_pairwise for row-aligned pairs.
model.similarity_fn_name # "cosine" | "dot" | "euclidean" | "manhattan"
Set at load via similarity_fn_name=; controls both similarity() and search defaults.

3encode_query / encode_documentasymmetric search

corpus_emb = model.encode_document(corpus)★
Encode the corpus once, keep the tensor as your index. Applies the model's document prompt if it has one.
q_emb = model.encode_query("my question")★
Encode each incoming query with the query prompt. Query/document methods (v5) replace manually prepending prompts.
model.similarity(q_emb, corpus_emb)
Then rank the corpus for the query — the core of a retrieval pipeline.
match query & doc encodersgotcha
Use the same model for both sides. Many retrieval models are asymmetric — skipping query/document prompts silently hurts recall.

8SentenceTransformerTrainerthe loop

from sentence_transformers import (SentenceTransformerTrainer, SentenceTransformerTrainingArguments)★
Mirrors the 🌐 Transformers Trainer API (v4+ refactor). CrossEncoder/SparseEncoder have their own Trainer classes.
trainer = SentenceTransformerTrainer(model=model, args=args, train_dataset=ds, loss=loss) trainer.train()★
Provide a dataset, a loss, and args (batch size, epochs, lr). Multi-GPU via accelerate.
args = SentenceTransformerTrainingArguments(output_dir="out", num_train_epochs=1, per_device_train_batch_size=64, batch_sampler="no_duplicates")
no_duplicates sampler matters for in-batch-negative losses. eval_strategy, warmup, fp16/bf16 as usual.
model.save_pretrained("out/") · model.push_to_hub("me/model")
Save + share the fine-tuned embedder.

9Losses & data formatmatch them up

from sentence_transformers.losses import MultipleNegativesRankingLoss loss = MultipleNegativesRankingLoss(model)★
The workhorse for retrieval: needs (anchor, positive) pairs (or triplets); other rows in the batch are the negatives.
CoSENTLoss · ContrastiveLoss · TripletLoss · SoftmaxLoss
Pick by data: labeled similarity scores → CoSENT; (a,pos,neg) triplets → Triplet; NLI-style → Softmax.
Dataset columns == loss inputs★
A 🌐 datasets Dataset whose column order matches the loss (e.g. anchor, positive); a label/score column when the loss needs one.
wrong loss for your datagotcha
The #1 fine-tuning mistake: mismatched loss & dataset shape. Check the loss's docstring for the exact expected columns.

Worth memorizing

3 model typesSentenceTransformer (dense), CrossEncoder (rerank), SparseEncoder (lexical, v5)

encode corpus onceencode_document to build the index, encode_query per request

retrieve then rerankbi-encoder fetches ~100, CrossEncoder reorders the top few

semantic_search = cos_sim + top-kbrute force is fine to ~1M; beyond that use FAISS/pgvector/Qdrant

use the model's promptsE5/BGE need query/passage prefixes; encode_query/document handle it

quantize to int8/binary4–32× smaller vectors for cheap storage & search

loss must match data shapeMultipleNegativesRankingLoss wants (anchor, positive) pairs

fine-tune on in-domain pairsthe single biggest quality win for your own corpus

sentence-transformers cheat sheet

Outline

Embed

Search

Rerank & sparse

Train

Reference

Embed

Search & Retrieval

Rerank & Sparse

Train / Fine-tune

Gotchas

Worth memorizing