FlagEmbedding 解码器架构 Reranker 微调模型参数完全指南RerankerModelArguments 深度解析【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇指南聚焦 FlagEmbedding 开源库中解码器Decoder-only架构重排序模型Reranker微调时的模型参数体系以 API 文档 arguments.rst 自动文档化的RerankerModelArguments类为核心骨架结合数据参数、训练参数与源码实现逐项展开。读完本文你将掌握每个参数的含义、默认值与底层作用机制能够独立配置出一条可运行的 decoder-only reranker 微调命令并理解 LoRA 参数高效微调、Flash Attention、LoRA 权重合并等关键机制在 FlagEmbedding 中的落地方式。一、认识 RerankerModelArguments解码器 Reranker 的模型参数入口在 FlagEmbedding 中解码器架构 reranker 的微调入口位于 FlagEmbedding/finetune/reranker/decoder_only/base/其 API 文档arguments.rst通过 Sphinx 的autoclass指令将 arguments.py 中的RerankerModelArguments类自动呈现为参数参考页。该类是所有 decoder-only reranker 微调脚本-m FlagEmbedding.finetune.reranker.decoder_only.base必需的模型侧参数容器用于控制基础模型Causal LM的加载方式是否启用 LoRA 参数高效微调及其超参注意力实现方式标准注意力 / Flash Attention已训练 LoRA 权重的加载与最终合并导出策略。RerankerModelArguments本身定义在 arguments.py 中它继承自抽象基类AbsRerankerModelArguments位于 FlagEmbedding/abc/finetune/reranker/AbsArguments.py因此完整的参数面由子类自有的 LoRA/注意力参数 基类继承的模型加载参数两部分构成。二、自有参数详解LoRA 微调与注意力机制以下是RerankerModelArguments直接声明的全部参数均以dataclass字段形式定义默认值取自源码参数类型默认值说明use_loraboolTrue是否使用 LoRA低秩参数高效训练微调模型lora_rankint64LoRA 低秩矩阵的秩rlora_alphafloat16LoRA 缩放超参alphalora_dropoutfloat0.1LoRA 模块的 dropout 比例target_modulesList[str][v_proj, q_proj, k_proj, gate_proj, down_proj, o_proj, up_proj]应用 LoRA 的目标模块注意力与 MLP 投影层modules_to_saveList[str]None除 LoRA 适配器外需要完整保存进最终检查点的模块列表use_flash_attnboolFalse是否使用 Flash Attention 训练from_peftstrNone从一个已存在的 PEFT/LoRA 检查点继续训练raw_peftList[str]None加载一个或多个原始 PEFT 权重并先合并进基础模型save_merged_lora_modelboolFalse训练结束后将 LoRA 权重合并进基础模型并保存完整模型2.1 LoRA 微调开关与超参use_lora / lora_rank / lora_alpha / lora_dropoutDecoder-only reranker 的基座通常是数十亿参数的 Causal LM全参微调显存与算力开销极大因此库默认use_loraTrue。在 load_model.py 的get_model()中当use_lora为真时会构造peft.LoraConfigpeft_config LoraConfig( task_typeTaskType.CAUSAL_LM, inference_modeFalse, rmodel_args.lora_rank, target_modulesmodel_args.target_modules, modules_to_savemodel_args.modules_to_save, lora_alphamodel_args.lora_alpha, lora_dropoutmodel_args.lora_dropout ) model get_peft_model(model, peft_config) model.print_trainable_parameters()三个超参的配合关系遵循 PEFT 通用规则lora_alpha与lora_rank的比值构成缩放因子实际缩放为alpha / ralpha越大新注入低秩分支对原权重的影响越强lora_dropout用于缓解过拟合。官方示例 base.sh 中使用的组合是--lora_rank 32 --lora_alpha 64可见实际训练中可根据数据规模在默认值基础上灵活调整。2.2 目标模块与模块保存target_modules / modules_to_savetarget_modules的默认值由default_target_modules()工厂函数生成见 arguments.py覆盖了典型 LLaMA 系架构的全部投影层注意力q_proj、k_proj、v_proj、o_proj前馈网络MLPgate_proj、down_proj、up_proj如果你的基座模型命名规范不同例如 Qwen/Mistral 变体需要显式传入--target_modules覆盖默认值。示例脚本中即传入了精简后的--target_modules q_proj k_proj v_proj o_proj仅对注意力层注入 LoRA 以进一步减少可训练参数量。modules_to_save用于指定除 LoRA 适配器外还需要完整保存的模块例如自定义的评分头或特殊 embedding这些模块的权重会原样存入最终 checkpoint不设置时默认None仅保存 LoRA 适配器权重。2.3 Flash Attentionuse_flash_attnuse_flash_attnTrue时load_model.py 会在加载 Causal LM 时传入attn_implementationflash_attention_2以加速长序列下的注意力计算并显著降低显存占用。该选项依赖硬件环境需要支持 Flash Attention 的 GPU 与配套 CUDA 环境不满足条件时应保持默认False。示例脚本base.sh与layerwise.sh均开启了该选项并配合--bf16使用。2.4 已训练权重的加载与合并from_peft / raw_peft / save_merged_lora_model这三个参数共同构成断点续训 权重合并的完整链路对应 load_model.py 中的加载逻辑from_peft指定一个已训练好的 PEFT 检查点路径通过PeftModel.from_pretrained(model, from_peft, is_trainableTrue)在其基础上继续训练raw_peft可传入一个或多个 PEFT 路径先逐个PeftModel.from_pretrained加载并merge_and_unload()合并进基础模型再决定是否叠加新的 LoRA 训练save_merged_lora_model训练完成后若为True且当前进程为主进程process_index 0runner 会调用 save_merged_model() 将 LoRA 适配器合并回基础模型并把完整权重与 tokenizer 保存到output_dir/merged_model目录方便后续直接用于推理而无需 PEFT 运行时。三、继承自抽象基类的模型加载参数RerankerModelArguments继承的AbsRerankerModelArguments定义于 FlagEmbedding/abc/finetune/reranker/AbsArguments.py提供了与基础模型、分词器加载相关的通用参数参数类型默认值说明model_name_or_pathstr必填初始化用的模型检查点名称或路径config_namestrNone与model_name不同时的预训练 config 名称或路径tokenizer_namestrNone与model_name不同时的分词器名称或路径cache_dirstrNone存放从模型中心下载的预训练模型缓存的目录trust_remote_codeboolFalse是否信任并执行远程代码自定义模型结构必需model_typestrencoder微调类型可选[encoder, decoder]use_fast_tokenizerboolTrue是否使用基于 Tokenizers 的快速分词器tokenstr环境变量HF_TOKEN访问受限模型时使用的鉴权 token在 runner.py 的load_tokenizer_and_model()中分词器优先取tokenizer_name否则回退到model_name_or_path并依次传入token、cache_dir、use_fast、trust_remote_code等参数model_type则用于在更上层路由到 decoder 分支官方示例统一传--model_type decoder。值得注意的实现细节加载时若 tokenizer 没有 pad tokenrunner 会依次尝试用unk_token、eod/im_start等特殊 token 兜底且统一将padding_side设为left左填充这是为了适配 decoder-only reranker 中query 与 passage 拼接后取末尾 token 输出的打分方式见下文第四节。四、配套参数体系数据参数与训练参数API 文档页虽然只自动文档化了RerankerModelArguments但在实际入口脚本main.py 中命令行参数由三组 dataclass 共同解析parser HfArgumentParser((RerankerModelArguments, AbsRerankerDataArguments, AbsRerankerTrainingArguments)) model_args, data_args, training_args parser.parse_args_into_dataclasses()4.1 数据参数 AbsRerankerDataArguments定义于 AbsArguments.py核心参数如下参数默认值说明train_dataNone必填训练数据路径支持多个数据需包含query、pos: List[str]、neg: List[str]字段cache_pathNone缓存数据存放目录train_group_size8每个 query 对应的文档组大小正样本 负样本数量query_max_len32query 分词后的最大长度超出截断passage_max_len128passage 分词后的最大长度max_len512总输入序列的最大长度pad_to_multiple_ofNone若设置将序列 padding 到该值的整数倍通常配合 8 以利用 Tensor Coremax_example_num_per_dataset100000000每个数据集最多使用的样本数query_instruction_for_rerankNonequery 侧的指令文本如A: query_instruction_format{}{}query 指令的拼接格式passage_instruction_for_rerankNonepassage 侧的指令文本如B: passage_instruction_format{}{}passage 指令拼接格式knowledge_distillationFalse是否启用知识蒸馏需要训练数据含pos_scores、neg_scoresshuffle_ratio0.0打乱文本 token 顺序的比例sep_token\n区分 query 与 passage 的分隔符其中train_data在__post_init__阶段会做存在性校验路径不存在会抛出FileNotFoundError指令格式中的\\n会被替换为真实换行符。官方示例 base.sh 使用了A: / B:指令前缀配合{}{}格式即典型的把 query 标记为 A、passage 标记为 B的 prompt 构造方式这正是解码器 reranker 的核心工作形式。4.2 训练参数 AbsRerankerTrainingArguments该类继承自transformers.TrainingArguments因此原生支持output_dir、learning_rate、bf16、num_train_epochs、per_device_train_batch_size、gradient_accumulation_steps、warmup_ratio、weight_decay、gradient_checkpointing、deepspeed、save_steps、logging_steps、resume_from_checkpoint等全部 HF 训练参数。其自身额外声明了一个字段参数默认值说明sub_batch_sizeNone训练子批次大小源码注释标明当前版本尚未实现在 AbsModeling.py 中通过class AbsRerankerTrainingArguments(TrainingArguments)定义使用时直接按 HF Trainer 习惯传入即可。五、完整可运行的微调示例以仓库自带的 examples/finetune/reranker/decoder_only/base.sh 为基础结合上文参数解析一份完整的 decoder-only reranker 微调命令如下torchrun多卡启动torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.reranker.decoder_only.base \ --model_name_or_path BAAI/bge-reranker-v2-gemma \ --cache_dir $HF_HUB_CACHE \ --use_lora True \ --lora_rank 32 \ --lora_alpha 64 \ --use_flash_attn True \ --target_modules q_proj k_proj v_proj o_proj \ --save_merged_lora_model True \ --model_type decoder \ --train_data ../example_data/prompt_based/examples.jsonl \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ --knowledge_distillation True \ --query_instruction_for_rerank A: \ --query_instruction_format {}{} \ --passage_instruction_for_rerank B: \ --passage_instruction_format {}{} \ --output_dir ./test_decoder_only_base_bge-reranker-v2-gemma \ --overwrite_output_dir \ --learning_rate 2e-4 \ --bf16 \ --num_train_epochs 1 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 1 \ --dataloader_drop_last True \ --warmup_ratio 0.1 \ --gradient_checkpointing \ --weight_decay 0.01 \ --deepspeed ../../ds_stage0.json \ --logging_steps 1 \ --save_steps 1000运行后训练产物保存在--output_dir下由于开启了--save_merged_lora_model还会额外生成merged_model/子目录内含合并后的完整模型权重与 tokenizer可直接交给 FlagEmbedding/inference 模块进行推理。六、从源码看参数如何影响模型行为6.1 打分方式为什么 decoder reranker 取末尾 token 的 Yes 概率CrossDecoderModel见 modeling.py在encode()中计算相关性分数的核心代码为outputs self.model(input_idsfeatures[input_ids], attention_maskfeatures[attention_mask], position_ids..., output_hidden_statesTrue) scores outputs.logits[:, -1, self.yes_loc]yes_loc在基类 AbsModeling.py 中通过self.tokenizer(Yes, add_special_tokensFalse)[input_ids][-1]获得即模型把打分建模为预测序列末尾出现 Yes 的概率。这解释了为何需要query_instruction_for_rerankA:、passage_instruction_for_rerankB:与sep_token构造 prompt也解释了 runner 中强制padding_sideleft的原因——只有左填充才能保证每个样本真正的最后一个 token 位置对齐。6.2 损失函数与知识蒸馏基类forward()AbsModeling.py将同一 batch 内的打分按train_batch_size分组grouped_logits ranker_logits.view(self.train_batch_size, -1)以每组第一项正样本为 target 计算交叉熵损失。当knowledge_distillationTrue且数据含教师分数时还会额外叠加一项-mean(sum(log_softmax(logits) * softmax(teacher_scores)))蒸馏损失让模型同时向教师模型的软标签对齐——这正是pos_scores/neg_scores字段在训练数据中的用途。6.3 训练与合并的完整调用链DecoderOnlyRerankerRunner.run()runner.py的流程为创建输出目录 →trainer.train(resume_from_checkpoint...)断点续训 →trainer.save_model()保存 LoRA 权重 → 若save_merged_lora_model且为主进程则调用save_merged_model()合并导出。save_merged_model()会优先从output_dir直接加载 PEFT 权重失败时回退到find_largest_checkpoint()定位最大的checkpoint-step目录正则checkpoint-(\d)匹配见 load_model.py因此该合并机制同样支持从训练中断的中间 checkpoint 恢复导出。七、常见参数组合建议与注意事项内存紧张时保持use_lora True将target_modules收窄为q_proj k_proj v_proj o_proj并配合--gradient_checkpointing、--bf16与 DeepSpeed ZeRO 配置仓库提供 ds_stage0.json 与 ds_stage1.json进一步降低显存。长文本 rerank 场景query_max_len、passage_max_len需按实际文档长度上调示例中两者均为 512并建议--pad_to_multiple_of 8对齐计算单元开启--use_flash_attn前务必确认 GPU 环境支持 Flash Attention 2。需要产出推理可直接加载的权重务必设置--save_merged_lora_model True否则仅保存 LoRA 适配器推理侧需要额外处理 PEFT 合并。蒸馏训练训练数据需提供pos_scores/neg_scores字段且显式传--knowledge_distillation True否则该字段会被忽略。层间layerwise变体如需训练分层加权输出的 reranker可参考 layerwise.sh其模型参数在基类之上扩展了--start_layer、--head_multi、--head_type、--trust_remote_code等选项入口模块为FlagEmbedding.finetune.reranker.decoder_only.layerwise。如需深入某一参数的底层实现建议依次阅读 arguments.py、load_model.py、AbsArguments.py 与 AbsModeling.py对照 base.sh 的完整命令即可快速上手 decoder-only reranker 微调。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
FlagEmbedding 解码器架构 Reranker 微调模型参数完全指南：RerankerModelArguments 深度解析
FlagEmbedding 解码器架构 Reranker 微调模型参数完全指南RerankerModelArguments 深度解析【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本篇指南聚焦 FlagEmbedding 开源库中解码器Decoder-only架构重排序模型Reranker微调时的模型参数体系以 API 文档 arguments.rst 自动文档化的RerankerModelArguments类为核心骨架结合数据参数、训练参数与源码实现逐项展开。读完本文你将掌握每个参数的含义、默认值与底层作用机制能够独立配置出一条可运行的 decoder-only reranker 微调命令并理解 LoRA 参数高效微调、Flash Attention、LoRA 权重合并等关键机制在 FlagEmbedding 中的落地方式。一、认识 RerankerModelArguments解码器 Reranker 的模型参数入口在 FlagEmbedding 中解码器架构 reranker 的微调入口位于 FlagEmbedding/finetune/reranker/decoder_only/base/其 API 文档arguments.rst通过 Sphinx 的autoclass指令将 arguments.py 中的RerankerModelArguments类自动呈现为参数参考页。该类是所有 decoder-only reranker 微调脚本-m FlagEmbedding.finetune.reranker.decoder_only.base必需的模型侧参数容器用于控制基础模型Causal LM的加载方式是否启用 LoRA 参数高效微调及其超参注意力实现方式标准注意力 / Flash Attention已训练 LoRA 权重的加载与最终合并导出策略。RerankerModelArguments本身定义在 arguments.py 中它继承自抽象基类AbsRerankerModelArguments位于 FlagEmbedding/abc/finetune/reranker/AbsArguments.py因此完整的参数面由子类自有的 LoRA/注意力参数 基类继承的模型加载参数两部分构成。二、自有参数详解LoRA 微调与注意力机制以下是RerankerModelArguments直接声明的全部参数均以dataclass字段形式定义默认值取自源码参数类型默认值说明use_loraboolTrue是否使用 LoRA低秩参数高效训练微调模型lora_rankint64LoRA 低秩矩阵的秩rlora_alphafloat16LoRA 缩放超参alphalora_dropoutfloat0.1LoRA 模块的 dropout 比例target_modulesList[str][v_proj, q_proj, k_proj, gate_proj, down_proj, o_proj, up_proj]应用 LoRA 的目标模块注意力与 MLP 投影层modules_to_saveList[str]None除 LoRA 适配器外需要完整保存进最终检查点的模块列表use_flash_attnboolFalse是否使用 Flash Attention 训练from_peftstrNone从一个已存在的 PEFT/LoRA 检查点继续训练raw_peftList[str]None加载一个或多个原始 PEFT 权重并先合并进基础模型save_merged_lora_modelboolFalse训练结束后将 LoRA 权重合并进基础模型并保存完整模型2.1 LoRA 微调开关与超参use_lora / lora_rank / lora_alpha / lora_dropoutDecoder-only reranker 的基座通常是数十亿参数的 Causal LM全参微调显存与算力开销极大因此库默认use_loraTrue。在 load_model.py 的get_model()中当use_lora为真时会构造peft.LoraConfigpeft_config LoraConfig( task_typeTaskType.CAUSAL_LM, inference_modeFalse, rmodel_args.lora_rank, target_modulesmodel_args.target_modules, modules_to_savemodel_args.modules_to_save, lora_alphamodel_args.lora_alpha, lora_dropoutmodel_args.lora_dropout ) model get_peft_model(model, peft_config) model.print_trainable_parameters()三个超参的配合关系遵循 PEFT 通用规则lora_alpha与lora_rank的比值构成缩放因子实际缩放为alpha / ralpha越大新注入低秩分支对原权重的影响越强lora_dropout用于缓解过拟合。官方示例 base.sh 中使用的组合是--lora_rank 32 --lora_alpha 64可见实际训练中可根据数据规模在默认值基础上灵活调整。2.2 目标模块与模块保存target_modules / modules_to_savetarget_modules的默认值由default_target_modules()工厂函数生成见 arguments.py覆盖了典型 LLaMA 系架构的全部投影层注意力q_proj、k_proj、v_proj、o_proj前馈网络MLPgate_proj、down_proj、up_proj如果你的基座模型命名规范不同例如 Qwen/Mistral 变体需要显式传入--target_modules覆盖默认值。示例脚本中即传入了精简后的--target_modules q_proj k_proj v_proj o_proj仅对注意力层注入 LoRA 以进一步减少可训练参数量。modules_to_save用于指定除 LoRA 适配器外还需要完整保存的模块例如自定义的评分头或特殊 embedding这些模块的权重会原样存入最终 checkpoint不设置时默认None仅保存 LoRA 适配器权重。2.3 Flash Attentionuse_flash_attnuse_flash_attnTrue时load_model.py 会在加载 Causal LM 时传入attn_implementationflash_attention_2以加速长序列下的注意力计算并显著降低显存占用。该选项依赖硬件环境需要支持 Flash Attention 的 GPU 与配套 CUDA 环境不满足条件时应保持默认False。示例脚本base.sh与layerwise.sh均开启了该选项并配合--bf16使用。2.4 已训练权重的加载与合并from_peft / raw_peft / save_merged_lora_model这三个参数共同构成断点续训 权重合并的完整链路对应 load_model.py 中的加载逻辑from_peft指定一个已训练好的 PEFT 检查点路径通过PeftModel.from_pretrained(model, from_peft, is_trainableTrue)在其基础上继续训练raw_peft可传入一个或多个 PEFT 路径先逐个PeftModel.from_pretrained加载并merge_and_unload()合并进基础模型再决定是否叠加新的 LoRA 训练save_merged_lora_model训练完成后若为True且当前进程为主进程process_index 0runner 会调用 save_merged_model() 将 LoRA 适配器合并回基础模型并把完整权重与 tokenizer 保存到output_dir/merged_model目录方便后续直接用于推理而无需 PEFT 运行时。三、继承自抽象基类的模型加载参数RerankerModelArguments继承的AbsRerankerModelArguments定义于 FlagEmbedding/abc/finetune/reranker/AbsArguments.py提供了与基础模型、分词器加载相关的通用参数参数类型默认值说明model_name_or_pathstr必填初始化用的模型检查点名称或路径config_namestrNone与model_name不同时的预训练 config 名称或路径tokenizer_namestrNone与model_name不同时的分词器名称或路径cache_dirstrNone存放从模型中心下载的预训练模型缓存的目录trust_remote_codeboolFalse是否信任并执行远程代码自定义模型结构必需model_typestrencoder微调类型可选[encoder, decoder]use_fast_tokenizerboolTrue是否使用基于 Tokenizers 的快速分词器tokenstr环境变量HF_TOKEN访问受限模型时使用的鉴权 token在 runner.py 的load_tokenizer_and_model()中分词器优先取tokenizer_name否则回退到model_name_or_path并依次传入token、cache_dir、use_fast、trust_remote_code等参数model_type则用于在更上层路由到 decoder 分支官方示例统一传--model_type decoder。值得注意的实现细节加载时若 tokenizer 没有 pad tokenrunner 会依次尝试用unk_token、eod/im_start等特殊 token 兜底且统一将padding_side设为left左填充这是为了适配 decoder-only reranker 中query 与 passage 拼接后取末尾 token 输出的打分方式见下文第四节。四、配套参数体系数据参数与训练参数API 文档页虽然只自动文档化了RerankerModelArguments但在实际入口脚本main.py 中命令行参数由三组 dataclass 共同解析parser HfArgumentParser((RerankerModelArguments, AbsRerankerDataArguments, AbsRerankerTrainingArguments)) model_args, data_args, training_args parser.parse_args_into_dataclasses()4.1 数据参数 AbsRerankerDataArguments定义于 AbsArguments.py核心参数如下参数默认值说明train_dataNone必填训练数据路径支持多个数据需包含query、pos: List[str]、neg: List[str]字段cache_pathNone缓存数据存放目录train_group_size8每个 query 对应的文档组大小正样本 负样本数量query_max_len32query 分词后的最大长度超出截断passage_max_len128passage 分词后的最大长度max_len512总输入序列的最大长度pad_to_multiple_ofNone若设置将序列 padding 到该值的整数倍通常配合 8 以利用 Tensor Coremax_example_num_per_dataset100000000每个数据集最多使用的样本数query_instruction_for_rerankNonequery 侧的指令文本如A: query_instruction_format{}{}query 指令的拼接格式passage_instruction_for_rerankNonepassage 侧的指令文本如B: passage_instruction_format{}{}passage 指令拼接格式knowledge_distillationFalse是否启用知识蒸馏需要训练数据含pos_scores、neg_scoresshuffle_ratio0.0打乱文本 token 顺序的比例sep_token\n区分 query 与 passage 的分隔符其中train_data在__post_init__阶段会做存在性校验路径不存在会抛出FileNotFoundError指令格式中的\\n会被替换为真实换行符。官方示例 base.sh 使用了A: / B:指令前缀配合{}{}格式即典型的把 query 标记为 A、passage 标记为 B的 prompt 构造方式这正是解码器 reranker 的核心工作形式。4.2 训练参数 AbsRerankerTrainingArguments该类继承自transformers.TrainingArguments因此原生支持output_dir、learning_rate、bf16、num_train_epochs、per_device_train_batch_size、gradient_accumulation_steps、warmup_ratio、weight_decay、gradient_checkpointing、deepspeed、save_steps、logging_steps、resume_from_checkpoint等全部 HF 训练参数。其自身额外声明了一个字段参数默认值说明sub_batch_sizeNone训练子批次大小源码注释标明当前版本尚未实现在 AbsModeling.py 中通过class AbsRerankerTrainingArguments(TrainingArguments)定义使用时直接按 HF Trainer 习惯传入即可。五、完整可运行的微调示例以仓库自带的 examples/finetune/reranker/decoder_only/base.sh 为基础结合上文参数解析一份完整的 decoder-only reranker 微调命令如下torchrun多卡启动torchrun --nproc_per_node 2 \ -m FlagEmbedding.finetune.reranker.decoder_only.base \ --model_name_or_path BAAI/bge-reranker-v2-gemma \ --cache_dir $HF_HUB_CACHE \ --use_lora True \ --lora_rank 32 \ --lora_alpha 64 \ --use_flash_attn True \ --target_modules q_proj k_proj v_proj o_proj \ --save_merged_lora_model True \ --model_type decoder \ --train_data ../example_data/prompt_based/examples.jsonl \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ --knowledge_distillation True \ --query_instruction_for_rerank A: \ --query_instruction_format {}{} \ --passage_instruction_for_rerank B: \ --passage_instruction_format {}{} \ --output_dir ./test_decoder_only_base_bge-reranker-v2-gemma \ --overwrite_output_dir \ --learning_rate 2e-4 \ --bf16 \ --num_train_epochs 1 \ --per_device_train_batch_size 2 \ --gradient_accumulation_steps 1 \ --dataloader_drop_last True \ --warmup_ratio 0.1 \ --gradient_checkpointing \ --weight_decay 0.01 \ --deepspeed ../../ds_stage0.json \ --logging_steps 1 \ --save_steps 1000运行后训练产物保存在--output_dir下由于开启了--save_merged_lora_model还会额外生成merged_model/子目录内含合并后的完整模型权重与 tokenizer可直接交给 FlagEmbedding/inference 模块进行推理。六、从源码看参数如何影响模型行为6.1 打分方式为什么 decoder reranker 取末尾 token 的 Yes 概率CrossDecoderModel见 modeling.py在encode()中计算相关性分数的核心代码为outputs self.model(input_idsfeatures[input_ids], attention_maskfeatures[attention_mask], position_ids..., output_hidden_statesTrue) scores outputs.logits[:, -1, self.yes_loc]yes_loc在基类 AbsModeling.py 中通过self.tokenizer(Yes, add_special_tokensFalse)[input_ids][-1]获得即模型把打分建模为预测序列末尾出现 Yes 的概率。这解释了为何需要query_instruction_for_rerankA:、passage_instruction_for_rerankB:与sep_token构造 prompt也解释了 runner 中强制padding_sideleft的原因——只有左填充才能保证每个样本真正的最后一个 token 位置对齐。6.2 损失函数与知识蒸馏基类forward()AbsModeling.py将同一 batch 内的打分按train_batch_size分组grouped_logits ranker_logits.view(self.train_batch_size, -1)以每组第一项正样本为 target 计算交叉熵损失。当knowledge_distillationTrue且数据含教师分数时还会额外叠加一项-mean(sum(log_softmax(logits) * softmax(teacher_scores)))蒸馏损失让模型同时向教师模型的软标签对齐——这正是pos_scores/neg_scores字段在训练数据中的用途。6.3 训练与合并的完整调用链DecoderOnlyRerankerRunner.run()runner.py的流程为创建输出目录 →trainer.train(resume_from_checkpoint...)断点续训 →trainer.save_model()保存 LoRA 权重 → 若save_merged_lora_model且为主进程则调用save_merged_model()合并导出。save_merged_model()会优先从output_dir直接加载 PEFT 权重失败时回退到find_largest_checkpoint()定位最大的checkpoint-step目录正则checkpoint-(\d)匹配见 load_model.py因此该合并机制同样支持从训练中断的中间 checkpoint 恢复导出。七、常见参数组合建议与注意事项内存紧张时保持use_lora True将target_modules收窄为q_proj k_proj v_proj o_proj并配合--gradient_checkpointing、--bf16与 DeepSpeed ZeRO 配置仓库提供 ds_stage0.json 与 ds_stage1.json进一步降低显存。长文本 rerank 场景query_max_len、passage_max_len需按实际文档长度上调示例中两者均为 512并建议--pad_to_multiple_of 8对齐计算单元开启--use_flash_attn前务必确认 GPU 环境支持 Flash Attention 2。需要产出推理可直接加载的权重务必设置--save_merged_lora_model True否则仅保存 LoRA 适配器推理侧需要额外处理 PEFT 合并。蒸馏训练训练数据需提供pos_scores/neg_scores字段且显式传--knowledge_distillation True否则该字段会被忽略。层间layerwise变体如需训练分层加权输出的 reranker可参考 layerwise.sh其模型参数在基类之上扩展了--start_layer、--head_multi、--head_type、--trust_remote_code等选项入口模块为FlagEmbedding.finetune.reranker.decoder_only.layerwise。如需深入某一参数的底层实现建议依次阅读 arguments.py、load_model.py、AbsArguments.py 与 AbsModeling.py对照 base.sh 的完整命令即可快速上手 decoder-only reranker 微调。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
