训练 sentence-transformers…

当需要训练或微调句向量/重排/稀疏/多向量检索模型时，按类型选模板、按数据形状选损失、按评估器构造指标键并跑通训练。

适用场景

解决思路

1. 先判断模型类型：'embedding model'/'vector search'/'similarity' 选 SentenceTransformer（双编码器，稠密向量，用于检索、相似度、聚类、分类、释义挖掘、去重）；'rerank'/'ranker'/'two-stage' 选 CrossEncoder（联合打分 query-passage 对，用于两阶段检索重排、对分类）；'SPLADE'/'sparse'/'inverted index' 选 SparseEncoder（词表稀疏向量，用于学习式稀疏检索、倒排索引后端如 Elasticsearch/OpenSearch/Lucene）；'ColBERT'/'late interaction'/'multi-vector'/'MaxSim'/'ColPali'/'ColQwen' 选 MultiVectorEncoder（每 token 一个向量，MaxSim 打分，用于后交互检索、多模态）。仍不明确就问用户。
2. 按类型完整阅读必读参考文件，不要凭相关性筛选：SentenceTransformer 读 losses_sentence_transformer.md（损失与数据形状映射、MNRL 系列需要 BatchSamplers.NO_DUPLICATES、Cached* 与 gradient_checkpointing 不兼容）、evaluators_sentence_transformer.md（评估器与任务映射、metric_for_best_model 键构造、各评估器 primary_metric）、model_architectures.md（编码器/解码器/静态/Router 流水线、池化规则、新起 MLM 基座的自动均值池化）；CrossEncoder 读 losses_cross_encoder.md（pointwise/pairwise/listwise/蒸馏、pos_weight 推导、非 BCE 损失必须 activation_fn=Identity() 否则评估排名静默崩溃）、evaluators_cross_encoder.md（CrossEncoderRerankingEvaluator 配方、命名评估器键格式 eval_{name}_{primary_metric}）；SparseEncoder 读 losses_sparse_encoder.md（必须用 SpladeLoss 包装、FLOPS 正则权重、冒烟测试活跃维度爬升行为）、evaluators_sparse_encoder.md（SparseNanoBEIREvaluator 仅英文及域内替代、eval_{name}_{primary_metric} 键格式）；MultiVectorEncoder 读 losses_multi_vector_encoder.md（MaxSim 打分、按打分模式选 scale、MNRL/CachedMNRL/MarginMSE/DistillKLDiv、XTR 与 ColBERT 打分、CachedMNRL 与 gradient_checkpointing 不兼容）、evaluators_multi_vector_encoder.md（MultiVectorNanoBEIREvaluator 仅英文及域内替代、eval_NanoBEIR_mean_maxsim_ndcg@10 键格式、蒸馏评估 spearman 变体）。
3. 无论何种任务都读跨领域必读文件：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、tracker、恢复、hub 推送变体）、dataset_formats.md（列匹配规则：标签名自动检测、按列顺序而非列名、重塑配方、难负样本挖掘选项）、base_model_selection.md（发现命令、各类型模型命名空间、ModernBERT 家族 max_seq_length=8192 陷阱、datasets >= 4 拒绝脚本加载器、非英文起点捷径）、troubleshooting.md（按症状索引的失败配方，每次运行都扫一遍标题，尤其 'Metrics don't improve' 和 'Hub push fails'）。
4. 按需加载跨领域文件：>24GB 模型、多 GPU 或 HF Jobs 运行必须读 hardware_guide.md（显存估算、多 GPU、FSDP/DeepSpeed、HF Jobs 规格）；在 HF Jobs 上运行必须读 hf_jobs_execution.md；使用 prompt 调优基座（E5、BGE、GTE、Qwen3-Embedding、Instructor、Nomic 等）或添加 query:/passage: 前缀时必须读 prompts_and_instructions.md。
5. 任务匹配时打开变体脚本：SentenceTransformer 的 matryoshka/multi_dataset/with_lora/distillation/make_multilingual/static_embedding 示例；CrossEncoder 的 distillation/listwise 示例；SparseEncoder 的 distillation 示例；难负样本挖掘 CLI 用 scripts/mine_hard_negatives.py。
6. 不要仅凭本文件合成训练脚本。打开对应类型的生产模板 scripts/train_<type>_example.py 并复制作为起点，模板包含关键脚手架（autocast 辅助、模型卡类、日志静默列表、force=True、seed、TF32、版本兼容导入、命名评估器指标处理），这些是此前 agent 自行合成时反复遗漏的。
7. 默认设置（除非用户另有要求）：本地执行，仅当本地硬件放不下才推荐 HF Jobs；单次运行，完成后若用户受益（判定弱/边缘、'看能推到多高'等）再提议实验迭代，迭代规则见 training_args.md 的 Experimentation 节；运行结束推送公共 Hub 并用 try-except 包裹，在 HF Jobs（临时环境）上还要启用训练器内推送（push_to_hub=True + hub_strategy='every_save'），细节见 hf_jobs_execution.md。
8. 产出的脚本必须满足不可协商的契约：在 trainer.train() 之前捕获训练前评估分数为 baseline_eval；输出单行结束行 VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=...（有监控会抓取）；将 httpx、httpcore、huggingface_hub、urllib3、filelock、fsspec 静默到 WARNING（否则 HF 下载 URL 会淹没上下文）；日志 tee 到 logs/{RUN_NAME}.log；结尾用 try/except 包裹 model.push_to_hub(...)；任何长跑前先冒烟测试（max_steps=1 + 小数据集切片，模板展示 SMOKE_TEST 环境变量模式）。
9. CrossEncoder 额外要求：加入 EarlyStoppingCallback(patience>=3)，因为 CE 重排器常在训练中途达到峰值后回退。
10. SparseEncoder 额外要求：在 verdict 行记录 query_active_dims / corpus_active_dims，高 nDCG 但稀疏度塌缩不算赢；键会带名称前缀（如 ..._query_active_dims），用后缀匹配提取，参考 SPARSE 生产模板的精确模式。
11. MultiVectorEncoder 额外要求：任何 MNRL 系列损失的 scale 要与打分模式匹配——非归一化 MaxSim 用接近 1.0（不要照抄双编码器 MNRL 的 scale=20.0），长度归一化 MeanMaxSim 用大约平均 query 长度（每个分数除以该 query 的 token 数）；XTRScores 是仅训练用的 similarity_fct，评估器会拒绝它，所以评估始终用 MaxSim 打分，即使对 XTR 训练的模型也一样。
12. 工作流：1) 识别模型类型，模糊就问；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，若判定弱/边缘则提议迭代。
13. 前置安装：pip install "sentence-transformers[train]>=5.0"（多模态加 [train,image]/[audio]/[video]，MultiVectorEncoder 需要 >=6.0）；pip install trackio（可选 tracker，或 wandb/tensorboard/mlflow）；hf auth login 或设置带写权限的 HF_TOKEN 用于 Hub 推送。强烈建议 GPU，CPU 仅适合演示和 SentenceTransformer 的 StaticEmbedding。

适用边界 · 注意事项

• 任务类型不明确且用户无法澄清时，不要盲目选型或合成脚本，应先询问。
• 不要仅凭 SKILL.md 自行合成训练脚本，必须复制对应类型的生产模板作为起点。
• 不要在未做冒烟测试（max_steps=1 + 小数据集切片）的情况下直接启动长跑。