train-sentence-transformers

训练 sentence-transformers 模型

此 SKILL.md 是路由文件，而非手册。 它会告诉你针对当前任务需要加载哪些参考资料和示例脚本。实际内容（推荐的损失函数、评估器、训练脚本结构、模型选择、训练参数选项、故障排查）位于 references/ 和 scripts/ 中。

不要仅凭此文件自行编写训练脚本。 打开对应类型的生产模板（scripts/train_<type>_example.py），并以此为起点复制。模板包含关键支架代码（autocast 辅助函数、模型卡类、日志记录器静默列表、force=True、seed、TF32、兼容不同版本的导入方式、命名评估器的指标处理），以往 Agent 在自行拼凑代码片段时屡次遗漏这些内容。

1. 确定模型类型

标签	类	功能	适用场景
[SentenceTransformer]	SentenceTransformer（双编码器）	将每个输入映射为固定维度的稠密向量	检索、相似度、聚类、分类、释义挖掘、去重
[CrossEncoder]	CrossEncoder（重排序器）	对 (query, passage) 对进行联合评分	两阶段检索（对双编码器检索出的前 100 个结果重排序）、成对分类
[SparseEncoder]	SparseEncoder（SPLADE）	生成词汇表上的稀疏向量	学习式稀疏检索、倒排索引后端（Elasticsearch / OpenSearch / Lucene）
[MultiVectorEncoder]	MultiVectorEncoder（ColBERT）	为每个词元生成一个嵌入，并使用 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 基础模型时的自动均值池化行为。
• 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 评分；不同评分模式对应的 scale 选择（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；蒸馏评估中的 spearman 变体。
• scripts/train_multi_vector_encoder_example.py：生产模板。请复制此文件作为起点。

跨类型：始终必读（无论任务类型）

• references/training_args.md：TrainingArguments 参数、精度规则（以 fp32 加载，并使用 autocast bf16/fp16；切勿设置 torch_dtype=bfloat16）、warmup_steps（浮点数）与已弃用的 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。
• 运行结束时输出一行：VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=...。监控程序会抓取此行。
• 将 httpx、httpcore、huggingface_hub、urllib3、filelock、fsspec 的日志级别设为 WARNING（否则 HF 下载 URL 会大量占用 Agent 的上下文）。
• 使用 Tee 将日志写入 logs/{RUN_NAME}.log。
• 结尾处调用 model.push_to_hub(...)，并使用 try/except 包装。
• 任何长时间运行之前都要先进行冒烟测试（max_steps=1 + 小型数据集切片）。生产模板展示了一种常见模式（SMOKE_TEST 环境变量）。
• [CrossEncoder] 包含 EarlyStoppingCallback(patience>=3)。CE 重排器通常会在训练过程中途达到峰值，之后性能可能回退。
• [SparseEncoder] 在 verdict 行中记录 query_active_dims / corpus_active_dims。稀疏度塌缩时，即使 nDCG 较高也不算胜利。这些键会带有名称前缀返回（例如 ..._query_active_dims）。使用后缀匹配提取。准确模式见 SPARSE 生产模板。
• [MultiVectorEncoder] 对于任何 MNRL 系列损失，scale 必须与评分模式匹配：使用未归一化的 MaxSim 时接近 1.0（不要照搬双编码器 MNRL 中的 scale=20.0）；使用长度归一化的 MeanMaxSim 时，大致设为查询的平均长度，因为每个分数都会除以对应查询的 token 数量。XTRScores 是仅用于训练的 similarity_fct：评估器不接受它，因此评估始终使用 MaxSim 为模型评分，包括使用 XTR 训练的模型。

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；如果 verdict 较弱或勉强达标，则建议迭代。

前置条件

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。