FlagEmbedding Decoder-Only 嵌入模型微调参数全解:DecoderOnlyEmbedderModelArguments 字段指南
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. 延伸阅读
- 参数类源码:arguments.py
- 参数消费与模型加载:load_model.py
- 抽象基类参数(数据/训练/模型公共字段):AbsArguments.py
- 微调入口脚本:main.py 与 init.py
- 完整可运行示例:base.sh(含
base_same_dataset.sh与 ICL 变体) - 模型/数据/训练三类参数如何在训练全流程中联动,可进一步阅读同目录下的 runner.py 与 modeling.py