train-sentence-transformers

sentence-transformers モデルをトレーニングする

この SKILL.md はマニュアルではなく、振り分けのためのファイルです。 タスクに応じて、どのリファレンスとサンプルスクリプトを読み込むべきかを示します。実際の内容（推奨される損失関数、評価器、トレーニングスクリプトの構成、モデルの選定、トレーニング引数の調整項目、トラブルシューティング）は references/ と scripts/ にあります。

このファイルだけをもとにトレーニングスクリプトを作成しないでください。 該当するタイプの本番用テンプレート（scripts/train_<type>_example.py）を開き、それを出発点としてコピーしてください。テンプレートには、重要な土台となるコード（autocast ヘルパー、モデルカードのクラス、ロガーを無効化するリスト、force=True、seed、TF32、バージョン互換性のあるインポート、名前付き評価器のメトリクス処理）が含まれています。エージェントが合成したスニペットから独自に作成した際、これらが繰り返し欠落していました。

1. モデルタイプを特定する

タグ	クラス	機能	選択する場面
[SentenceTransformer]	SentenceTransformer（バイエンコーダー）	各入力を固定次元の密ベクトルに変換します	検索、類似度判定、クラスタリング、分類、言い換えのマイニング、重複排除
[CrossEncoder]	CrossEncoder（リランカー）	(query, passage) のペアをまとめてスコアリングします	2 段階検索（バイエンコーダーの上位 100 件を再ランキング）、ペア分類
[SparseEncoder]	SparseEncoder（SPLADE）	語彙全体にわたるスパースベクトルを生成します	学習型スパース検索、転置インデックスのバックエンド（Elasticsearch / OpenSearch / Lucene）
[MultiVectorEncoder]	MultiVectorEncoder（ColBERT）	トークンごとに 1 つの埋め込みを生成し、MaxSim でスコアリングします	後期インタラクション検索、ストレージコストの増加と引き換えにバイエンコーダーより再現率を高める場合、マルチモーダル（ColPali / ColQwen2）

リクエストが曖昧な場合の判断基準：「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]。それでも不明な場合は、質問してください。

2. 必読資料

コードを書く前に、以下をすべて読んでください。関連性がありそうかどうかで選別しないでください。

タイプ別：常に必須

[SentenceTransformer]

• references/losses_sentence_transformer.md：損失関数とデータ形状の対応、MNRL 系での BatchSamplers.NO_DUPLICATES 要件、Cached* と gradient_checkpointing の非互換性。
• references/evaluators_sentence_transformer.md：評価器とタスクの対応、metric_for_best_model キーの構成方法（名前付き／名前なし）、評価器ごとの primary_metric 値。
• references/model_architectures.md：エンコーダー、デコーダー、静的モデル、Router のパイプライン、プーリングのルール（mean／cls／lasttoken）、新規開始の MLM ベースモデルにおける自動 mean pooling の動作。
• scripts/train_sentence_transformer_example.py：本番用テンプレートです。これを出発点としてコピーしてください。

[CrossEncoder]

• references/losses_cross_encoder.md：ポイントワイズ／ペアワイズ／リストワイズ／蒸留、pos_weight の導出、BCE 以外の損失では activation_fn=Identity() が必須であること（指定しないと評価時のランキングが警告なく崩れます）。
• references/evaluators_cross_encoder.md：CrossEncoderRerankingEvaluator のレシピ、名前付き評価器のキー形式 eval_{name}_{primary_metric}。
• scripts/train_cross_encoder_example.py：本番用テンプレートです。これを出発点としてコピーしてください。

[SparseEncoder]

• references/losses_sparse_encoder.md：SpladeLoss ラッパーの要件、FLOPS 正則化の重み、スモークテストにおける有効次元数の増加動作。
• references/evaluators_sparse_encoder.md：SparseNanoBEIREvaluator（英語のみ）とドメイン内の代替手段、eval_{name}_{primary_metric} キー形式。
• scripts/train_sparse_encoder_example.py：本番用テンプレートです。これを出発点としてコピーしてください。

[MultiVectorEncoder]

• references/losses_multi_vector_encoder.md：MaxSim スコアリング、スコアリング方式ごとのスケール選択（MaxSim では scale=1.0、MeanMaxSim ではクエリの平均長程度）、MNRL／CachedMNRL／MarginMSE／DistillKLDiv、XTR と ColBERT のスコアリングの違い、CachedMNRL と gradient_checkpointing の非互換性。
• references/evaluators_multi_vector_encoder.md：MultiVectorNanoBEIREvaluator（英語のみ）とドメイン内の代替手段、eval_NanoBEIR_mean_maxsim_ndcg@10 キー形式、蒸留評価におけるスピアマン相関のバリアント。
• scripts/train_multi_vector_encoder_example.py：本番用テンプレートです。これを出発点としてコピーしてください。

タスクを問わず常に必要な共通項目

