十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

FlagEmbedding Decoder-Only 嵌入模型微调参数全解:DecoderOnlyEmbedderModelArguments 字段指南

FlagEmbedding Decoder-Only 嵌入模型微调参数全解:DecoderOnlyEmbedderModelArguments 字段指南 FlagEmbedding Decoder-Only 嵌入模型微调参数全解DecoderOnlyEmbedderModelArguments 字段指南【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding本指南以 FlagEmbedding 官方 API 文档中DecoderOnlyEmbedderModelArguments参数类为骨架系统讲解基于 decoder-only仅解码器架构的嵌入模型在参数高效微调LoRA场景下全部模型级参数的语义、默认值与底层生效逻辑。读者将掌握如何为bge-multilingual-gemma2等 LLM 型嵌入模型配置 LoRA 微调命令理解参数在模型加载、词表扩展、LoRA 注入与合并保存全流程中的作用并可直接对照仓库源码逐项验证每个参数的调用关系。1. 参数类定位从文档 autoclass 到源码实现官方 API 文档页面 arguments.rst 中仅有一段 Sphinx 自动文档指令Arguments .. autoclass:: FlagEmbedding.finetune.embedder.decoder_only.base.DecoderOnlyEmbedderModelArguments该指令对应的实体定义于 arguments.py它继承自抽象基类AbsEmbedderModelArguments定义于 AbsArguments.py并通过init.py 以DecoderOnlyEmbedderModelArguments名称对外导出。从源码结构看该参数类与同一包下的DecoderOnlyEmbedderDataArguments即AbsEmbedderDataArguments的别名、DecoderOnlyEmbedderTrainingArguments即AbsEmbedderTrainingArguments的别名共同构成 decoder-only 基类微调入口的三大参数集合。入口脚本main.py 使用 Hugging Face 的HfArgumentParser一次性解析三类参数再交给DecoderOnlyEmbedderRunner驱动训练parser HfArgumentParser(( DecoderOnlyEmbedderModelArguments, DecoderOnlyEmbedderDataArguments, DecoderOnlyEmbedderTrainingArguments )) model_args, data_args, training_args parser.parse_args_into_dataclasses() runner DecoderOnlyEmbedderRunner(model_argsmodel_args, data_argsdata_args, training_argstraining_args) runner.run()因此理解DecoderOnlyEmbedderModelArguments的全部字段就等同于理解 decoder-only 嵌入模型微调命令中model_args段的全部合法开关。2. 继承自 AbsEmbedderModelArguments 的通用模型参数在进入 decoder-only 专属字段之前必须先掌握从 AbsArguments.py 继承的基础字段它们是所有嵌入模型微调共用的字段默认值类型说明model_name_or_path无必填str用于初始化的模型检查点路径或 Hugging Face 模型 ID。加载时若路径含.ckpt会自动按 TensorFlow 权重处理见from_tf判断config_nameNonestr当配置文件与模型权重路径不同时指定预训练 config 的名称或路径tokenizer_nameNonestr当分词器与模型权重路径不同时指定预训练 tokenizer 的名称或路径cache_dirNonestr存放从远端下载的预训练模型的本地缓存目录trust_remote_codeFalsebool是否信任并执行模型仓库中的自定义远程代码use_fast_tokenizerTruebool是否使用基于 Tokenizers 库的快速分词器tokenos.getenv(HF_TOKEN, None)str访问受控模型如 gated model时使用的 Hugging Face token默认从环境变量HF_TOKEN读取其中model_name_or_path是唯一没有默认值、必须显式指定的字段。在 load_model.py 中若既没有config_name也没有model_name_or_path会直接抛出ValueError提示不允许从零实例化新 config。3. LoRA 参数高效微调核心字段decoder-only 架构的嵌入模型参数量庞大全量微调成本过高因此该参数类以 LoRA 为核心默认方案。相关字段定义于 arguments.py。3.1 use_lora是否启用 LoRA默认值True语义传入后使用 LoRA低秩参数高效训练微调模型置为False则进入全参数微调路径。3.2 lora_rank / lora_alpha / lora_dropout字段默认值语义lora_rank64LoRA 分解矩阵的秩r决定新增可训练参数的数量lora_alpha16LoRA 缩放超参数alpha实际缩放因子为alpha / rlora_dropout0.1LoRA 模块的 dropout 比率这些字段在 load_model.py 中直接映射到 PEFT 的LoraConfigpeft_config LoraConfig( task_typeTaskType.FEATURE_EXTRACTION, inference_modeFalse, rmodel_args.lora_rank, target_modulestarget_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()注意此处task_type被固定为FEATURE_EXTRACTION这与嵌入模型提取特征而非生成文本的定位一致。官方示例 base.sh 中bge-multilingual-gemma2的常用组合为lora_rank 32lora_alpha 64缩放因子 2你可以根据显存与效果需求调整但应保持两者比例合理。3.3 target_modulesLoRA 注入的目标模块默认值[v_proj, q_proj, k_proj, gate_proj, down_proj, o_proj, up_proj]语义应用 LoRA 的目标模块列表。默认值由default_target_modules()工厂函数生成见 arguments.py覆盖了典型 LLM 的全部注意力投影q/k/v/o与 MLP 投影gate/down/up即默认对所有线性层注入 LoRA。命令行传入时需用空格分隔多个模块名例如示例脚本中的写法--target_modules q_proj k_proj v_proj o_proj gate_proj down_proj up_proj3.4 modules_to_save默认值None语义除 LoRA 注入模块外额外以模块整体保存方式训练的参数模块PEFT 的modules_to_save选项。典型用途是让某些非投影层如特定 head在训练中保持为可训练并随检查点保存。3.5 from_peft / raw_peft从既有 LoRA 权重继续训练字段默认值语义from_peftNone指定一个 PEFT 检查点路径以其初始化模型并继续训练raw_peftNone指定包含embedding/emb.pth与 LoRA 权重的原始 PEFT 目录加载后立即merge_and_unload()合并回基座二者在 load_model.py 中有明确的分支逻辑raw_peft不为空时先加载embedding/emb.pth覆盖输入嵌入再PeftModel.from_pretrained并merge_and_unload()得到合并后的完整模型from_peft不为空时若该目录含embedding/子目录则先恢复词嵌入再以is_trainableTrue方式加载 PEFT 权重继续训练两者都为空且use_loraTrue走新建 LoRA 配置的路径。3.6 peft_model_path默认值语义用于初始化的 PEFT 模型检查点路径。该字段在get_model主流程中未直接使用从字段命名与from_peft的并存关系可以推断它是面向外部调用方提供的 PEFT 权重入口之一实际训练续接主要依赖from_peft/raw_peft。4. 词表与分词相关字段4.1 additional_special_tokens默认值None支持nargs: 可传入多个 token语义为分词器追加的特殊 token。在示例脚本中用于注入指令模板 token--additional_special_tokens instruct query这些 token 随后被query_instruction_format如instruct{}\nquery{}引用形成检索指令的定界符。追加 token 会触发词表扩展对应源码中resize与resize_token_embeddings机制详见第 5 节。4.2 use_slow_tokenizer默认值False语义传入后使用慢速分词器非 Tokenizers 库后端。默认False意味着优先使用快速分词器与基类的use_fast_tokenizerTrue默认行为保持一致。4.3 use_flash_attn默认值False语义传入后训练时使用 Flash Attention 加速。在 load_model.py 中映射为 Transformers 的注意力实现attn_implementation flash_attention_2 if model_args.use_flash_attn else None开启前请确认 GPU 型号与已安装的 flash-attn 库版本支持flash_attention_2实现。5. 词表扩展与嵌入恢复机制resize 路径理解additional_special_tokens的完整生命周期需要进入get_model的resize分支load_model.pyif resize: model.resize_token_embeddings(resize_tokens) os.makedirs(os.path.join(output_dir, embedding), exist_okTrue) torch.save(model.embed_tokens, os.path.join(output_dir, embedding, emb.pth))即扩展词表 → 将新的embed_tokens权重保存为output_dir/embedding/emb.pth。该文件在后续流程中被反复使用raw_peft/from_peft路径通过model.set_input_embeddings(torch.load(...))恢复扩展后的嵌入保存合并模型时load_model.py若存在embedding/emb.pth会恢复嵌入并把model.config.vocab_size修正为分词器实际长度。这也是为什么示例脚本中追加instruct、query特殊 token 后必须配合嵌入保存/恢复机制才能保证词表扩展在续训与合并导出阶段不被丢失。6. LoRA 合并与模型导出字段6.1 save_merged_lora_model默认值False语义传入后训练结束把 LoRA 模块合并进基座并保存完整模型。该开关在get_model之外的保存阶段由 Runner 消费最终调用 save_merged_modelmodel PeftModel.from_pretrained(model, output_dir) model model.merge_and_unload() model.save_pretrained(os.path.join(output_dir, merged_model))该函数优先尝试从output_dir直接加载 PEFT 权重若失败则通过find_largest_checkpoint回退到最大编号的checkpoint-*子目录。合并后的模型与分词器统一保存到merged_model/子目录。示例脚本中显式开启--save_merged_lora_model True。6.2 only_merge_lora_model默认值False语义传入后仅执行 LoRA 合并与保存不再进行训练。其 help 文本与save_merged_lora_model完全一致从字段设计与并存关系可以推断该开关用于只合并、不训练的纯导出场景适合对已有训练检查点做一次性合并导出。6.3 被注释的 low_cpu_mem_usage源码中以注释形式保留了low_cpu_mem_usage字段arguments.py其设计意图是先创建空壳模型、加载预训练权重时再物化参数以降低 LLM 加载时间与 RAM 占用。当前版本未启用该开关意味着本类目前不支持该选项传参时不应使用。7. 实战完整 decoder-only 微调命令中的 model_args 段结合官方示例 base.sh一个基于bge-multilingual-gemma2的 decoder-only 嵌入模型微调命令中model_args段的完整写法如下model_args\ --model_name_or_path BAAI/bge-multilingual-gemma2 \ --cache_dir $HF_HUB_CACHE \ --use_lora True \ --lora_rank 32 \ --lora_alpha 64 \ --target_modules q_proj k_proj v_proj o_proj gate_proj down_proj up_proj \ --additional_special_tokens instruct query \ --save_merged_lora_model True \ 对应的data_args段负责指令格式与数据组织data_args\ --train_data $train_data \ --train_group_size 8 \ --query_max_len 512 \ --passage_max_len 512 \ --pad_to_multiple_of 8 \ --query_instruction_for_retrieval Given a query, retrieve passages that are relevant to the query. \ --query_instruction_format instruct{}\nquery{} \ training_args段则补充训练超参与池化方式decoder-only 嵌入通常用last_token池化training_args\ --output_dir ./test_decoder_only_base_bge-multilingual-gemma2 \ --learning_rate 1e-4 \ --fp16 \ --num_train_epochs $num_train_epochs \ --per_device_train_batch_size $per_device_train_batch_size \ --gradient_checkpointing \ --deepspeed ../../ds_stage1.json \ --negatives_cross_device \ --temperature 0.02 \ --sentence_pooling_method last_token \ --normalize_embeddings True \ --kd_loss_type m3_kd_loss \ 最终通过torchrun启动torchrun --nproc_per_node $num_gpus \ -m FlagEmbedding.finetune.embedder.decoder_only.base \ $model_args $data_args $training_args需要说明的是data_args与training_args中的字段如sentence_pooling_method、temperature、negatives_cross_device、kd_loss_type等定义于抽象参数类 AbsArguments.py不属于本文主角DecoderOnlyEmbedderModelArguments但它们在训练数据读取、相似度打分与损失计算中与模型参数协同生效属于 decoder-only 微调完整命令的必要组成部分。8. 快速参考字段总表与默认值字段默认值类别model_name_or_path必填基类继承config_nameNone基类继承tokenizer_nameNone基类继承cache_dirNone基类继承trust_remote_codeFalse基类继承use_fast_tokenizerTrue基类继承tokenHF_TOKEN环境变量基类继承peft_model_pathLoRAuse_loraTrueLoRAlora_rank64LoRAlora_alpha16LoRAlora_dropout0.1LoRAtarget_modules7 个 q/k/v/o/gate/down/up 投影LoRAmodules_to_saveNoneLoRAfrom_peftNoneLoRA 续训raw_peftNoneLoRA 合并加载additional_special_tokensNone词表扩展use_flash_attnFalse性能优化use_slow_tokenizerFalse分词器save_merged_lora_modelFalse合并导出only_merge_lora_modelFalse合并导出9. 延伸阅读参数类源码arguments.py参数消费与模型加载load_model.py抽象基类参数数据/训练/模型公共字段AbsArguments.py微调入口脚本main.py 与init.py完整可运行示例base.sh含base_same_dataset.sh与 ICL 变体模型/数据/训练三类参数如何在训练全流程中联动可进一步阅读同目录下的 runner.py 与 modeling.py【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表