train-sentence-transformers

Par huggingface · skills

Entraîne ou affine des modèles sentence-transformers pour `SentenceTransformer` (bi-encodeur ; modèle d'embedding dense ou statique ; pour la recherche, la similarité, le clustering, la classification, le paraphrase mining, la déduplication, le multimodal), `CrossEncoder` (reranker ; scoring de paires pour la recherche en deux étapes / classification de paires) et `SparseEncoder` (SPLADE, modèle d'embedding sparse ; pour la recherche sparse apprise). Couvre la sélection de la loss, le hard-negative mining, les évaluateurs, la distillation, LoRA, Matryoshka et la publication sur le Hugging Face Hub. À utiliser pour toute tâche d'entraînement sentence-transformers.

npx skills add https://github.com/huggingface/skills --skill train-sentence-transformers

Former un modèle sentence-transformers

Ce SKILL.md est un routeur, pas un manuel. Il te dit quelles références et scripts d'exemple charger pour ta tâche. Le contenu réel — losses recommandées, evaluators, structure du script d'entraînement, sélection de modèle, réglages des training-args, dépannage — se trouve dans references/ et scripts/.

Ne synthétise pas un script d'entraînement à partir de ce fichier seul. Ouvre le template de production par type (scripts/train_<type>_example.py) et copie-le comme point de départ. Les templates contiennent du scaffolding porteur (helper autocast, classe model-card, liste de silencieux pour le logger, force=True, seed, TF32, imports compatibles avec les versions, gestion des métriques d'evaluator nommés) que les exécutions d'agents précédentes ont répétée manquées en créant les leurs à partir d'un snippet synthétisé.

1. Identifier le type de modèle

Tag Classe Ce qu'il fait Quand le choisir
[SentenceTransformer] SentenceTransformer (bi-encoder) Mappe chaque entrée à un vecteur dense de dimension fixe Récupération, similarité, clustering, classification, mining de paraphrase, dédup
[CrossEncoder] CrossEncoder (reranker) Note les paires (query, passage) conjointement Récupération deux étapes (reclassement des top-100 du bi-encoder), classification de paires
[SparseEncoder] SparseEncoder (SPLADE) Vecteurs creux sur le vocabulaire Récupération sparse apprise, backends d'index inversé (Elasticsearch / OpenSearch / Lucene)

Briseurs d'égalité quand la demande est ambiguë : « embedding model » / « vector search » / « similarity » → [SentenceTransformer]. « rerank » / « ranker » / « two-stage » → [CrossEncoder]. « SPLADE » / « sparse » / « inverted index » → [SparseEncoder]. Si encore flou, demande.

2. Lectures obligatoires

Lis ces documents en intégralité avant d'écrire du code. Ne trie pas par pertinence perçue.

Par type — toujours obligatoire

[SentenceTransformer]

  • references/losses_sentence_transformer.md — mapping loss-vers-forme-données ; requirement BatchSamplers.NO_DUPLICATES pour la famille MNRL ; incompatibilité Cached* ↔ gradient_checkpointing.
  • references/evaluators_sentence_transformer.md — mapping evaluator-vers-tâche ; construction de clé metric_for_best_model (named vs unnamed) ; valeurs primary_metric par evaluator.
  • references/model_architectures.md — pipelines encoder vs decoder vs static vs Router ; règles de pooling (mean / cls / lasttoken) ; comportement d'auto-mean-pooling pour les bases MLM de démarrage frais.
  • scripts/train_sentence_transformer_example.py — template de production ; copie ceci comme point de départ.

[CrossEncoder]

  • references/losses_cross_encoder.md — pointwise / pairwise / listwise / distillation ; dérivation pos_weight ; activation_fn=Identity() obligatoire pour les non-BCE losses (sinon effondrement silencieux du classement en eval).
  • references/evaluators_cross_encoder.md — recette CrossEncoderRerankingEvaluator ; format de clé d'evaluator nommé eval_{name}_{primary_metric}.
  • scripts/train_cross_encoder_example.py — template de production ; copie ceci comme point de départ.

[SparseEncoder]

  • references/losses_sparse_encoder.md — requirement du wrapper SpladeLoss ; poids du regularizer FLOPS ; comportement de smoke-test de la rampe active-dim.
  • references/evaluators_sparse_encoder.md — SparseNanoBEIREvaluator (anglais uniquement) et l'alternative dans le domaine ; format de clé eval_{name}_{primary_metric}.
  • scripts/train_sparse_encoder_example.py — template de production ; copie ceci comme point de départ.

Cross-cutting — toujours obligatoire (indépendamment de la tâche)

  • references/training_args.md — knobs TrainingArguments, règles de précision (charger fp32 + autocast bf16/fp16 ; jamais torch_dtype=bfloat16), warmup_steps (float) vs deprecated warmup_ratio, save_steps doit être un multiple de eval_steps pour load_best_model_at_end, schedulers, HPO, tracker, resume, variantes hub-push.
  • references/dataset_formats.md — règles de correspondance de colonnes (auto-détection du nom de label ; colonne-non-ordre-ni-nom) ; recettes de reshaping ; options de hard-negative mining.
  • references/base_model_selection.md — commandes de découverte ; namespaces de modèles par type ; piège max_seq_length=8192 pour la famille ModernBERT ; rejet du script-loader datasets >= 4 ; raccourcis de point de départ non-anglais.
  • references/troubleshooting.md — recettes d'échec indexées par symptôme. Survole les en-têtes de section à chaque exécution, même une saine ; les entrées « Les métriques ne s'améliorent pas » et « Hub push échoue » couvrent les bugs qui frappent fréquemment et sont moins coûteux à reconnaître avant qu'ils ne se produisent que de déboguer après.

