Train Sentence Transformers
Purpose
Help agents train or fine-tune sentence-transformers models for retrieval, similarity, reranking, learned sparse retrieval, clustering, classification, paraphrase mining, or deduplication.
Quick Start
- Identify model type: bi-encoder
SentenceTransformer, CrossEncoder reranker, or SparseEncoder.
- Match loss function to data shape.
- Choose the evaluator that matches the task and primary metric.
- Smoke-test with a tiny slice before long training.
- Capture baseline score before training and emit an end-of-run verdict.
- Push or publish only after validation.
Operating Constraints
- Do not synthesize a training script from memory when production templates or examples exist.
- Do not train without baseline evaluation.
- Do not use cached losses with incompatible gradient-checkpointing settings.
- Do not use a reranker when first-pass recall is too weak.
- Do not publish models or cards containing private data.
- Keep run logs, seeds, model names, data versions, and primary metrics reproducible.
Inputs This Skill Expects
- Task type and model class.
- Dataset shape: pairs, triplets, query-positive-negative, labels, rankings, or sparse targets.
- Base model, language/domain, hardware, and Hub policy.
- Evaluator and baseline metric.
- Hard-negative mining plan when relevant.
Output Contract
- State model type, loss, evaluator, data shape, metric, and training command.
- Include smoke-test command and baseline evaluation.
- Report verdict: win, marginal, or regression.
- State publish, iterate, or reject decision with metric evidence.
Procedure
- Classify the model type from task wording.
- Inspect dataset columns and labels.
- Choose loss and evaluator from data shape and task.
- Prepare training script/config from a known-good template.
- Run smoke test.
- Run training and log baseline plus final metrics.
- Publish or archive artifacts only after the verdict is acceptable.
Pitfalls And Gotchas
- Choosing a loss that silently mismatches columns or labels.
- Evaluating rerankers with first-pass retrieval metrics.
- Forgetting named-evaluator metric keys.
- Skipping hard-negative quality checks.
- Reporting high scores despite sparse dimension collapse.
Progressive Disclosure
Start with model type and data shape. Expand into hard-negative mining, LoRA, Matryoshka, distillation, multilingual transfer, sparse regularization, or cloud execution only when the training objective needs it.
Verification Pattern
- Confirm model type, loss, evaluator, and metric align.
- Confirm baseline evaluation ran before training.
- Confirm smoke test passed.
- Confirm final verdict compares baseline and trained model.
- Confirm publication respects privacy and artifact policy.
1---2name: train-sentence-transformers3description: Guardrail for training sentence-transformers bi-encoders, cross-encoders, and sparse encoders with correct loss, evaluator, hard-negative, and publishing choices.4---56# Train Sentence Transformers78## Purpose9Help agents train or fine-tune sentence-transformers models for retrieval, similarity, reranking, learned sparse retrieval, clustering, classification, paraphrase mining, or deduplication.1011## Quick Start121. Identify model type: bi-encoder `SentenceTransformer`, `CrossEncoder` reranker, or `SparseEncoder`.132. Match loss function to data shape.143. Choose the evaluator that matches the task and primary metric.154. Smoke-test with a tiny slice before long training.165. Capture baseline score before training and emit an end-of-run verdict.176. Push or publish only after validation.1819## Operating Constraints20- Do not synthesize a training script from memory when production templates or examples exist.21- Do not train without baseline evaluation.22- Do not use cached losses with incompatible gradient-checkpointing settings.23- Do not use a reranker when first-pass recall is too weak.24- Do not publish models or cards containing private data.25- Keep run logs, seeds, model names, data versions, and primary metrics reproducible.2627## Inputs This Skill Expects28- Task type and model class.29- Dataset shape: pairs, triplets, query-positive-negative, labels, rankings, or sparse targets.30- Base model, language/domain, hardware, and Hub policy.31- Evaluator and baseline metric.32- Hard-negative mining plan when relevant.3334## Output Contract35- State model type, loss, evaluator, data shape, metric, and training command.36- Include smoke-test command and baseline evaluation.37- Report verdict: win, marginal, or regression.38- State publish, iterate, or reject decision with metric evidence.3940## Procedure411. Classify the model type from task wording.422. Inspect dataset columns and labels.433. Choose loss and evaluator from data shape and task.444. Prepare training script/config from a known-good template.455. Run smoke test.466. Run training and log baseline plus final metrics.477. Publish or archive artifacts only after the verdict is acceptable.4849## Pitfalls And Gotchas50- Choosing a loss that silently mismatches columns or labels.51- Evaluating rerankers with first-pass retrieval metrics.52- Forgetting named-evaluator metric keys.53- Skipping hard-negative quality checks.54- Reporting high scores despite sparse dimension collapse.5556## Progressive Disclosure57Start with model type and data shape. Expand into hard-negative mining, LoRA, Matryoshka, distillation, multilingual transfer, sparse regularization, or cloud execution only when the training objective needs it.5859## Verification Pattern60- Confirm model type, loss, evaluator, and metric align.61- Confirm baseline evaluation ran before training.62- Confirm smoke test passed.63- Confirm final verdict compares baseline and trained model.64- Confirm publication respects privacy and artifact policy.
tim-osterhus