Trains sentence-transformers models - bi-encoders, CrossEncoder rerankers, and SPLADE sparse encoders - covering loss selection, hard-negative mining, evaluators, LoRA, Matryoshka, and Hub publishing.
---
name: train-sentence-transformers
description: Train or fine-tune sentence-transformers models - SentenceTransformer bi-encoders (retrieval, similarity, clustering), CrossEncoder rerankers (two-stage retrieval, pair classification), and SparseEncoder/SPLADE (learned-sparse retrieval). Covers loss selection, hard-negative mining, evaluators, distillation, LoRA, and Matryoshka.
---
# Train a sentence-transformers Model
This SKILL.md is a router: it tells you which references and example scripts to load. Do not synthesize a training script from this file alone - copy the per-type production template.
## Workflow
1. Identify the model type: bi-encoder ("embedding"/"vector search"), CrossEncoder ("rerank"/"two-stage"), or SparseEncoder ("SPLADE"/"inverted index").
2. Read the required per-type references in full - losses (data-shape mapping), evaluators (metric-key construction), and architectures.
3. Read the cross-cutting references - `training_args.md` (precision: load fp32 + autocast, not torch_dtype), `dataset_formats.md`, and `base_model_selection.md`.
4. Copy the matching production template (`scripts/train_<type>_example.py`) and adapt it; use variant scripts for Matryoshka, LoRA, distillation, or multilingual.
5. Mine hard negatives with `scripts/mine_hard_negatives.py` when needed; default to local execution, single run, and a public Hub push wrapped in try-except.
Full skill & source: https://github.com/huggingface/skills/tree/ea9a24f38a98baf2430dab3bcb31a89753ae9e6d/skills/train-sentence-transformers