Cross-cutting — charge quand applicable

  • references/hardware_guide.md — dimensionnement VRAM, multi-GPU, FSDP / DeepSpeed, saveurs HF Jobs. Obligatoire pour les modèles >24GB, multi-GPU, ou exécutions HF Jobs.
  • references/hf_jobs_execution.md — obligatoire lors de l'exécution sur HF Jobs.
  • references/prompts_and_instructions.md — obligatoire lors de l'utilisation de bases prompt-tuned (E5, BGE, GTE, Qwen3-Embedding, Instructor, Nomic, etc.) ou ajout de préfixes de style query: / passage:.

Scripts variantes (ouvre quand la tâche correspond)

  • [SentenceTransformer] scripts/train_sentence_transformer_<matryoshka|multi_dataset|with_lora|distillation|make_multilingual|static_embedding>_example.py.
  • [CrossEncoder] scripts/train_cross_encoder_<distillation|listwise>_example.py.
  • [SparseEncoder] scripts/train_sparse_encoder_distillation_example.py.
  • CLI hard-negative mining — scripts/mine_hard_negatives.py.

3. Défauts

Remplace seulement si l'utilisateur le spécifie autrement :

  • Exécution locale. Propose HF Jobs seulement si le matériel local ne peut pas tenir la tâche.
  • Exécution unique. Après son achèvement, propose l'expérimentation si l'utilisateur en bénéficierait (verdict faible/marginal, framing « vois jusqu'où tu peux la pousser », etc.). Règles d'itération dans references/training_args.md (section Experimentation).
  • Public Hub push à fin d'exécution, enveloppé dans try-except. Sur HF Jobs (env éphémère) ACTIVE AUSSI le push en-trainer (push_to_hub=True + hub_strategy="every_save") ; détails dans references/hf_jobs_execution.md.

4. Contraintes que le script produit doit satisfaire

Ce sont des contrats non-négociables. L'implémentation vit dans les templates de production et les références — ne réinvente pas.

  • Capture le score de l'evaluator de pré-entraînement comme baseline_eval avant trainer.train().
  • Émets une seule ligne de fin d'exécution : VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=.... Un moniteur la scrape.
  • Silence httpx, httpcore, huggingface_hub, urllib3, filelock, fsspec à WARNING (sinon les URLs HF de téléchargement inondent le contexte de l'agent).
  • Tee logs vers logs/{RUN_NAME}.log.
  • Termine avec model.push_to_hub(...) enveloppé dans try/except.
  • Smoke-test avant toute longue exécution (max_steps=1 + tiny dataset slice). Les templates de production montrent un motif courant (SMOKE_TEST env var).
  • [CrossEncoder] Inclus EarlyStoppingCallback(patience>=3) — les CE rerankers culminent souvent en milieu d'entraînement et régressent.
  • [SparseEncoder] Log query_active_dims / corpus_active_dims sur la ligne verdict ; nDCG élevé avec sparsité effondrée n'est pas une victoire. Les clés reviennent avec préfixe de nom (p. ex. ..._query_active_dims) ; utilise la correspondance de suffixe pour les extraire — voir le template SPARSE de production pour le motif exact.

5. Flux de travail

  1. Identifier le type de modèle (§1). Demande s'il est ambigu.
  2. Charge les fichiers de lecture obligatoire du §2 pour ce type.
  3. Ouvre scripts/train_<type>_example.py et copie-le comme point de départ.
  4. Remplace MODEL_NAME, DATASET_NAME, RUN_NAME, la loss, et l'evaluator par la tâche de l'utilisateur. Croise la correspondance loss/forme-données contre references/losses_<type>.md ; croise la clé metric_for_best_model contre references/evaluators_<type>.md (les evaluators nommés formatent la clé comme eval_{name}_{primary_metric}).
  5. Smoke-test (max_steps=1).
  6. Exécute.
  7. Après l'exécution, ajoute à logs/experiments.md et propose l'itération si le verdict est faible/marginal.

Prérequis

pip install "sentence-transformers[train]>=5.0"        # ajoute [train,image] / [audio] / [video] pour [SentenceTransformer] multimodal
pip install trackio                                    # tracker optionnel ; ou wandb / tensorboard / mlflow
hf auth login                                          # ou définis HF_TOKEN avec scope write (pour le Hub push)

GPU fortement recommandé. CPU fonctionne seulement pour les démos et [SentenceTransformer] StaticEmbedding.

Skills similaires

eval-bootstrap
datadog-labs / agent-skills

Générer du code d'évaluation Python à partir de traces de production LLM Datadog.

107
huggingface-llm-trainer
huggingface / skills

Entraîner des modèles de langage avec TRL sur l'infrastructure cloud Hugging Face Jobs.

10 482
ad-model-onboard
nvidia / skills

Automatiser l'intégration de modèles HuggingFace dans AutoDeploy avec tests et rapport.

85
arize-evaluator
github / awesome-copilot

Concevoir et exécuter des évaluateurs LLM-as-judge sur la plateforme Arize.

32 867
huggingface-vision-trainer
huggingface / skills

Entraîner des modèles de vision (détection, classification, segmentation) sur GPU cloud Hugging Face.

10 482