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

原创2026-09-14 21:07:491,870 阅读
文章标签:人工智能RAGNLP微调模型评测

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

本指南以 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_args=model_args, data_args=data_args, training_args=training_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_name None str 当配置文件与模型权重路径不同时,指定预训练 config 的名称或路径
tokenizer_name None str 当分词器与模型权重路径不同时,指定预训练 tokenizer 的名称或路径
cache_dir None str 存放从远端下载的预训练模型的本地缓存目录
trust_remote_code False bool 是否信任并执行模型仓库中的自定义远程代码
use_fast_tokenizer True bool 是否使用基于 🤗 Tokenizers 库的快速分词器
token os.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_rank 64 LoRA 分解矩阵的秩 r,决定新增可训练参数的数量
lora_alpha 16 LoRA 缩放超参数 alpha,实际缩放因子为 alpha / r
lora_dropout 0.1 LoRA 模块的 dropout 比率

这些字段在 load_model.py 中直接映射到 PEFT 的 LoraConfig:

peft_config = LoraConfig(
    task_type=TaskType.FEATURE_EXTRACTION,
    inference_mode=False,
    r=model_args.lora_rank,
    target_modules=target_modules,
    modules_to_save=model_args.modules_to_save,
    lora_alpha=model_args.lora_alpha,
    lora_dropout=model_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 32 + lora_alpha 64(缩放因子 2),你可以根据显存与效果需求调整,但应保持两者比例合理。

3.3 target_modules:LoRA 注入的目标模块

  • 默认值:['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_proj

3.4 modules_to_save

  • 默认值:None
  • 语义:除 LoRA 注入模块外,额外以"模块整体保存"方式训练的参数模块(PEFT 的 modules_to_save 选项)。典型用途是让某些非投影层(如特定 head)在训练中保持为可训练并随检查点保存。

3.5 from_peft / raw_peft:从既有 LoRA 权重继续训练

字段 默认值 语义
from_peft None 指定一个 PEFT 检查点路径,以其初始化模型并继续训练
raw_peft None 指定包含 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_trainable=True 方式加载 PEFT 权重继续训练;
  • 两者都为空且 use_lora=True:走新建 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>{}\n<query>{}')引用,形成检索指令的定界符。追加 token 会触发词表扩展,对应源码中 resize 与 resize_token_embeddings 机制(详见第 5 节)。

4.2 use_slow_tokenizer

  • 默认值:False
  • 语义:传入后使用慢速分词器(非 🤗 Tokenizers 库后端)。默认 False 意味着优先使用快速分词器,与基类的 use_fast_tokenizer=True 默认行为保持一致。

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.py):

if resize:
    model.resize_token_embeddings(resize_tokens)
    os.makedirs(os.path.join(output_dir, 'embedding'), exist_ok=True)
    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_model:
model = 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>{}\n<query>{}' \
"

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_name None 基类继承
tokenizer_name None 基类继承
cache_dir None 基类继承
trust_remote_code False 基类继承
use_fast_tokenizer True 基类继承
token HF_TOKEN 环境变量 基类继承
peft_model_path '' LoRA
use_lora True LoRA
lora_rank 64 LoRA
lora_alpha 16 LoRA
lora_dropout 0.1 LoRA
target_modules 7 个 q/k/v/o/gate/down/up 投影 LoRA
modules_to_save None LoRA
from_peft None LoRA 续训
raw_peft None LoRA 合并加载
additional_special_tokens None 词表扩展
use_flash_attn False 性能优化
use_slow_tokenizer False 分词器
save_merged_lora_model False 合并导出
only_merge_lora_model False 合并导出

9. 延伸阅读

登录后查看全文
FlagEmbedding