| name | train-sentence-transformers |
| description | Trains or fine-tunes sentence-transformers bi-encoders, CrossEncoder rerankers, and SparseEncoder/SPLADE using the bundled references and example scripts. Use when the user asks to train embeddings, rerankers, or SPLADE on custom data. Not for inference-only embedding calls, Hugging Face paper lookup, or model-card eval tables. |
| version | 1.0.1 |
| risk | unknown |
| source | https://github.com/huggingface/skills/tree/main/skills/train-sentence-transformers |
| source_repo | huggingface/skills |
| source_type | official |
| date_added | 2026-07-01T00:00:00.000Z |
| license | Apache-2.0 |
| license_source | https://github.com/huggingface/skills/blob/main/LICENSE |
Train a sentence-transformers Model
Overview
This skill trains or fine-tunes sentence-transformers models across three model classes:
SentenceTransformer (bi-encoder; dense or static embedding model) — for retrieval, similarity, clustering, classification, paraphrase mining, dedup, multimodal.CrossEncoder (reranker; pair scoring) — for two-stage retrieval / pair classification.SparseEncoder (SPLADE; sparse vectors over vocabulary) — for learned-sparse retrieval, inverted-index backends (Elasticsearch / OpenSearch / Lucene).
This SKILL.md is a router, not a manual. It tells you which references and example scripts to load for your task. The actual content — recommended losses, evaluators, training-script structure, model selection, training-arg knobs, troubleshooting — lives in references/ and scripts/.
Do not synthesize a training script from this file alone. Open the matching train_<type>_example.py in this skill's scripts folder and copy it as your starting point. The templates contain load-bearing scaffolding (autocast helper, model-card class, logger silencing list, force=True, seed, TF32, version-compatible imports, named-evaluator metric handling) that prior agent runs have repeatedly missed when rolling their own from a synthesized snippet.
When to Use
Use this skill when the user needs to:
- Train or fine-tune a dense embedding model (retrieval, similarity, clustering, classification, paraphrase mining, dedup, multimodal).
- Train or fine-tune a reranker / cross-encoder for two-stage retrieval or pair classification.
- Train or fine-tune a SPLADE / sparse encoder for learned-sparse retrieval or inverted-index backends.
- Fine-tune an existing sentence-transformers checkpoint on a custom dataset.
- Add LoRA, distillation, Matryoshka, multi-dataset, multilingual, or static-embedding variants.
Trigger keywords: embedding model training, fine-tune sentence-transformers, train reranker, train cross-encoder, train SPLADE, sparse encoder training, retrieval model fine-tuning, sentence similarity model training, bi-encoder training, dense retrieval training.
Prerequisites
pip install "sentence-transformers[train]>=5.0"
# For multimodal [SentenceTransformer], add the relevant extra:
# pip install "sentence-transformers[train,image]>=5.0"
# pip install "sentence-transformers[train,audio]>=5.0"
# pip install "sentence-transformers[train,video]>=5.0"
pip install trackio # optional tracker; or wandb / tensorboard / mlflow
hf auth login # or set HF_TOKEN with write scope (for Hub push)
