C✳CODEZ.WIN
🌐 English

Localized reading guide

train-sentence-transformersPurpose, usage and source

Train or fine-tune sentence-transformers models across 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 embedding model for learned-sparse retrieval), and MultiVectorEncoder (ColBERT / late-interaction, per-token embeddings scored with MaxSim). Covers loss selection, hard-negative mining, evaluators, distillation, LoRA, Matryoshka, and Hugging Face Hub publishing. Use for any sentence-transformers training task.

Source retrieved:

Source repository
huggingface/skills
SKILL.md
skills/train-sentence-transformers/SKILL.md
Repository stars
11,241
Repository updated
2026-10-30
Categories
Development
Last collected

License: Apache-2.0

Source SKILL.md

Workflow excerpts are reading aids, not executable instructions from Codez. No third-party Skill was run to produce this page.

The purpose and workflow passages below are upstream material, organized and translated for reading. They are distinct from the separately labeled Codez editorial analysis.

What this Skill does

Train or fine-tune sentence-transformers models across 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 embedding model for learned-sparse retrieval), and MultiVectorEncoder (ColBERT / late-interaction, per-token embeddings scored with MaxSim). Covers loss selection, hard-negative mining, evaluators, distillation, LoRA, Matryoshka, and Hugging Face Hub publishing. Use for any sentence-transformers training task.

How the upstream workflow works

5. Workflow

Identify the model type (§1). Ask if ambiguous. Load the §2 required-reading files for that type. Open scripts/train__example.py and copy it as your starting point. Replace MODEL_NAME, DATASET_NAME, RUN_NAME, the loss, and the evaluator with the user's task. Cross-check loss/data-shape match against references/losses_.md. Cross-check the metric_for_best_model key against references/evaluators_.md (named evaluators format the key as eval_{name}_{primary_metric}).

Upstream passage · L90 ↗

Train a sentence-transformers Model

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 per-type production template (scripts/train__example.py) 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.

Upstream passage · L6 ↗

1. Identify the model type

Tiebreakers when the request is ambiguous: "embedding model" / "vector search" / "similarity" → [SentenceTransformer]. "rerank" / "ranker" / "two-stage" → [CrossEncoder]. "SPLADE" / "sparse" / "inverted index" → [SparseEncoder]. "ColBERT" / "late interaction" / "multi-vector" / "MaxSim" / "ColPali" / "ColQwen" → [MultiVectorEncoder]. If still unclear, ask.

Upstream passage · L12 ↗

Requirements and setup

Prerequisites

GPU strongly recommended. CPU works only for demos and [SentenceTransformer] StaticEmbedding.

Upstream passage · L100 ↗
Upstream passage · bash ↗
pip install "sentence-transformers[train]>=5.0"        # add [train,image] / [audio] / [video] for [SentenceTransformer] multimodal
                                                       # [MultiVectorEncoder] requires >=6.0
pip install trackio                                    # optional tracker (or wandb / tensorboard / mlflow)
hf auth login                                          # or set HF_TOKEN with write scope (for Hub push)

Limits and quality checks

4. Constraints the produced script must satisfy

These are non-negotiable contracts. Implementation lives in the production templates and references. Do not reinvent. Capture the pre-training evaluator score as baseline_eval before trainer.train().

Upstream passage · L76 ↗

Start with a safe trial

  1. Check the supported host and the repository installation instructions. Keep the Skill directory and its referenced scripts, assets and documentation together; SKILL.md alone may omit dependencies.
  2. Give the agent your real input, desired output and acceptance criteria. Invocation syntax and available tools depend on the host; this site does not assume a universal install command.
  3. Try the source workflow in a disposable project or on a copy. Review operations that change files, remote services or billable resources before allowing them.
  4. Validate the output against the source quality checks and your own requirements. A successful trigger or a high repository Star count does not establish a correct result.

Skill format and directory specification ↗

Read further in the source

Translation and scope

This reading guide selects passages from the pinned upstream SKILL.md. Translation is assisted. It is not a complete manual or a claim of tested compatibility. Read the original and its referenced files before use.

This introduction refers to the pinned version below; current repository activity and collection time are shown separately.

Source retrieved
Source commit
fabc634a893f62ad5c2039830397efa35fa62715
Source SHA-256
9bd098d81049fc245032ee4f97cf5d9de906d726731ace4a6df0bad6d9dcd182
Back to the full Skill catalog