FlagEmbedding 编码器架构 Embedder 微调全解析Base 与 M3 双路径 API 指南【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本文以 FlagEmbedding 官方 API 文档 docs/source/API/finetune/embedder/encoder_only.rst 为骨架系统讲解FlagEmbedding.finetune.embedder.encoder_only模块下两类编码器Encoder-OnlyEmbedder 微调路径面向普通双塔模型的Base路径BiEncoderOnlyEmbedderModel与面向 BGE-M3 的多向量M3路径EncoderOnlyEmbedderM3Model。读完本文你将掌握两大路径的类层次、核心方法与训练参数、损失计算原理以及可直接运行的微调启动命令能够在 FlagEmbedding 框架内独立配置并启动一次编码器架构 Embedder 的微调任务。一、模块定位Encoder-Only 微调在 FlagEmbedding 中的角色FlagEmbedding 的finetune.embedder目录下分为encoder_only与decoder_only两大分支前者面向 BERT/RoBERTa 这类双向编码器架构将句子编码为固定维度的向量后者则面向 LLM 类 decoder 架构。本文聚焦的 encoder_only 目录结构如下FlagEmbedding/finetune/embedder/encoder_only/ ├── __init__.py ├── base/ # Base 路径普通双塔编码器 │ ├── modeling.py # BiEncoderOnlyEmbedderModel │ ├── runner.py # EncoderOnlyEmbedderRunner │ └── trainer.py # EncoderOnlyEmbedderTrainer └── m3/ # M3 路径BGE-M3 多向量统一微调 ├── arguments.py # M3 专用 Model/Training 参数 ├── modeling.py # EncoderOnlyEmbedderM3Model 及推理类 ├── runner.py # EncoderOnlyEmbedderM3Runner └── trainer.py # EncoderOnlyEmbedderM3Trainer该模块的 API 文档base.rst 与 m3.rst通过 Sphinx autodoc 生成分别索引了Modeling、Runner、TrainerBase以及Arguments、Modeling、Runner、TrainerM3等子章节所有类均继承自抽象基类目录 FlagEmbedding/abc/finetune/embedder 中的AbsEmbedderModel、AbsEmbedderRunner、AbsEmbedderTrainer。二、Base 路径BiEncoderOnlyEmbedderModel双塔编码器模型2.1 类的定位与构造参数BiEncoderOnlyEmbedderModel定义于 modeling.py继承AbsEmbedderModel是查询-文档双塔结构的核心封装。其构造参数与含义如下表参数默认值说明base_model必填用于训练的基座模型PreTrainedModel通常为 BERT 系编码器tokenizerNone分词器实例negatives_cross_deviceFalse是否跨设备共享负样本计算损失temperature1.0控制分数缩放的温度系数sub_batch_size-1编码时的子批次大小为负则不切分kd_loss_typekl_div知识蒸馏损失类型use_mrlFalse是否使用 Matryoshka Representation Learning 训练mrl_dims[]MRL 各层输出维度列表sentence_pooling_methodcls句向量池化方式可选cls/mean/last_tokennormalize_embeddingsFalse是否对向量做 L2 归一化值得注意temperature与normalize_embeddings的默认值在 AbsArguments.py 中分别被命令行默认覆盖为0.02与True即实际微调脚本默认使用 0.02 的温度并归一化向量。2.2 核心方法逐一解析encode(features)是模型的前向编码入口。从源码实现看modeling.py它有三条分支路径子批次切分当sub_batch_size 0时按 attention mask 长度将 batch 切成多个子批次分别前向再torch.cat拼接用于显存受限场景整批编码直接对整批输入做一次前向列表输入features为 list每组特征长度不同时逐组编码后拼接。若启用use_mrl则按mrl_dims依次截取前dim维超出原始维度时告警并截断到原始维度可选归一化后返回多个维度的向量列表否则返回单条向量并可选归一化。_sentence_embedding(last_hidden_state, attention_mask)实现三种池化modeling.pycls取last_hidden_state[:, 0]mean按 attention mask 加权求平均last_token先判断是否为左侧 paddingleft_padding左 padding 直接取末位否则取每个序列最后一个有效 tokenattention_mask.sum(dim1) - 1定位。compute_score(q_reps, p_reps)与_compute_similarity(q_reps, p_reps)相似度采用内积torch.matmul再除以temperature得到分数矩阵compute_loss(scores, target)直接使用交叉熵torch.nn.CrossEntropyLoss(reductionmean)。gradient_checkpointing_enable与enable_input_require_grads分别透传给底层 HuggingFace 模型用于显存优化与梯度检查点兼容save(output_dir)将权重克隆到 CPU 后调用save_pretrained落盘。2.3 Runner 与 TrainerEncoderOnlyEmbedderRunnerrunner.py负责组装训练管线load_tokenizer_and_model()用AutoTokenizer/AutoModel/AutoConfig从model_args.model_name_or_path加载构建BiEncoderOnlyEmbedderModel将训练参数逐一注入开启gradient_checkpointing时调用enable_input_require_grads()设置fix_position_embedding时遍历参数将含position_embeddings的权重requires_grad置为Falseload_trainer()构造EncoderOnlyEmbedderTrainer并在same_dataset_within_batch为真时注册EmbedderTrainerCallbackForDataRefresh回调保证同一 batch 内的样本来自同一数据集。EncoderOnlyEmbedderTrainertrainer.py覆写_save先调用模型的save(output_dir)保存权重再由主进程保存 tokenizer并额外把training_args以training_args.bin存入输出目录便于后续恢复训练配置。三、M3 路径EncoderOnlyEmbedderM3Model多向量统一微调3.1 与 Base 的本质区别BGE-M3 同时产出稠密Dense、**稀疏Sparse**与 **ColBERT多向量**三类表示。因此EncoderOnlyEmbedderM3Modelmodeling.py在构造时接收的不再是单个base_model而是一个 dict{model: ..., colbert_linear: ..., sparse_linear: ...}。其中colbert_linearLinear(hidden_size, hidden_size 或 colbert_dim)将 token 隐层投影为 ColBERT 向量sparse_linearLinear(hidden_size, 1)为每个 token 产出稀疏词权重。unified_finetuningTrue时三者联合训练为False时只保留modelcolbert_linear/sparse_linear置空等价于纯稠密微调。此外该模型明确禁止 MRL构造函数中if use_mrl is True: raise NotImplementedError。3.2 三类表示的编码实现稠密_dense_embedding复用与 Base 相同的三种池化cls/mean/last_token稀疏_sparse_embeddingmodeling.py先经sparse_linear ReLU 得到 token 权重再scatter到 vocab 维度的稀疏向量上。训练态用torch.scatter推理态用scatter_reduce(..., reduceamax)避免原地操作破坏梯度详见代码内注释引用的 issue #1364随后将cls/eos/pad/unk特殊 token 的权重清零ColBERT_colbert_embedding取last_hidden_state[:, 1:]跳过 [CLS]经colbert_linear投影并与 mask 相乘屏蔽 padding。3.3 打分与损失三种分数 集成分数compute_dense_score、compute_sparse_score均为内积除以温度compute_colbert_scoremodeling.py用torch.einsum(qin,pjn-qipj, q_reps, p_reps)计算 token 级相似度矩阵对 passage 维度取 max晚期交互再对 query token 求和并除以 query mask 中有效 token 数。三者加权组合为最终分数dense_score * dense_weight sparse_score * sparse_weight colbert_score * colbert_weight默认权重为 dense1.0、sparse0.3、colbert1.0compute_score签名默认值ensemble_score亦按dense 0.3 * sparse colbert合成集成分数。forward()modeling.py的损失逻辑最值得关注训练态下dense / sparse / colbert 三路分别用compute_loss_func计算损失negatives_cross_device或no_in_batch_neg_flag会切换为跨设备/无 in-batch 负样本损失再计算 ensemble 损失最终loss (loss ensemble_loss 0.1 * sparse_loss colbert_loss) / 4若开启use_self_distill且self.step self_distill_start_step则以 ensemble 分数detach 后 softmax作为软标签对三路分数各算一次 KL 散度自蒸馏损失叠加后整体减半。teacher_scores非空时则走知识蒸馏以教师分数 softmax 作为teacher_targets。3.4 M3 专用参数类EncoderOnlyEmbedderM3ModelArguments与EncoderOnlyEmbedderM3TrainingArgumentsarguments.py在抽象参数之上扩展了参数默认值说明colbert_dim-1ColBERT 线性层输出维度≤0 时沿用hidden_sizeunified_finetuningFalse是否统一微调三路表示use_self_distillFalse统一微调时是否使用自蒸馏fix_encoderFalse冻结编码器仅训练 colbert/sparse 线性层self_distill_start_step-1自蒸馏启动的步数阈值其中fix_encoder在EncoderOnlyEmbedderM3Runner.load_tokenizer_and_modelm3/runner.py中实现遍历参数时仅放行名字含colbert_linear或sparse_linear的权重。同时该 Runner 的静态方法get_model会从本地路径或 HuggingFace Hub 拉取模型新建两个线性层若模型目录下已存在colbert_linear.pt与sparse_linear.pt由save方法保存则自动加载续训否则视为全新初始化并打印提示。3.5 推理封装EncoderOnlyEmbedderM3ModelForInference该子类modeling.py重写forward通过return_dense/return_sparse/return_colbert_vecs三个开关按需输出且断言三者至少一个为真。truncate_dim可对 dense/colbert 向量做维度截断兼容 Matryoshka 场景return_sparse_embedding控制稀疏输出是完整 embedding 还是仅 token 权重。进入该推理分支时会强制self.training False保证稀疏计算走非原地路径。四、M3 Trainer 与 Base Trainer 的保存差异EncoderOnlyEmbedderM3Trainer的_save与 Base 版行为一致调用model.save(output_dir)、保存 tokenizer 与training_args.bin差异集中在EncoderOnlyEmbedderM3Model.savemodeling.py除主干权重外unified_finetuning模式下还会额外保存colbert_linear.pt与sparse_linear.pt两个独立文件这正是下一轮训练时get_model能加载续训的前提。五、实战从命令行启动 Encoder-Only 微调仓库提供了开箱即用的脚本 base.sh 与 m3.sh。两者公共的数据与训练配置如下测试用途正式训练请调大 epoch 与 batchexport WANDB_MODEdisabled train_data\ ../example_data/retrieval \ ../example_data/sts/sts.jsonl \ ../example_data/classification-no_in_batch_neg \ ../example_data/clustering-no_in_batch_neg num_train_epochs4 per_device_train_batch_size2 num_gpus2 data_args\ --train_data $train_data \ --cache_path ~/.cache \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ Base 路径对应文档encoder_only/base启动命令torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.embedder.encoder_only.base \ --model_name_or_path BAAI/bge-large-en-v1.5 \ --query_instruction_for_retrieval Represent this sentence for searching relevant passages: \ --output_dir ./test_encoder_only_base_bge-large-en-v1.5 \ --overwrite_output_dir --learning_rate 1e-5 --fp16 \ --num_train_epochs 4 --per_device_train_batch_size 2 \ --dataloader_drop_last True --warmup_ratio 0.1 \ --gradient_checkpointing --deepspeed ../../ds_stage0.json \ --logging_steps 1 --save_steps 1000 \ --negatives_cross_device --temperature 0.02 \ --sentence_pooling_method cls --normalize_embeddings True \ --kd_loss_type kl_divM3 路径对应文档encoder_only/m3在 Base 基础上追加多向量微调参数torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.embedder.encoder_only.m3 \ --model_name_or_path BAAI/bge-m3 \ --output_dir ./test_encoder_only_m3_bge-m3 \ --learning_rate 1e-5 --fp16 --num_train_epochs 4 \ --per_device_train_batch_size 2 --dataloader_drop_last True \ --warmup_ratio 0.1 --gradient_checkpointing \ --deepspeed ../../ds_stage0.json --logging_steps 1 --save_steps 1000 \ --negatives_cross_device --temperature 0.02 \ --sentence_pooling_method cls --normalize_embeddings True \ --kd_loss_type m3_kd_loss \ --unified_finetuning True --use_self_distill True \ --fix_encoder False --self_distill_start_step 05.1 核心训练参数速查表以下参数定义于 AbsArguments.py适用于两条路径参数默认值说明negatives_cross_deviceFalse跨设备共享负样本多卡时等价于扩大 batch 的负样本数temperature0.02相似度分数缩放温度fix_position_embeddingFalse冻结 position embeddings 参数sentence_pooling_methodcls池化方式可选cls/mean/last_tokennormalize_embeddingsTrue是否归一化输出向量sub_batch_sizeNone训练编码子批次大小kd_loss_typekl_div蒸馏损失可选kl_div/m3_kd_lossuse_mrl/mrl_dimsFalse/[]Matryoshka 表示学习开关与维度列表M3 模型不支持train_data必填训练数据路径要求每条含query、pos: List[str]、neg: List[str]字段train_group_size8每组样本数含正负样本query_max_len/passage_max_len32/128查询/文档最大长度query_instruction_for_retrievalNone查询侧指令前缀knowledge_distillationFalse数据含pos_scores/neg_scores时启用蒸馏same_dataset_within_batchFalse同一 batch 样本来自同一数据集多数据集训练时防止跨集互相充当负样本六、总结与延伸阅读encoder_only模块为 BERT 系编码器提供了两条成熟微调路径Base 路径以BiEncoderOnlyEmbedderModel的内积相似度 交叉熵双塔范式适配各类稠密检索任务支持 MRL、跨设备负样本、知识蒸馏与三种池化M3 路径则在EncoderOnlyEmbedderM3Model中实现 dense/sparse/ColBERT 三路联合训练、加权集成打分、自蒸馏与统一的fix_encoder冻结策略是 BGE-M3 能力向微调场景的完整开放接口。若希望进一步深入可依次阅读抽象基类定义FlagEmbedding/abc/finetune/embedderAbsEmbedderModel、AbsEmbedderRunner、AbsEmbedderTrainer、AbsArguments解码器LLM架构微调对照decoder_only推理侧封装FlagEmbedding/inference/embedder/encoder_only完整 API 文档索引docs/source/API/finetune/embedder.rst。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FlagEmbedding 编码器架构 Embedder 微调全解析：Base 与 M3 双路径 API 指南
FlagEmbedding 编码器架构 Embedder 微调全解析Base 与 M3 双路径 API 指南【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本文以 FlagEmbedding 官方 API 文档 docs/source/API/finetune/embedder/encoder_only.rst 为骨架系统讲解FlagEmbedding.finetune.embedder.encoder_only模块下两类编码器Encoder-OnlyEmbedder 微调路径面向普通双塔模型的Base路径BiEncoderOnlyEmbedderModel与面向 BGE-M3 的多向量M3路径EncoderOnlyEmbedderM3Model。读完本文你将掌握两大路径的类层次、核心方法与训练参数、损失计算原理以及可直接运行的微调启动命令能够在 FlagEmbedding 框架内独立配置并启动一次编码器架构 Embedder 的微调任务。一、模块定位Encoder-Only 微调在 FlagEmbedding 中的角色FlagEmbedding 的finetune.embedder目录下分为encoder_only与decoder_only两大分支前者面向 BERT/RoBERTa 这类双向编码器架构将句子编码为固定维度的向量后者则面向 LLM 类 decoder 架构。本文聚焦的 encoder_only 目录结构如下FlagEmbedding/finetune/embedder/encoder_only/ ├── __init__.py ├── base/ # Base 路径普通双塔编码器 │ ├── modeling.py # BiEncoderOnlyEmbedderModel │ ├── runner.py # EncoderOnlyEmbedderRunner │ └── trainer.py # EncoderOnlyEmbedderTrainer └── m3/ # M3 路径BGE-M3 多向量统一微调 ├── arguments.py # M3 专用 Model/Training 参数 ├── modeling.py # EncoderOnlyEmbedderM3Model 及推理类 ├── runner.py # EncoderOnlyEmbedderM3Runner └── trainer.py # EncoderOnlyEmbedderM3Trainer该模块的 API 文档base.rst 与 m3.rst通过 Sphinx autodoc 生成分别索引了Modeling、Runner、TrainerBase以及Arguments、Modeling、Runner、TrainerM3等子章节所有类均继承自抽象基类目录 FlagEmbedding/abc/finetune/embedder 中的AbsEmbedderModel、AbsEmbedderRunner、AbsEmbedderTrainer。二、Base 路径BiEncoderOnlyEmbedderModel双塔编码器模型2.1 类的定位与构造参数BiEncoderOnlyEmbedderModel定义于 modeling.py继承AbsEmbedderModel是查询-文档双塔结构的核心封装。其构造参数与含义如下表参数默认值说明base_model必填用于训练的基座模型PreTrainedModel通常为 BERT 系编码器tokenizerNone分词器实例negatives_cross_deviceFalse是否跨设备共享负样本计算损失temperature1.0控制分数缩放的温度系数sub_batch_size-1编码时的子批次大小为负则不切分kd_loss_typekl_div知识蒸馏损失类型use_mrlFalse是否使用 Matryoshka Representation Learning 训练mrl_dims[]MRL 各层输出维度列表sentence_pooling_methodcls句向量池化方式可选cls/mean/last_tokennormalize_embeddingsFalse是否对向量做 L2 归一化值得注意temperature与normalize_embeddings的默认值在 AbsArguments.py 中分别被命令行默认覆盖为0.02与True即实际微调脚本默认使用 0.02 的温度并归一化向量。2.2 核心方法逐一解析encode(features)是模型的前向编码入口。从源码实现看modeling.py它有三条分支路径子批次切分当sub_batch_size 0时按 attention mask 长度将 batch 切成多个子批次分别前向再torch.cat拼接用于显存受限场景整批编码直接对整批输入做一次前向列表输入features为 list每组特征长度不同时逐组编码后拼接。若启用use_mrl则按mrl_dims依次截取前dim维超出原始维度时告警并截断到原始维度可选归一化后返回多个维度的向量列表否则返回单条向量并可选归一化。_sentence_embedding(last_hidden_state, attention_mask)实现三种池化modeling.pycls取last_hidden_state[:, 0]mean按 attention mask 加权求平均last_token先判断是否为左侧 paddingleft_padding左 padding 直接取末位否则取每个序列最后一个有效 tokenattention_mask.sum(dim1) - 1定位。compute_score(q_reps, p_reps)与_compute_similarity(q_reps, p_reps)相似度采用内积torch.matmul再除以temperature得到分数矩阵compute_loss(scores, target)直接使用交叉熵torch.nn.CrossEntropyLoss(reductionmean)。gradient_checkpointing_enable与enable_input_require_grads分别透传给底层 HuggingFace 模型用于显存优化与梯度检查点兼容save(output_dir)将权重克隆到 CPU 后调用save_pretrained落盘。2.3 Runner 与 TrainerEncoderOnlyEmbedderRunnerrunner.py负责组装训练管线load_tokenizer_and_model()用AutoTokenizer/AutoModel/AutoConfig从model_args.model_name_or_path加载构建BiEncoderOnlyEmbedderModel将训练参数逐一注入开启gradient_checkpointing时调用enable_input_require_grads()设置fix_position_embedding时遍历参数将含position_embeddings的权重requires_grad置为Falseload_trainer()构造EncoderOnlyEmbedderTrainer并在same_dataset_within_batch为真时注册EmbedderTrainerCallbackForDataRefresh回调保证同一 batch 内的样本来自同一数据集。EncoderOnlyEmbedderTrainertrainer.py覆写_save先调用模型的save(output_dir)保存权重再由主进程保存 tokenizer并额外把training_args以training_args.bin存入输出目录便于后续恢复训练配置。三、M3 路径EncoderOnlyEmbedderM3Model多向量统一微调3.1 与 Base 的本质区别BGE-M3 同时产出稠密Dense、**稀疏Sparse**与 **ColBERT多向量**三类表示。因此EncoderOnlyEmbedderM3Modelmodeling.py在构造时接收的不再是单个base_model而是一个 dict{model: ..., colbert_linear: ..., sparse_linear: ...}。其中colbert_linearLinear(hidden_size, hidden_size 或 colbert_dim)将 token 隐层投影为 ColBERT 向量sparse_linearLinear(hidden_size, 1)为每个 token 产出稀疏词权重。unified_finetuningTrue时三者联合训练为False时只保留modelcolbert_linear/sparse_linear置空等价于纯稠密微调。此外该模型明确禁止 MRL构造函数中if use_mrl is True: raise NotImplementedError。3.2 三类表示的编码实现稠密_dense_embedding复用与 Base 相同的三种池化cls/mean/last_token稀疏_sparse_embeddingmodeling.py先经sparse_linear ReLU 得到 token 权重再scatter到 vocab 维度的稀疏向量上。训练态用torch.scatter推理态用scatter_reduce(..., reduceamax)避免原地操作破坏梯度详见代码内注释引用的 issue #1364随后将cls/eos/pad/unk特殊 token 的权重清零ColBERT_colbert_embedding取last_hidden_state[:, 1:]跳过 [CLS]经colbert_linear投影并与 mask 相乘屏蔽 padding。3.3 打分与损失三种分数 集成分数compute_dense_score、compute_sparse_score均为内积除以温度compute_colbert_scoremodeling.py用torch.einsum(qin,pjn-qipj, q_reps, p_reps)计算 token 级相似度矩阵对 passage 维度取 max晚期交互再对 query token 求和并除以 query mask 中有效 token 数。三者加权组合为最终分数dense_score * dense_weight sparse_score * sparse_weight colbert_score * colbert_weight默认权重为 dense1.0、sparse0.3、colbert1.0compute_score签名默认值ensemble_score亦按dense 0.3 * sparse colbert合成集成分数。forward()modeling.py的损失逻辑最值得关注训练态下dense / sparse / colbert 三路分别用compute_loss_func计算损失negatives_cross_device或no_in_batch_neg_flag会切换为跨设备/无 in-batch 负样本损失再计算 ensemble 损失最终loss (loss ensemble_loss 0.1 * sparse_loss colbert_loss) / 4若开启use_self_distill且self.step self_distill_start_step则以 ensemble 分数detach 后 softmax作为软标签对三路分数各算一次 KL 散度自蒸馏损失叠加后整体减半。teacher_scores非空时则走知识蒸馏以教师分数 softmax 作为teacher_targets。3.4 M3 专用参数类EncoderOnlyEmbedderM3ModelArguments与EncoderOnlyEmbedderM3TrainingArgumentsarguments.py在抽象参数之上扩展了参数默认值说明colbert_dim-1ColBERT 线性层输出维度≤0 时沿用hidden_sizeunified_finetuningFalse是否统一微调三路表示use_self_distillFalse统一微调时是否使用自蒸馏fix_encoderFalse冻结编码器仅训练 colbert/sparse 线性层self_distill_start_step-1自蒸馏启动的步数阈值其中fix_encoder在EncoderOnlyEmbedderM3Runner.load_tokenizer_and_modelm3/runner.py中实现遍历参数时仅放行名字含colbert_linear或sparse_linear的权重。同时该 Runner 的静态方法get_model会从本地路径或 HuggingFace Hub 拉取模型新建两个线性层若模型目录下已存在colbert_linear.pt与sparse_linear.pt由save方法保存则自动加载续训否则视为全新初始化并打印提示。3.5 推理封装EncoderOnlyEmbedderM3ModelForInference该子类modeling.py重写forward通过return_dense/return_sparse/return_colbert_vecs三个开关按需输出且断言三者至少一个为真。truncate_dim可对 dense/colbert 向量做维度截断兼容 Matryoshka 场景return_sparse_embedding控制稀疏输出是完整 embedding 还是仅 token 权重。进入该推理分支时会强制self.training False保证稀疏计算走非原地路径。四、M3 Trainer 与 Base Trainer 的保存差异EncoderOnlyEmbedderM3Trainer的_save与 Base 版行为一致调用model.save(output_dir)、保存 tokenizer 与training_args.bin差异集中在EncoderOnlyEmbedderM3Model.savemodeling.py除主干权重外unified_finetuning模式下还会额外保存colbert_linear.pt与sparse_linear.pt两个独立文件这正是下一轮训练时get_model能加载续训的前提。五、实战从命令行启动 Encoder-Only 微调仓库提供了开箱即用的脚本 base.sh 与 m3.sh。两者公共的数据与训练配置如下测试用途正式训练请调大 epoch 与 batchexport WANDB_MODEdisabled train_data\ ../example_data/retrieval \ ../example_data/sts/sts.jsonl \ ../example_data/classification-no_in_batch_neg \ ../example_data/clustering-no_in_batch_neg num_train_epochs4 per_device_train_batch_size2 num_gpus2 data_args\ --train_data $train_data \ --cache_path ~/.cache \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ Base 路径对应文档encoder_only/base启动命令torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.embedder.encoder_only.base \ --model_name_or_path BAAI/bge-large-en-v1.5 \ --query_instruction_for_retrieval Represent this sentence for searching relevant passages: \ --output_dir ./test_encoder_only_base_bge-large-en-v1.5 \ --overwrite_output_dir --learning_rate 1e-5 --fp16 \ --num_train_epochs 4 --per_device_train_batch_size 2 \ --dataloader_drop_last True --warmup_ratio 0.1 \ --gradient_checkpointing --deepspeed ../../ds_stage0.json \ --logging_steps 1 --save_steps 1000 \ --negatives_cross_device --temperature 0.02 \ --sentence_pooling_method cls --normalize_embeddings True \ --kd_loss_type kl_divM3 路径对应文档encoder_only/m3在 Base 基础上追加多向量微调参数torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.embedder.encoder_only.m3 \ --model_name_or_path BAAI/bge-m3 \ --output_dir ./test_encoder_only_m3_bge-m3 \ --learning_rate 1e-5 --fp16 --num_train_epochs 4 \ --per_device_train_batch_size 2 --dataloader_drop_last True \ --warmup_ratio 0.1 --gradient_checkpointing \ --deepspeed ../../ds_stage0.json --logging_steps 1 --save_steps 1000 \ --negatives_cross_device --temperature 0.02 \ --sentence_pooling_method cls --normalize_embeddings True \ --kd_loss_type m3_kd_loss \ --unified_finetuning True --use_self_distill True \ --fix_encoder False --self_distill_start_step 05.1 核心训练参数速查表以下参数定义于 AbsArguments.py适用于两条路径参数默认值说明negatives_cross_deviceFalse跨设备共享负样本多卡时等价于扩大 batch 的负样本数temperature0.02相似度分数缩放温度fix_position_embeddingFalse冻结 position embeddings 参数sentence_pooling_methodcls池化方式可选cls/mean/last_tokennormalize_embeddingsTrue是否归一化输出向量sub_batch_sizeNone训练编码子批次大小kd_loss_typekl_div蒸馏损失可选kl_div/m3_kd_lossuse_mrl/mrl_dimsFalse/[]Matryoshka 表示学习开关与维度列表M3 模型不支持train_data必填训练数据路径要求每条含query、pos: List[str]、neg: List[str]字段train_group_size8每组样本数含正负样本query_max_len/passage_max_len32/128查询/文档最大长度query_instruction_for_retrievalNone查询侧指令前缀knowledge_distillationFalse数据含pos_scores/neg_scores时启用蒸馏same_dataset_within_batchFalse同一 batch 样本来自同一数据集多数据集训练时防止跨集互相充当负样本六、总结与延伸阅读encoder_only模块为 BERT 系编码器提供了两条成熟微调路径Base 路径以BiEncoderOnlyEmbedderModel的内积相似度 交叉熵双塔范式适配各类稠密检索任务支持 MRL、跨设备负样本、知识蒸馏与三种池化M3 路径则在EncoderOnlyEmbedderM3Model中实现 dense/sparse/ColBERT 三路联合训练、加权集成打分、自蒸馏与统一的fix_encoder冻结策略是 BGE-M3 能力向微调场景的完整开放接口。若希望进一步深入可依次阅读抽象基类定义FlagEmbedding/abc/finetune/embedderAbsEmbedderModel、AbsEmbedderRunner、AbsEmbedderTrainer、AbsArguments解码器LLM架构微调对照decoder_only推理侧封装FlagEmbedding/inference/embedder/encoder_only完整 API 文档索引docs/source/API/finetune/embedder.rst。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考