训练参数SentenceTransformerTrainingArguments、CrossEncoderTrainingArguments和SparseEncoderTrainingArguments都继承自 Hugging Face 的TrainingArguments所以 95% 的参数是相同的。本参考涵盖对嵌入模型训练真正重要的参数。推荐的默认配置以此开头只调整你有理由更改的内容fromsentence_transformersimportSentenceTransformerTrainingArgumentsfromsentence_transformers.base.samplerimportBatchSamplers argsSentenceTransformerTrainingArguments(output_dirmodels/my-model,# 时长num_train_epochs1,# max_steps10_000, # 代替 epochs# 批次大小per_device_train_batch_size64,per_device_eval_batch_size64,gradient_accumulation_steps1,# 优化器learning_rate2e-5,warmup_steps0.1,# transformers v5.2 弃用了 warmup_ratio直接把比例作为浮点数传给 warmup_stepslr_scheduler_typelinear,weight_decay0.0,# 精度bf16True,# 较旧 GPUT4、V100上为 fp16True# 采样器双编码器 稀疏编码器batch_samplerBatchSamplers.NO_DUPLICATES,# 评估 检查点eval_strategysteps,eval_steps0.1,# 分数每个 epoch 10 次评估随数据集大小扩展save_strategysteps,save_steps0.1,# 与 eval_steps 保持一致以使用 load_best_model_at_endsave_total_limit2,load_best_model_at_endTrue,metric_for_best_modeleval_NanoBEIR_mean_cosine_ndcg10,greater_is_betterTrue,# 日志记录logging_steps0.01,# 分数每个 epoch 约 100 行日志logging_first_stepTrue,run_namemy-model,report_totrackio,# 或 wandb、tensorboard、mlflow、none)时长num_train_epochs— 最常见。大数据集50 万为 1小数据集为 3–10。max_steps— 当你想要固定计算预算时用它代替 epochs。覆盖num_train_epochs。对 1 个 epoch 过于浪费的巨大数据集选择与你的计算计划匹配的max_steps。批次大小有效批次大小 per_device_train_batch_size × num_gpus × gradient_accumulation_steps。经验法则对比损失MNRL、GIST、SMNRL在 VRAM 允许的情况下尽量提高per_device_train_batch_size。更大的批内负样本 更好的梯度。典型 64–256。回归损失CoSENTLoss、CosineSimilarityLoss 等批次大小不太重要。16–64 就可以。交叉编码器批次大小对质量不那么关键。典型 32–128。如果无法容纳期望的每设备批次使用gradient_accumulation_steps模拟——但对 MNRL 家族损失这不提供与真实批次相同的收益批内负样本仍然只是每设备的。请改用CachedMultipleNegativesRankingLoss。学习率和调度2e-5是 BERT 家族编码器全量微调的安全默认值。LoRA / PEFT 适配器为1e-4到5e-4。从头训练StaticEmbedding模型为2e-1比 transformers 高得多因为每个 token 都是没有上游梯度的自由浮动向量。lr_scheduler_typelinear配合warmup_steps0.1是标准做法 1的浮点数被解释为总步数的比例。cosine效果同样好constant_with_warmup适合非常短的运行。遗留的warmup_ratio在 transformers v5.2 中被弃用改用接受浮点数的warmup_steps传warmup_ratio...仍然有效但会发出 DeprecationWarning。如果损失变成 NaN首先降低 LR再做其他事。精度不可协商的规则以fp32加载模型默认——不要给模型构造函数或model_kwargs传torch_dtypetorch.bfloat16。使用下面的bf16True/fp16True标志启用autocast而不是权重转换。训练器将模型和优化器状态保持在 fp32并在前向/反向时将激活 autocast 到 bf16/fp16。这保留了 Adam 的全精度矩同时给你大部分 bf16 吞吐量。在优化器创建之前将权重转换为 bf16会把 Adam 状态exp_avg、exp_avg_sq也置于 bf16——bf16 的 7 位尾数对小的梯度矩来说太粗了你会得到跨运行的静默质量回退。标志何时使用bf16TrueAmpereA10G、A100、3090及更新Hopper、Ada。受支持时首选——比 fp16 数值上更稳定。仅激活权重保持 fp32。fp16True较旧 GPUT4、V100、2080、Titan V。如果看到 NaN准备降低 LR 或启用损失缩放。仅激活权重保持 fp32。都不用全程 fp32。慢仅用于调试数值问题。不要同时设置bf16True和fp16True。训练器之外的评估器调用通常是预训练基线 最终训练后一次不会获得训练器的 autocast。手动包裹它们以获得加速——并注意只有当模型使用attn_implementationflash_attention_2时包裹才是严格必需的因为 FA2 内核需要 bf16/fp16 输入才能工作。没有 FA2包裹只是吞吐量优化不是正确性要求importtorchfromcontextlibimportnullcontextdefautocast_ctx():ifnottorch.cuda.is_available():returnnullcontext()dtypetorch.bfloat16iftorch.cuda.is_bf16_supported()elsetorch.float16returntorch.autocast(cuda,dtypedtype)withautocast_ctx():evaluator(model)# baselinetrainer.train()withautocast_ctx():evaluator(model)# post-trainingFlashAttention 2想要 bf16/fp16 输入但不要求 bf16 权重。传model_kwargs{attn_implementation: flash_attention_2}不带torch_dtype让bf16Trueautocast 将 bf16 激活喂给 FA2。权重保持 fp32优化器状态保持 fp32。批次采样器双编码器 稀疏编码器batch_samplerBatchSamplers.NO_DUPLICATES对对比损失至关重要。没有它同一个 (anchor, positive) 可以在一个批次中出现多次把合法的正例变成假负样本。对 MNRL / SMNRL / CachedMNRL / GIST 使用BatchSamplers.NO_DUPLICATES默认推荐对批次三元组损失BatchAllTripletLoss、BatchHardTripletLoss使用BatchSamplers.GROUP_BY_LABEL仅对逐批次字符串比较变慢的超大数据集使用BatchSamplers.NO_DUPLICATES_HASHED。对于多数据集训练类似的MultiDatasetBatchSamplers类控制如何从每个数据集抽取ROUND_ROBIN、PROPORTIONAL。在 DDP 下每个数据集会自动按进程分片——无需额外配置设置一次multi_dataset_batch_sampler...它在 1-GPU 和 N-GPU 运行中行为相同。评估与检查点eval_strategysteps,eval_steps0.1,# 每训练 10% 评估一次save_strategysteps,save_steps0.1,# 以相同节奏保存load_best_model_at_end 需要save_total_limit2,load_best_model_at_endTrue,metric_for_best_modeleval_EvaluatorName_metric,greater_is_betterTrue,优先使用小数值而非绝对步数。eval_steps0.1/save_steps0.1/logging_steps0.01被解释为总训练步数的比例每个 epoch 10 次评估每个 epoch 100 行日志并在数据集大小或 epoch 数变化时自动扩展。HF Trainer 在初始化时将float 1转换为int(total_steps * fraction)所以同样的配置无论你在 10k 还是 10M 行上训练都有效——无需每次重新计算绝对步数。只有在你有一个特定理由时才使用绝对整数例如eval_steps500在已知步数下比较运行或当max_steps设置为使分数变得笨拙的非常规值时。不可协商的规则当load_best_model_at_endTrue时save_steps必须是eval_steps的倍数或相等这样最佳评估检查点确实在磁盘上。让它们匹配是最简单的路径例如都在0.1。如果eval_strategysteps且你不传eval_dataset训练会挂起。要么提供评估数据集要么设置eval_strategyno。metric_for_best_model必须与评估器写入的确切键匹配。模式通常是feval_{evaluator.primary_metric}。常见值NanoBEIREvaluator双编码器余弦eval_NanoBEIR_mean_cosine_ndcg10SparseNanoBEIREvaluator稀疏点积eval_NanoBEIR_mean_dot_ndcg10CrossEncoderNanoBEIREvaluator从 BM25 top-100 重排eval_NanoBEIR_R100_mean_ndcg10EmbeddingSimilarityEvaluator(namests-dev)eval_sts-dev_spearman_cosine早停通过callbacks[...]添加EarlyStoppingCallbackfromtransformersimportEarlyStoppingCallback trainerSentenceTransformerTrainer(...,callbacks[EarlyStoppingCallback(early_stopping_patience3)],)这需要设置load_best_model_at_endTrue和metric_for_best_model...。early_stopping_patience3意味着如果最佳指标在连续 3 轮评估中没有提升就停止。使用early_stopping_threshold0.001要求最小提升。它真正重要的场景交叉编码器强烈推荐。CE 重排器通常训练中途达到峰值然后退化——最佳检查点很少是最后一个。早停既节省计算又防止质量回退。双编码器和稀疏编码器通常会平台期而不是回退所以早停触发频率低得多。仅load_best_model_at_endTrue就给你正确的最终模型添加回调是双保险安全网。恢复训练trainer.train(resume_from_checkpointTrue)从output_dir中最新的检查点恢复。传特定路径以从特定步骤恢复resume_from_checkpointmodels/my-model/checkpoint-500。跨恢复持久化的状态优化器、调度器、随机种子、训练器步数计数器。不持久化的状态IterableDataset的数据集迭代顺序——如果你使用流式数据集必须自己处理恢复。Hub 推送push_to_hubTruehub_model_idyour-username/my-modelhub_strategyevery_save是标准模式。在 HF Jobs 上还要在作业提交时传secrets{HF_TOKEN: $HF_TOKEN}。四种hub_strategy值every_save每个检查点HF Jobs 必须、end仅最终、checkpoint最新覆盖、all_checkpoints每个作为独立提交。日志记录logging_steps0.01,# 分数每个 epoch 约 100 行日志用整数表示固定节奏logging_first_stepTrue,# 在任何训练前记录有用的健全性检查logging_dirNone,# 默认为 output_dir/runsreport_totrackio,# 或 [trackio, tensorboard] 用于多个none 禁用全部run_namemeaningful-name,# 显示在 tracker UI 中Tracker 推荐Trackio默认适合单人 / 小团队工作除了HF_TOKEN之外零摩擦。首次运行会在https://huggingface.co/spaces/your-username/trackio自动创建一个 Space后续运行追加并按run_name分组。WB适合更大的团队或扫描 / 报告功能。pip install wandb wandb login或设置WANDB_API_KEY。TensorBoard适合隔离环境。没有远程仪表板。MLflow当它已是组织标准时使用。对于 trackio 扫描 / 消融在训练前使用trackio.init(project..., name..., groupv1, config{...})将相关运行并排分组。没有trackio.init()默认值从run_name和 HF 用户名派生。Tracker 陷阱report_toall启用每个已安装的集成通常比你想要的多none禁用一切当前transformers默认。始终显式设置。在 HF Jobs 上没有secrets{HF_TOKEN: $HF_TOKEN}的 Trackio 会静默失败。在 HF Jobs 上WB 需要在secrets中提供WANDB_API_KEY。HF Trainer 在 DDP 下只在 rank 0 上记录脚本中的自定义日志可能需要显式 rank 检查以避免重复写入。节省内存的参数gradient_checkpointingTrue,# 用计算换内存。约慢 30%少用约 40% 内存。gradient_checkpointing_kwargs{use_reentrant:False},torch_empty_cache_steps1000,# 定期清除 PyTorch 分配器缓存dataloader_num_workers2,# 并行数据加载2-4 通常足够dataloader_pin_memoryTrue,不要将gradient_checkpointingTrue与任何Cached*损失组合——它们冲突。超参数搜索trainer.hyperparameter_search(...)对三种训练器都受支持通过 Hugging Face 的TrainerAPI后端使用 Optuna、Ray Tune、Sigopt 或 WB。最小示例defmodel_init(trial):returnSentenceTransformer(microsoft/mpnet-base)defhp_space(trial):return{learning_rate:trial.suggest_float(learning_rate,1e-6,1e-4,logTrue),num_train_epochs:trial.suggest_int(num_train_epochs,1,3),per_device_train_batch_size:trial.suggest_categorical(per_device_train_batch_size,[32,64,128]),}trainerSentenceTransformerTrainer(modelNone,model_initmodel_init,argsargs,train_datasettrain_dataset,eval_dataseteval_dataset,losslambdamodel:MultipleNegativesRankingLoss(model),# 接受 model - loss 的函数evaluatorevaluator,)best_runtrainer.hyperparameter_search(hp_spacehp_space,directionmaximize,n_trials10,backendoptuna,)print(best_run)安装一个后端pip install optuna或ray[tune]。HPO 很昂贵。在单个手动调优的运行端到端工作之前不要使用它。对大多数生产模型从上面的范围选择一个合理的 LR 并调优批次大小就够了。多任务训练参数简要在带损失函数字典的数据集字典上训练时添加multi_dataset_batch_samplerMultiDatasetBatchSamplers.PROPORTIONAL,# 或 ROUND_ROBIN参见../scripts/train_sentence_transformer_multi_dataset_example.pydocstring 涵盖每数据集损失、单损失 DatasetDict 变体、采样器、陷阱。不要做不要在没有设置save_strategyepoch的情况下设置eval_strategyepoch——检查点/评估对齐对load_best_model_at_end很重要。不要设置remove_unused_columnsFalse除非你有消费损失函数看不到的元数据列的自定义 collator。默认True更安全——它会自动丢弃未使用的列。不要设置seed来验证可复现性然后期望在不同 GPU 或不同 PyTorch 版本上得到逐位相同的运行——跨硬件的完全可复现性无法保证。不要调优adam_beta1/adam_beta2/adam_epsilon除非你有特定理由。默认值在 99% 的情况下都没问题。