• references/training_args.md：TrainingArguments の設定項目、精度に関するルール（fp32 で読み込み、autocast で bf16/fp16 を使用し、torch_dtype=bfloat16 は使用しない）、warmup_steps（float）と非推奨の warmup_ratio、load_best_model_at_end では save_steps を eval_steps の倍数にする必要があること、スケジューラー、HPO、トラッカー、再開、Hub へのプッシュ方法のバリエーション。
• references/dataset_formats.md：列の照合ルール（ラベル名の自動検出、列名ではなく列の順序を使用）、形状変更のレシピ、ハードネガティブのマイニング方法。
• references/base_model_selection.md：モデルの検索コマンド、タイプ別のモデル名前空間、ModernBERT 系の max_seq_length=8192 に関する落とし穴、datasets >= 4 によるスクリプトローダーの拒否、非英語モデルの開始点を手早く選ぶ方法。
• references/troubleshooting.md：症状別の失敗対処法。問題なく動作している場合も、実行のたびに見出しをざっと確認してください。「メトリクスが改善しない」と「Hub へのプッシュが失敗する」の項目では、頻繁に発生するバグを扱っています。発生後にデバッグするより、事前に把握しておく方が簡単です。

該当する場合に参照する共通項目

• references/hardware_guide.md：VRAM の見積もり、マルチ GPU、FSDP／DeepSpeed、HF Jobs の構成。24GB 超のモデル、マルチ GPU、HF Jobs での実行では必須です。
• references/hf_jobs_execution.md：HF Jobs で実行する場合に必須です。
• references/prompts_and_instructions.md：プロンプトチューニング済みのベースモデル（E5、BGE、GTE、Qwen3-Embedding、Instructor、Nomic など）を使用する場合、または query: ／passage: 形式のプレフィックスを追加する場合に必須です。

バリアントスクリプト（タスクに該当する場合は開きます）

• [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：scripts/mine_hard_negatives.py。

3. デフォルト設定

ユーザーから別の指定がない限り、次の設定を使用します。

• ローカルで実行。 ローカルのハードウェアでジョブを実行できない場合に限り、HF Jobs を提案します。
• 単一の実行。 完了後、ユーザーにとって有益であれば、実験を提案します（判定が弱い／境界的な場合、「どこまで性能を高められるか試してみる」といった表現など）。イテレーションのルールは references/training_args.md（Experimentation セクション）を参照してください。
• 実行終了時に公開 Hub へプッシュし、try-except で囲む。 HF Jobs（エフェメラル環境）では、トレーナー内からのプッシュも有効にします（push_to_hub=True + hub_strategy="every_save"）。詳細は references/hf_jobs_execution.md を参照してください。

4. 生成するスクリプトが満たすべき制約

これらは必須の要件です。実装は本番用テンプレートとリファレンスにあります。独自の実装に置き換えないでください。

• trainer.train() の前に、事前学習時の評価スコアを baseline_eval として取得します。
• 実行終了時に、次の行を1行だけ出力します：VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=...。監視ツールはこの行をスクレイピングします。
• httpx、httpcore、huggingface_hub、urllib3、filelock、fsspec のログレベルを WARNING に設定して出力を抑制します（設定しないと、HF のダウンロード URL がエージェントのコンテキストを埋め尽くします）。
• ログを logs/{RUN_NAME}.log に Tee します。
• 最後に model.push_to_hub(...) を実行し、try/except で囲みます。
• 長時間の実行前にスモークテストを行います（max_steps=1 + 小さなデータセットのスライス）。本番用テンプレートには、一般的なパターンの1つ（SMOKE_TEST 環境変数）が示されています。
• [CrossEncoder] EarlyStoppingCallback(patience>=3) を含めます。CE リランカーはトレーニング途中で性能がピークに達し、その後低下することがよくあります。
• [SparseEncoder] query_active_dims / corpus_active_dims を判定行に記録します。スパース性が崩れた状態で nDCG が高くても、成功とは見なせません。キーには名前のプレフィックスが付いて返されます（例：..._query_active_dims）。サフィックスマッチングを使って値を取り出してください。正確なパターンは SPARSE 本番用テンプレートを参照してください。
• [MultiVectorEncoder] MNRL ファミリーの損失では、スコアリングモードに合わせて scale を設定します。正規化なしの MaxSim ではほぼ 1.0 にします（バイエンコーダー MNRL の scale=20.0 をコピーしないでください）。長さ正規化 MeanMaxSim では、各スコアがクエリのトークン数で割られるため、おおよその平均クエリ長にします。XTRScores はトレーニング専用の similarity_fct です。評価器はこれを受け付けないため、XTR でトレーニングしたモデルも含め、評価では常に MaxSim でスコアを計算します。

5. ワークフロー

1. モデルの種類を特定します（§1）。不明な場合は確認します。
2. その種類に必要な §2 のファイルを読み込みます。
3. scripts/train_<type>_example.py を開き、出発点としてコピーします。
4. MODEL_NAME、DATASET_NAME、RUN_NAME、損失、評価器をユーザーのタスクに合わせて置き換えます。references/losses_<type>.md を参照して、損失とデータ形状の適合性を照合します。references/evaluators_<type>.md を参照して、metric_for_best_model のキーを照合します（名前付き評価器では、キーの形式は eval_{name}_{primary_metric} です）。
5. スモークテストを行います（max_steps=1）。
6. 実行します。
7. 実行後、logs/experiments.md に追記し、判定が弱い／境界的な場合はイテレーションを提案します。

前提条件

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)

GPU を強く推奨します。CPU はデモと [SentenceTransformer] StaticEmbedding に限り動作します。