SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场train-sentence-transformers

train-sentence-transformers

智能体与模型

查看项目

更新于 10-16 11:29

技能介绍

用途

该技能用于训练或微调 sentence-transformers 模型，适用于检索、相似度计算、聚类、分类、重排序及同类任务。它本身是一个路由（router），而非完整操作手册：它告诉你针对当前任务应加载哪些参考文档与示例脚本，真正的推荐损失函数、评估器、训练脚本结构、模型选择、训练参数与故障排查内容都放在 references/ 与 scripts/ 目录中。技能明确要求：不要仅凭该文件自行拼凑训练脚本，而应复制对应类型的生产模板（scripts/train_<type>_example.py）作为起点，因为模板中包含大量关键脚手架（autocast 辅助、model-card 类、日志静默列表、force=True、seed、TF32、版本兼容导入、命名评估器指标处理），这些在以往自行合成的片段中常被遗漏。

模型类型划分

技能将任务分为三类模型：

  • [SentenceTransformer]（双编码器）：将每个输入映射为固定维度稠密向量，适用于检索、相似度、聚类、分类、释义挖掘、去重。
  • [CrossEncoder]（重排序器）：联合对 (query, passage) 对打分，适用于两阶段检索（对双编码器召回的 top-100 重排）、配对分类。
  • [SparseEncoder]（SPLADE）：在词表上生成稀疏向量，适用于学习式稀疏检索、倒排索引后端（Elasticsearch / OpenSearch / Lucene）。

当请求含糊时，按以下规则判断：出现 "embedding model" / "vector search" / "similarity" 选 [SentenceTransformer]；出现 "rerank" / "ranker" / "two-stage" 选 [CrossEncoder]；出现 "SPLADE" / "sparse" / "inverted index" 选 [SparseEncoder]；仍不明确则询问用户。

必读材料

技能要求写代码前完整阅读相关文档，不按主观相关性筛选。

按类型必读：

  • [SentenceTransformer]：references/losses_sentence_transformer.md（损失与数据形态映射、MNRL 家族的 BatchSamplers.NO_DUPLICATES 要求、Cached* 与 gradient_checkpointing 不兼容）、references/evaluators_sentence_transformer.md（评估器与任务映射、metric_for_best_model 键构造）、references/model_architectures.md（编码器/解码器/静态/Router 流水线、池化规则、MLM 基座的自动平均池化行为）、scripts/train_sentence_transformer_example.py。
  • [CrossEncoder]：references/losses_cross_encoder.md（pointwise / pairwise / listwise / 蒸馏、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 仅英文及域内替代、键格式）、scripts/train_sparse_encoder_example.py。

跨类型必读（无论任务）：references/training_args.md（TrainingArguments 参数、精度规则、warmup_steps 与已弃用的 warmup_ratio、save_steps 与 eval_steps 的倍数关系、调度器、HPO、追踪器、恢复、Hub 推送变体）、references/dataset_formats.md（列匹配规则、重塑配方、难负例挖掘选项）、references/base_model_selection.md（发现命令、各类型模型命名空间、ModernBERT 家族 max_seq_length=8192 陷阱、datasets >= 4 的 script-loader 拒绝、非英文起点捷径）、references/troubleshooting.md（按症状索引的故障配方，建议每次运行都浏览标题）。

按需加载：references/hardware_guide.md（显存估算、多 GPU、FSDP / DeepSpeed、HF Jobs），>24GB 模型、多 GPU 或 HF Jobs 运行时必读；references/hf_jobs_execution.md（在 HF Jobs 上运行时必读）；references/prompts_and_instructions.md（使用 prompt 调优基座如 E5、BGE、GTE、Qwen3-Embedding、Instructor、Nomic，或添加 query:/passage: 前缀时必读）。

变体脚本（任务匹配时打开）：[SentenceTransformer] 的 matryoshka / multi_dataset / with_lora / distillation / make_multilingual / static_embedding 示例；[CrossEncoder] 的 distillation / listwise 示例；[SparseEncoder] 的 distillation 示例。难负例挖掘 CLI 为 scripts/mine_hard_negatives.py。

默认行为

除非用户另有指定：默认本地执行（仅当本地硬件无法承载时才推荐 HF Jobs）；默认单次运行，完成后如用户有收益可提议实验（判定为 weak/marginal、"看看能推到多高" 等）；默认运行结束时推送至公开 Hub 并用 try-except 包裹，在 HF Jobs（临时环境）上还应启用训练器内推送（push_to_hub=True + hub_strategy="every_save"）。

脚本必须满足的约束

以下为不可协商的契约，实现已在生产模板与参考文档中，不要自行发明：在 trainer.train() 之前记录训练前评估器分数为 baseline_eval；运行结束时输出单行 VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=...（有监控程序会抓取该行）；将 httpx、httpcore、huggingface_hub、urllib3、filelock、fsspec 日志静默至 WARNING；日志 tee 到 logs/{RUN_NAME}.log；以带 try/except 的 model.push_to_hub(...) 结束；任何长运行前先做冒烟测试（max_steps=1 + 极小数据集切片）；[CrossEncoder] 加入 EarlyStoppingCallback(patience>=3)，因为 CE 重排器常在训练中途达到峰值后回退；[SparseEncoder] 在判定行记录 query_active_dims / corpus_active_dims，稀疏度塌缩下的高 nDCG 不算胜利（键名带回前缀，需后缀匹配提取）。

工作流程

  1. 判断模型类型（含糊则询问）。2. 加载该类型的必读文件。3. 打开并复制 scripts/train_<type>example.py 作为起点。4. 将 MODEL_NAME、DATASET_NAME、RUN_NAME、损失与评估器替换为用户任务，并对照损失文档核对损失与数据形态匹配、对照评估器文档核对 metric_for_best_model 键（命名评估器格式为 eval{name}_{primary_metric}）。5. 冒烟测试（max_steps=1）。6. 正式运行。7. 运行后追加写入 logs/experiments.md，若判定为 weak/marginal 则提议迭代。

前置条件

pip install "sentence-transformers[train]>=5.0"（多模态 [SentenceTransformer] 需加 [train,image] / [audio] / [video]）；pip install trackio（可选追踪器，或 wandb / tensorboard / mlflow）；hf auth login 或设置具有写权限的 HF_TOKEN（用于 Hub 推送）。强烈建议使用 GPU，CPU 仅适用于演示与 [SentenceTransformer] StaticEmbedding。

限制

仅当任务明确匹配其上游产品或 API 范围时使用该技能；在做出更改前，应针对当前官方文档核实命令、API 行为、定价、配额、凭据与部署影响；不要将生成的示例视为环境特定测试、安全审查或对破坏性/高成本操作的用户批准的替代品。