人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载本文以 docs/package_reference/multi_vector_encoder/training_args.md 为核心完整讲解MultiVectorEncoderTrainingArguments的字段体系与使用姿势。它面向 ColBERT 风格多向量late-interaction模型的训练是MultiVectorEncoderTrainer的默认参数类。读完本文你将掌握max_length的两种传参形式与 query/document 任务分配机制、与query_expansion的相互作用以及从BaseTrainingArguments与 TransformersTrainingArguments继承而来的全部关键训练选项并能在 MS MARCO 知识蒸馏、MIRIAD 对比学习等真实训练脚本中直接落地配置。一、它是什么一条参数类串起整个多向量训练sentence-transformers的多向量编码器MultiVectorEncoder与常见的单向量SentenceTransformer不同它对每个输入产出逐 token 的向量序列打分时使用 MaxSim 晚期交互算子——对每个查询 token 取与文档 token 的最大相似度再在查询 token 上求和。这种架构ColBERT 风格在召回与重排任务上表现突出但训练时的 token 长度控制、query/document 前缀路由、批量采样等都与单向量模型差异显著。MultiVectorEncoderTrainingArguments正是为此而生的训练参数类定义于 sentence_transformers/multi_vector_encoder/training_args.py通过 docs/package_reference/multi_vector_encoder/training_args.md 的 autodoc 暴露为公开 API。它的继承链为transformers.TrainingArguments └── sentence_transformers.base.training_args.BaseTrainingArguments └── MultiVectorEncoderTrainingArgumentsTransformersTrainingArguments提供output_dir、learning_rate、per_device_train_batch_size、gradient_accumulation_steps、fp16/bf16、eval_strategy、save_strategy等通用训练参数BaseTrainingArgumentssentence_transformers/base/training_args.py叠加 ST 特有的prompts、router_mapping、learning_rate_mapping、batch_sampler、multi_dataset_batch_sampler等参数MultiVectorEncoderTrainingArguments在_VALID_DICT_FIELDS中追加max_length并新增唯一专属字段max_length——一个控制训练期 token 截断长度的参数。配套使用的MultiVectorEncoderTrainer见 sentence_transformers/multi_vector_encoder/trainer.py通过training_args_class MultiVectorEncoderTrainingArguments将二者绑定并在未显式传loss时默认使用MultiVectorMultipleNegativesRankingLoss。二、核心专属字段max_lengthmax_length是MultiVectorEncoderTrainingArguments相对基类新增的唯一字段默认值为None。它的语义精确定义在类 docstring 中值得逐句拆解。2.1 它只作用于训练不改变模型自身配置Maximum token length applied when tokenizing training and evaluation-loss batches, without changing the models own configuration: evaluators, inference, and the saved model keep the lengths configured on the model (set those via processor_kwargs globally or processing_kwargs per call).关键结论该长度只施加于训练批次与评估损失evaluation-loss批次的 tokenize 过程评估器evaluators、推理inference、保存的模型仍然使用模型自身的长度配置若要修改模型自身的长度应通过模型加载时的processor_kwargs全局或单次调用时的processing_kwargs设置而不是训练参数。这一设计的价值在于训练可以用更短的长度上限以换取速度与显存而推理与导出模型保持完整能力。docstring 明确指出Tight training caps can be much faster and measurably stronger than uncapped training紧凑的训练长度上限往往比不设上限更快、效果可测地更强并指向多向量 MS MARCO 知识蒸馏示例。2.2 两种传参格式int对所有列统一施加同一最大长度。例如max_length180。Dict[str, int]按任务task分别指定例如{query: 32, document: 180}。此时任务分配规则为数据整理器data collator默认将第 0 列赋予query任务其余列赋予document任务router_mapping参数可以按列名覆盖这一默认分配。该默认分配逻辑在 sentence_transformers/multi_vector_encoder/data_collator.py 的_get_task_for_column中有直接实现def _get_task_for_column(self, column_name: str, column_position: int, router_mapping: dict[str, str]) - str: task router_mapping.get(column_name) if task is None: task query if column_position 0 else document return task注意分配只看列位置position不看列名column names are not consulted这与多向量损失函数的位置化约定column 0 query保持一致。需要按列名定制时用router_mapping覆盖。2.3 与 query_expansion 的相互作用这是多向量模型特有的重要细节当模型配置了固定宽度的query_expansionstrategyfixed时查询query会忽略max_length的覆盖——因为扩展长度已经固定了查询的宽度当strategymin时max_length作为上限ceiling生效但永远不会低于扩展长度。也就是说max_length不会把查询截得比 query expansion 的下限还短。这一约束与底层Transformer模块中query_expansion的校验逻辑呼应见 sentence_transformers/base/modules/transformer.py其中校验了query_length不得小于query_expansion[length]以及固定扩展长度下查询不可再截短的语义。2.4 源码中的实现方式在 sentence_transformers/multi_vector_encoder/training_args.py 中_VALID_DICT_FIELDS [*BaseTrainingArguments._VALID_DICT_FIELDS, max_length] max_length: Union[int, None, dict[str, int]] field( defaultNone, metadata{ help: Maximum token length for training and evaluation-loss tokenization. Either 1) an int applied to every column, or 2) a mapping of tasks (query, document) to lengths. Evaluators, inference, and the saved model keep the models own configuration. }, )将max_length注册进_VALID_DICT_FIELDS意味着当通过命令行或字符串传参时该字段会被当作可 JSON 解析的 dict 处理详见下文第五节。三、继承自 BaseTrainingArguments 的 ST 特有参数BaseTrainingArguments在 TransformersTrainingArguments之上新增了以下 ST 专属参数多向量训练中同样全部可用。3.1 prompts为各列指定提示前缀用于为训练、评估、测试数据集的每一列指定 prompt支持四种格式格式说明str单个 prompt应用于所有列Dict[str, str]列名 → prompt 的映射Dict[str, str]数据集维度数据集名 → prompt仅当数据集为DatasetDict或 dict 时Dict[str, Dict[str, str]]数据集名 → (列名 → prompt)对 ColBERT 风格模型典型用法是{query: [Q] , document: [D] }或模型实际使用的前缀 token。需要说明如果传入了纯字符串且无法解析为 JSON__post_init__会把它当作作用于所有列的单个 prompt见 sentence_transformers/base/training_args.py 的__post_init__逻辑。3.2 router_mapping列 → Router 路由A mapping of dataset column names to Router routes, like query or document.两种格式Dict[str, str]列名 → 路由如{query: query, passage: document}Dict[str, Dict[str, str]]数据集名 → (列名 → 路由)用于多数据集训练/评估。它决定了每个数据集列由哪个 Router 子模块处理同时覆盖 data collator 的默认任务分配默认第 0 列为 query、其余为 document。3.3 learning_rate_mapping分模块学习率A mapping of parameter name regular expressions to learning rates.允许对模型不同部分设置不同学习率例如{SparseStaticEmbedding\.*: 1e-3}。适用于只想以不同速率微调模型特定子模块如投影层、特定 Embedding 层的场景。3.4 batch_sampler 与 multi_dataset_batch_samplerbatch_sampler默认BatchSamplers.BATCH_SAMPLER可选值见sentence_transformers.base.sampler.BatchSamplers。多向量对比学习训练中常使用BatchSamplers.NO_DUPLICATES见下文 MIRIAD 示例来降低批内重复文档multi_dataset_batch_sampler默认MultiDatasetBatchSamplers.PROPORTIONAL控制多数据集训练时的按比例采样。两者都支持传入字符串枚举值构造时自动转换或自定义可调用对象to_dict()时会剔除可调用对象以便序列化。3.5 warmup 兼容逻辑BaseTrainingArguments显式定义了warmup_ratio并实现了跨 Transformers 版本的兼容Transformers v5warmup_ratio已废弃使用warmup_steps可传 float 表示比例Transformers v4支持warmup_ratio与整数warmup_steps若向warmup_steps传入(0, 1)区间的 float会将其自动转换为warmup_ratio。这正是仓库示例中warmup_steps0.05Warm up over the first 5% of training steps这一写法的来源。四、其他在__post_init__中被自动修正的行为BaseTrainingArguments.__post_init__中还有几个值得了解的训练行为sentence_transformers/base/training_args.pyprediction_loss_only TrueSentenceTransformerTrainer.compute_loss被重写为只计算预测损失因此显式设置以避免额外计算ddp_broadcast_buffers False避免基于 BertModel 的模型在 DDP 训练时触发 inplace 操作导致的RuntimeError非分布式模式下提示 DataParallelDP慢于 DistributedDataParallelDDPDDP 模式下若未设置dataloader_drop_last会自动置为True以避免不均匀末批次的挂起问题当dataloader_num_workers 0且工作进程通过spawn启动时提示设置dataloader_persistent_workersTrue否则每个 worker 都要重新 import sentence-transformers耗时数秒反而比dataloader_num_workers0更慢。五、dict 字段的字符串解析机制_VALID_DICT_FIELDS追踪所有允许以字符串形式传入 dict的字段目前包括accelerator_config, fsdp_config, deepspeed, gradient_checkpointing_kwargs, lr_scheduler_kwargs, learning_rate_mapping, prompts, router_mappingMultiVectorEncoderTrainingArguments追加了max_length。在__post_init__中learning_rate_mapping与router_mapping若为字符串则尝试json.loads解析失败会抛出明确的ValueError而prompts解析失败时会被宽容地当作单 prompt 字符串。这意味着这些参数既可以在 Python 中以 dict 传入也可以从命令行以 JSON 字符串传入。六、实战一MS MARCO 知识蒸馏训练max_length180仓库中的 examples/multi_vector_encoder/training/msmarco/training_kd.py 是一个完整可运行的 ColBERT 蒸馏训练脚本。其核心配置如下args MultiVectorEncoderTrainingArguments( # Required parameter: output_dirfmodels/{run_name}, # Optional training parameters: num_train_epochsnum_epochs, per_device_train_batch_sizetrain_batch_size, gradient_accumulation_stepsgradient_accumulation_steps, per_device_eval_batch_sizetrain_batch_size, learning_ratelearning_rate, max_length180, # Cap training tokenization at 180 tokens, the query width floor stays 32 via the expansion warmup_steps0.05, # Warm up over the first 5% of training steps fp16False, # Set to False if you get an error that your GPU cant run on FP16 bf16True, # Set to True if you have a GPU that supports BF16 load_best_model_at_endTrue, metric_for_best_modeleval_NanoBEIR_mean_maxsim_ndcg10, # Optional tracking/debugging parameters: eval_strategysteps, # The NanoBEIR evaluator runs on its own datasets, so no eval_dataset is needed eval_steps0.1, save_strategysteps, save_steps0.1, save_total_limit2, logging_steps0.01, run_namerun_name, # Will be used in WB if wandb is installed seed42, )要点解读训练集为(query_id, document_ids, scores)的知识蒸馏格式通过resolve_ids将 ID 实时解析为文本max_list_length32控制每个 query 的负例文档数损失为MultiVectorDistillKLDivLoss(modelmodel, temperature0.25)——教师分数分布经温度锐化后与学生分数分布做 KL 散度评估器MultiVectorNanoBEIREvaluator自行加载 NanoBEIR 数据集因此eval_strategysteps时无需eval_datasetmax_length180的意义训练 tokenize 被截断到 180 token而查询宽度下限32由 query expansion 兜底模型推理/保存仍保持自身完整长度配置metric_for_best_modeleval_NanoBEIR_mean_maxsim_ndcg10表明该模型以MeanMaxSim长度归一化的 MaxSim作为评估指标训练期打分与评估口径保持一致混合精度bf16True、fp16False需 GPU 支持 BF16。七、实战二MIRIAD 医疗问答对比学习max_length1024examples/multi_vector_encoder/training/miriad/training_contrastive.py 展示了从零构建 ColBERT 模块序列并训练的场景。其参数配置args MultiVectorEncoderTrainingArguments( output_dirfmodels/{run_name}, num_train_epochsnum_epochs, per_device_train_batch_sizetrain_batch_size, per_device_eval_batch_size8, learning_ratelearning_rate, max_length1024, # Cap training tokenization: passages average ~940 tokens, the model serves 8192 warmup_steps0.05, fp16False, bf16True, batch_samplerBatchSamplers.NO_DUPLICATES, load_best_model_at_endTrue, metric_for_best_modeleval_miriad_eval_maxsim_ndcg10, eval_strategysteps, eval_steps0.1, save_strategysteps, save_steps0.1, save_total_limit2, logging_steps0.005, run_namerun_name, seed42, )要点解读模型由Transformer Dense(128) MultiVectorMask(skiplist_wordspunctuation) Normalize四个模块顺序组成可通过MultiVectorEncoder(modules[...])从零构建详见 sentence_transformers/multi_vector_encoder/model.py 的_load_default_modules与示例脚本中的构造方式损失为CachedMultiVectorMultipleNegativesRankingLoss(modelmodel, mini_batch_sizemini_batch_size)——缓存式大 batch InfoNCE 目标max_length1024的典型场景MIRIAD 段落平均约 940 token训练截断到 1024 即可覆盖绝大多数样本而模型在推理时支持 8192 token即文档注释the model serves 8192。训练与推理长度解耦正是max_length的设计意图batch_samplerBatchSamplers.NO_DUPLICATES避免同一批次内出现重复文档提升对比学习质量训练中评估用 1000 条 query 的子采样build_ir_evaluator(..., max_queries1000)最终用完整 NanoBEIR 测试集评估。八、常见的完整训练流程闭环综合两个实战脚本一个标准的多向量训练流程为构建/加载模型MultiVectorEncoder(lightonai/LateOn)或MultiVectorEncoder(modules[...])从零构建投影层随机初始化时会有日志提示 Training is required before this model is useful准备数据标准 pair / triplet / multi-negative 格式或(query, document_1, ..., document_N, scores)的蒸馏格式配合resolve_ids实时解析选择损失不传时默认MultiVectorMultipleNegativesRankingLoss蒸馏用MultiVectorDistillKLDivLoss、margin-MSE 用MultiVectorMarginMSELoss大 batch 用缓存式损失可传loss或按数据集名分发的 dict定义评估器如MultiVectorNanoBEIREvaluator、MultiVectorInformationRetrievalEvaluator等见 docs/package_reference/multi_vector_encoder/evaluation.md可先跑一次基线配置MultiVectorEncoderTrainingArguments重点调好max_length考虑 query_expansion 的固定宽度下限、metric_for_best_model与模型similarity_fn_name保持一致maxsim或meanmaxsim、batch sampler 与混合精度训练并保存MultiVectorEncoderTrainer(model..., args..., train_dataset..., loss..., evaluator...)→trainer.train()→model.save_pretrained()或model.push_to_hub()。九、关键设计要点速查关注点结论依据max_length作用域仅训练与 evaluation-loss 批次评估器/推理/保存模型不受影响training_args.py docstringmax_lengthint所有列统一长度同上max_lengthdict按query/document任务区分第 0 列默认 query其余 documentdata_collator.py_get_task_for_column任务覆盖用router_mapping按列名覆盖默认分配同上 base/training_args.pyquery_expansionfixed查询忽略max_length宽度由扩展长度固定training_args.py docstringquery_expansionminmax_length为上限且不低于扩展长度training_args.py docstring默认损失MultiVectorMultipleNegativesRankingLosstrainer.pyget_default_loss推理长度配置走模型自身的processor_kwargs/processing_kwargstraining_args.py docstringdict 字段字符串解析_VALID_DICT_FIELDS中的字段支持 JSON 字符串max_length已追加training_args.py__post_init__十、适用前提与注意事项本文描述的行为以当前仓库代码为准MultiVectorEncoderTrainingArguments是 2025 年后引入的新 API若你使用的旧版本 sbert 中不存在MultiVectorEncoder或该参数类请先升级到包含sentence_transformers/multi_vector_encoder/包的最新版本max_length的收益依赖模型本身支持的长序列能力与训练数据分布文档与示例均强调紧凑上限可能更快且更强但具体数值180、1024应依据你自己的语料 token 分布决定混合精度fp16/bf16需硬件支持warmup_steps传 float 比例的写法依赖BaseTrainingArguments的 Transformers v4/v5 兼容逻辑训练长度与推理长度解耦的前提是训练数据被截断后仍保留足够语义——对于超长文档的领域过小的max_length会让模型看不见关键内容建议先统计语料 token 分布再定值。十一、继续深入阅读参数类实现sentence_transformers/multi_vector_encoder/training_args.py、sentence_transformers/base/training_args.py配套 Trainersentence_transformers/multi_vector_encoder/trainer.py默认损失、模型卡回调、混合精度、多 GPU任务分配实现sentence_transformers/multi_vector_encoder/data_collator.py模型与推理侧长度配置sentence_transformers/multi_vector_encoder/model.py、sentence_transformers/base/modules/transformer.pyquery_length、document_length、query_expansion完整可运行示例examples/multi_vector_encoder/training/msmarco/training_kd.py、examples/multi_vector_encoder/training/miriad/training_contrastive.py相关 API 参考docs/package_reference/multi_vector_encoder/trainer.md、docs/package_reference/multi_vector_encoder/model.md、docs/package_reference/multi_vector_encoder/losses.md赞分享人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载相关推荐PaddleOCR多卡训练参数配置详解PaddleOCR多卡训练参数配置详解 在使用PaddleOCR进行深度学习模型训练时很多开发者会遇到多GPU训练配置的问题。特别是在使用分布式训练时参数的人工智能计算机视觉OCR深度学习大模型RAG《sentence-transformers模型的参数设置详解》《sentence transformers模型的参数设置详解》 引言 在自然语言处理NLP领域模型参数设置的重要性不言而喻。参数的选择和调整直接影响模型Argilla 向量数据实战VectorSettings 配置、向量写入与 Sentence Transformers 语义嵌入Argilla 向量数据实战VectorSettings 配置、向量写入与 Sentence Transformers 语义嵌入 Argilla 是面向 AI数据标注人工智能NLPMLOpsRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/20 10:10:33 · 阅读 1.2k sentence-transformers 多向量编码器训练参数详解：MultiVectorEncoderTrainingArguments 配置指南
人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载本文以 docs/package_reference/multi_vector_encoder/training_args.md 为核心完整讲解MultiVectorEncoderTrainingArguments的字段体系与使用姿势。它面向 ColBERT 风格多向量late-interaction模型的训练是MultiVectorEncoderTrainer的默认参数类。读完本文你将掌握max_length的两种传参形式与 query/document 任务分配机制、与query_expansion的相互作用以及从BaseTrainingArguments与 TransformersTrainingArguments继承而来的全部关键训练选项并能在 MS MARCO 知识蒸馏、MIRIAD 对比学习等真实训练脚本中直接落地配置。一、它是什么一条参数类串起整个多向量训练sentence-transformers的多向量编码器MultiVectorEncoder与常见的单向量SentenceTransformer不同它对每个输入产出逐 token 的向量序列打分时使用 MaxSim 晚期交互算子——对每个查询 token 取与文档 token 的最大相似度再在查询 token 上求和。这种架构ColBERT 风格在召回与重排任务上表现突出但训练时的 token 长度控制、query/document 前缀路由、批量采样等都与单向量模型差异显著。MultiVectorEncoderTrainingArguments正是为此而生的训练参数类定义于 sentence_transformers/multi_vector_encoder/training_args.py通过 docs/package_reference/multi_vector_encoder/training_args.md 的 autodoc 暴露为公开 API。它的继承链为transformers.TrainingArguments └── sentence_transformers.base.training_args.BaseTrainingArguments └── MultiVectorEncoderTrainingArgumentsTransformersTrainingArguments提供output_dir、learning_rate、per_device_train_batch_size、gradient_accumulation_steps、fp16/bf16、eval_strategy、save_strategy等通用训练参数BaseTrainingArgumentssentence_transformers/base/training_args.py叠加 ST 特有的prompts、router_mapping、learning_rate_mapping、batch_sampler、multi_dataset_batch_sampler等参数MultiVectorEncoderTrainingArguments在_VALID_DICT_FIELDS中追加max_length并新增唯一专属字段max_length——一个控制训练期 token 截断长度的参数。配套使用的MultiVectorEncoderTrainer见 sentence_transformers/multi_vector_encoder/trainer.py通过training_args_class MultiVectorEncoderTrainingArguments将二者绑定并在未显式传loss时默认使用MultiVectorMultipleNegativesRankingLoss。二、核心专属字段max_lengthmax_length是MultiVectorEncoderTrainingArguments相对基类新增的唯一字段默认值为None。它的语义精确定义在类 docstring 中值得逐句拆解。2.1 它只作用于训练不改变模型自身配置Maximum token length applied when tokenizing training and evaluation-loss batches, without changing the models own configuration: evaluators, inference, and the saved model keep the lengths configured on the model (set those via processor_kwargs globally or processing_kwargs per call).关键结论该长度只施加于训练批次与评估损失evaluation-loss批次的 tokenize 过程评估器evaluators、推理inference、保存的模型仍然使用模型自身的长度配置若要修改模型自身的长度应通过模型加载时的processor_kwargs全局或单次调用时的processing_kwargs设置而不是训练参数。这一设计的价值在于训练可以用更短的长度上限以换取速度与显存而推理与导出模型保持完整能力。docstring 明确指出Tight training caps can be much faster and measurably stronger than uncapped training紧凑的训练长度上限往往比不设上限更快、效果可测地更强并指向多向量 MS MARCO 知识蒸馏示例。2.2 两种传参格式int对所有列统一施加同一最大长度。例如max_length180。Dict[str, int]按任务task分别指定例如{query: 32, document: 180}。此时任务分配规则为数据整理器data collator默认将第 0 列赋予query任务其余列赋予document任务router_mapping参数可以按列名覆盖这一默认分配。该默认分配逻辑在 sentence_transformers/multi_vector_encoder/data_collator.py 的_get_task_for_column中有直接实现def _get_task_for_column(self, column_name: str, column_position: int, router_mapping: dict[str, str]) - str: task router_mapping.get(column_name) if task is None: task query if column_position 0 else document return task注意分配只看列位置position不看列名column names are not consulted这与多向量损失函数的位置化约定column 0 query保持一致。需要按列名定制时用router_mapping覆盖。2.3 与 query_expansion 的相互作用这是多向量模型特有的重要细节当模型配置了固定宽度的query_expansionstrategyfixed时查询query会忽略max_length的覆盖——因为扩展长度已经固定了查询的宽度当strategymin时max_length作为上限ceiling生效但永远不会低于扩展长度。也就是说max_length不会把查询截得比 query expansion 的下限还短。这一约束与底层Transformer模块中query_expansion的校验逻辑呼应见 sentence_transformers/base/modules/transformer.py其中校验了query_length不得小于query_expansion[length]以及固定扩展长度下查询不可再截短的语义。2.4 源码中的实现方式在 sentence_transformers/multi_vector_encoder/training_args.py 中_VALID_DICT_FIELDS [*BaseTrainingArguments._VALID_DICT_FIELDS, max_length] max_length: Union[int, None, dict[str, int]] field( defaultNone, metadata{ help: Maximum token length for training and evaluation-loss tokenization. Either 1) an int applied to every column, or 2) a mapping of tasks (query, document) to lengths. Evaluators, inference, and the saved model keep the models own configuration. }, )将max_length注册进_VALID_DICT_FIELDS意味着当通过命令行或字符串传参时该字段会被当作可 JSON 解析的 dict 处理详见下文第五节。三、继承自 BaseTrainingArguments 的 ST 特有参数BaseTrainingArguments在 TransformersTrainingArguments之上新增了以下 ST 专属参数多向量训练中同样全部可用。3.1 prompts为各列指定提示前缀用于为训练、评估、测试数据集的每一列指定 prompt支持四种格式格式说明str单个 prompt应用于所有列Dict[str, str]列名 → prompt 的映射Dict[str, str]数据集维度数据集名 → prompt仅当数据集为DatasetDict或 dict 时Dict[str, Dict[str, str]]数据集名 → (列名 → prompt)对 ColBERT 风格模型典型用法是{query: [Q] , document: [D] }或模型实际使用的前缀 token。需要说明如果传入了纯字符串且无法解析为 JSON__post_init__会把它当作作用于所有列的单个 prompt见 sentence_transformers/base/training_args.py 的__post_init__逻辑。3.2 router_mapping列 → Router 路由A mapping of dataset column names to Router routes, like query or document.两种格式Dict[str, str]列名 → 路由如{query: query, passage: document}Dict[str, Dict[str, str]]数据集名 → (列名 → 路由)用于多数据集训练/评估。它决定了每个数据集列由哪个 Router 子模块处理同时覆盖 data collator 的默认任务分配默认第 0 列为 query、其余为 document。3.3 learning_rate_mapping分模块学习率A mapping of parameter name regular expressions to learning rates.允许对模型不同部分设置不同学习率例如{SparseStaticEmbedding\.*: 1e-3}。适用于只想以不同速率微调模型特定子模块如投影层、特定 Embedding 层的场景。3.4 batch_sampler 与 multi_dataset_batch_samplerbatch_sampler默认BatchSamplers.BATCH_SAMPLER可选值见sentence_transformers.base.sampler.BatchSamplers。多向量对比学习训练中常使用BatchSamplers.NO_DUPLICATES见下文 MIRIAD 示例来降低批内重复文档multi_dataset_batch_sampler默认MultiDatasetBatchSamplers.PROPORTIONAL控制多数据集训练时的按比例采样。两者都支持传入字符串枚举值构造时自动转换或自定义可调用对象to_dict()时会剔除可调用对象以便序列化。3.5 warmup 兼容逻辑BaseTrainingArguments显式定义了warmup_ratio并实现了跨 Transformers 版本的兼容Transformers v5warmup_ratio已废弃使用warmup_steps可传 float 表示比例Transformers v4支持warmup_ratio与整数warmup_steps若向warmup_steps传入(0, 1)区间的 float会将其自动转换为warmup_ratio。这正是仓库示例中warmup_steps0.05Warm up over the first 5% of training steps这一写法的来源。四、其他在__post_init__中被自动修正的行为BaseTrainingArguments.__post_init__中还有几个值得了解的训练行为sentence_transformers/base/training_args.pyprediction_loss_only TrueSentenceTransformerTrainer.compute_loss被重写为只计算预测损失因此显式设置以避免额外计算ddp_broadcast_buffers False避免基于 BertModel 的模型在 DDP 训练时触发 inplace 操作导致的RuntimeError非分布式模式下提示 DataParallelDP慢于 DistributedDataParallelDDPDDP 模式下若未设置dataloader_drop_last会自动置为True以避免不均匀末批次的挂起问题当dataloader_num_workers 0且工作进程通过spawn启动时提示设置dataloader_persistent_workersTrue否则每个 worker 都要重新 import sentence-transformers耗时数秒反而比dataloader_num_workers0更慢。五、dict 字段的字符串解析机制_VALID_DICT_FIELDS追踪所有允许以字符串形式传入 dict的字段目前包括accelerator_config, fsdp_config, deepspeed, gradient_checkpointing_kwargs, lr_scheduler_kwargs, learning_rate_mapping, prompts, router_mappingMultiVectorEncoderTrainingArguments追加了max_length。在__post_init__中learning_rate_mapping与router_mapping若为字符串则尝试json.loads解析失败会抛出明确的ValueError而prompts解析失败时会被宽容地当作单 prompt 字符串。这意味着这些参数既可以在 Python 中以 dict 传入也可以从命令行以 JSON 字符串传入。六、实战一MS MARCO 知识蒸馏训练max_length180仓库中的 examples/multi_vector_encoder/training/msmarco/training_kd.py 是一个完整可运行的 ColBERT 蒸馏训练脚本。其核心配置如下args MultiVectorEncoderTrainingArguments( # Required parameter: output_dirfmodels/{run_name}, # Optional training parameters: num_train_epochsnum_epochs, per_device_train_batch_sizetrain_batch_size, gradient_accumulation_stepsgradient_accumulation_steps, per_device_eval_batch_sizetrain_batch_size, learning_ratelearning_rate, max_length180, # Cap training tokenization at 180 tokens, the query width floor stays 32 via the expansion warmup_steps0.05, # Warm up over the first 5% of training steps fp16False, # Set to False if you get an error that your GPU cant run on FP16 bf16True, # Set to True if you have a GPU that supports BF16 load_best_model_at_endTrue, metric_for_best_modeleval_NanoBEIR_mean_maxsim_ndcg10, # Optional tracking/debugging parameters: eval_strategysteps, # The NanoBEIR evaluator runs on its own datasets, so no eval_dataset is needed eval_steps0.1, save_strategysteps, save_steps0.1, save_total_limit2, logging_steps0.01, run_namerun_name, # Will be used in WB if wandb is installed seed42, )要点解读训练集为(query_id, document_ids, scores)的知识蒸馏格式通过resolve_ids将 ID 实时解析为文本max_list_length32控制每个 query 的负例文档数损失为MultiVectorDistillKLDivLoss(modelmodel, temperature0.25)——教师分数分布经温度锐化后与学生分数分布做 KL 散度评估器MultiVectorNanoBEIREvaluator自行加载 NanoBEIR 数据集因此eval_strategysteps时无需eval_datasetmax_length180的意义训练 tokenize 被截断到 180 token而查询宽度下限32由 query expansion 兜底模型推理/保存仍保持自身完整长度配置metric_for_best_modeleval_NanoBEIR_mean_maxsim_ndcg10表明该模型以MeanMaxSim长度归一化的 MaxSim作为评估指标训练期打分与评估口径保持一致混合精度bf16True、fp16False需 GPU 支持 BF16。七、实战二MIRIAD 医疗问答对比学习max_length1024examples/multi_vector_encoder/training/miriad/training_contrastive.py 展示了从零构建 ColBERT 模块序列并训练的场景。其参数配置args MultiVectorEncoderTrainingArguments( output_dirfmodels/{run_name}, num_train_epochsnum_epochs, per_device_train_batch_sizetrain_batch_size, per_device_eval_batch_size8, learning_ratelearning_rate, max_length1024, # Cap training tokenization: passages average ~940 tokens, the model serves 8192 warmup_steps0.05, fp16False, bf16True, batch_samplerBatchSamplers.NO_DUPLICATES, load_best_model_at_endTrue, metric_for_best_modeleval_miriad_eval_maxsim_ndcg10, eval_strategysteps, eval_steps0.1, save_strategysteps, save_steps0.1, save_total_limit2, logging_steps0.005, run_namerun_name, seed42, )要点解读模型由Transformer Dense(128) MultiVectorMask(skiplist_wordspunctuation) Normalize四个模块顺序组成可通过MultiVectorEncoder(modules[...])从零构建详见 sentence_transformers/multi_vector_encoder/model.py 的_load_default_modules与示例脚本中的构造方式损失为CachedMultiVectorMultipleNegativesRankingLoss(modelmodel, mini_batch_sizemini_batch_size)——缓存式大 batch InfoNCE 目标max_length1024的典型场景MIRIAD 段落平均约 940 token训练截断到 1024 即可覆盖绝大多数样本而模型在推理时支持 8192 token即文档注释the model serves 8192。训练与推理长度解耦正是max_length的设计意图batch_samplerBatchSamplers.NO_DUPLICATES避免同一批次内出现重复文档提升对比学习质量训练中评估用 1000 条 query 的子采样build_ir_evaluator(..., max_queries1000)最终用完整 NanoBEIR 测试集评估。八、常见的完整训练流程闭环综合两个实战脚本一个标准的多向量训练流程为构建/加载模型MultiVectorEncoder(lightonai/LateOn)或MultiVectorEncoder(modules[...])从零构建投影层随机初始化时会有日志提示 Training is required before this model is useful准备数据标准 pair / triplet / multi-negative 格式或(query, document_1, ..., document_N, scores)的蒸馏格式配合resolve_ids实时解析选择损失不传时默认MultiVectorMultipleNegativesRankingLoss蒸馏用MultiVectorDistillKLDivLoss、margin-MSE 用MultiVectorMarginMSELoss大 batch 用缓存式损失可传loss或按数据集名分发的 dict定义评估器如MultiVectorNanoBEIREvaluator、MultiVectorInformationRetrievalEvaluator等见 docs/package_reference/multi_vector_encoder/evaluation.md可先跑一次基线配置MultiVectorEncoderTrainingArguments重点调好max_length考虑 query_expansion 的固定宽度下限、metric_for_best_model与模型similarity_fn_name保持一致maxsim或meanmaxsim、batch sampler 与混合精度训练并保存MultiVectorEncoderTrainer(model..., args..., train_dataset..., loss..., evaluator...)→trainer.train()→model.save_pretrained()或model.push_to_hub()。九、关键设计要点速查关注点结论依据max_length作用域仅训练与 evaluation-loss 批次评估器/推理/保存模型不受影响training_args.py docstringmax_lengthint所有列统一长度同上max_lengthdict按query/document任务区分第 0 列默认 query其余 documentdata_collator.py_get_task_for_column任务覆盖用router_mapping按列名覆盖默认分配同上 base/training_args.pyquery_expansionfixed查询忽略max_length宽度由扩展长度固定training_args.py docstringquery_expansionminmax_length为上限且不低于扩展长度training_args.py docstring默认损失MultiVectorMultipleNegativesRankingLosstrainer.pyget_default_loss推理长度配置走模型自身的processor_kwargs/processing_kwargstraining_args.py docstringdict 字段字符串解析_VALID_DICT_FIELDS中的字段支持 JSON 字符串max_length已追加training_args.py__post_init__十、适用前提与注意事项本文描述的行为以当前仓库代码为准MultiVectorEncoderTrainingArguments是 2025 年后引入的新 API若你使用的旧版本 sbert 中不存在MultiVectorEncoder或该参数类请先升级到包含sentence_transformers/multi_vector_encoder/包的最新版本max_length的收益依赖模型本身支持的长序列能力与训练数据分布文档与示例均强调紧凑上限可能更快且更强但具体数值180、1024应依据你自己的语料 token 分布决定混合精度fp16/bf16需硬件支持warmup_steps传 float 比例的写法依赖BaseTrainingArguments的 Transformers v4/v5 兼容逻辑训练长度与推理长度解耦的前提是训练数据被截断后仍保留足够语义——对于超长文档的领域过小的max_length会让模型看不见关键内容建议先统计语料 token 分布再定值。十一、继续深入阅读参数类实现sentence_transformers/multi_vector_encoder/training_args.py、sentence_transformers/base/training_args.py配套 Trainersentence_transformers/multi_vector_encoder/trainer.py默认损失、模型卡回调、混合精度、多 GPU任务分配实现sentence_transformers/multi_vector_encoder/data_collator.py模型与推理侧长度配置sentence_transformers/multi_vector_encoder/model.py、sentence_transformers/base/modules/transformer.pyquery_length、document_length、query_expansion完整可运行示例examples/multi_vector_encoder/training/msmarco/training_kd.py、examples/multi_vector_encoder/training/miriad/training_contrastive.py相关 API 参考docs/package_reference/multi_vector_encoder/trainer.md、docs/package_reference/multi_vector_encoder/model.md、docs/package_reference/multi_vector_encoder/losses.md赞分享人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载相关推荐PaddleOCR多卡训练参数配置详解PaddleOCR多卡训练参数配置详解 在使用PaddleOCR进行深度学习模型训练时很多开发者会遇到多GPU训练配置的问题。特别是在使用分布式训练时参数的人工智能计算机视觉OCR深度学习大模型RAG《sentence-transformers模型的参数设置详解》《sentence transformers模型的参数设置详解》 引言 在自然语言处理NLP领域模型参数设置的重要性不言而喻。参数的选择和调整直接影响模型Argilla 向量数据实战VectorSettings 配置、向量写入与 Sentence Transformers 语义嵌入Argilla 向量数据实战VectorSettings 配置、向量写入与 Sentence Transformers 语义嵌入 Argilla 是面向 AI数据标注人工智能NLPMLOpsRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考