【LLaMA-Factory 实战系列】三、命令行篇 - YAML 配置与高效微调 Qwen2.5-VL

1. 引言

在上一篇教程【LLaMA-Factory 实战系列】二、WebUI 篇 - Qwen2.5-VL 多模态模型 LoRA 微调保姆级教程 中，我们通过图形化界面成功对 Qwen2.5-VL-3B-Instruct 模型进行了 LoRA 微调。WebUI 固然直观便捷，但在许多场景下，命令行（CLI）配合配置文件的方式更具优势。

本教程将详细介绍如何使用 llamafactory-cli train 命令，结合精心编写的 .yaml 配置文件，来微调我们的宝可梦图文识别模型。这种方式不仅是可复现研究和自动化实验的基石，也是在没有图形化界面的远程服务器上进行训练的标准做法。

2. 为什么从 WebUI 转向命令行？

如果您已经熟悉了 WebUI，可能会问：为什么还要学习命令行？

• 可复现性：一个 .yaml 文件完整地记录了模型、数据集、超参数等所有配置。您可以将它与代码一同提交到 Git，任何人都能用完全相同的设置复现您的实验结果。
• 自动化与批处理：您可以通过编写 Shell 脚本，轻松地启动一系列不同超参数的训练任务，而无需手动在 WebUI 上逐个点击。这对于调参和对比实验至关重要。
• 版本控制：对 .yaml 文件的每一次修改都可以被 Git 追踪，让您清晰地看到每次实验的配置变动。
• 远程服务器友好：在只有 SSH 终端的服务器上，命令行是唯一也是最高效的交互方式。

3. 准备工作（回顾）

在开始之前，请确保您已经完成了前两篇教程中的准备工作：

• 环境已搭建：已按照教程安装 LLaMA-Factory 并创建了 llama_factory conda 环境。
• 数据集已备好：pokemon_sharegpt 数据集已按要求放在 LLaMA-Factory 的根目录下，目录结构如下：

LLaMA-Factory/
├── pokemon_sharegpt/
│   ├── dataset_info.json
│   ├── images/
│   └── pokemon_sharegpt.json
└── ... (其他项目文件)

• 数据集已声明：dataset_info.json 文件已正确配置，将我们的数据集命名为 pokemon_multimodal。

4. 核心：创建并理解训练配置文件

LLaMA-Factory 在 examples/ 目录下提供了丰富的配置文件模板。我们的策略是：找到一个最相似的模板，复制并修改它，而不是从零开始。

4.1 选择并复制基础模板

根据我们的目标（使用 LoRA 微调 Qwen2.5-VL），最合适的模板是：

examples/train_lora/qwen2.5vl_lora_sft.yaml

我们来创建一个专门存放我们自己配置的目录，并把模板复制过去。

# 确保在 LLaMA-Factory-main 根目录下
mkdir -p my_configs
cp examples/train_lora/qwen2.5vl_lora_sft.yaml my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml

这样做的好处是不污染官方示例，并且能让我们的配置一目了然。

4.2 逐一解析与修改配置文件

打开 my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml 文件，并根据我们的“宝可梦”任务进行修改。

修改后的完整配置如下：

# model
model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct
image_max_pixels: 262144
video_max_pixels: 16384
trust_remote_code: true# method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.1
lora_target: all# dataset
dataset: pokemon_multimodal
dataset_dir: pokemon_sharegpt
template: qwen2_vl
cutoff_len: 4096
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16
dataloader_num_workers: 4# output
output_dir: saves/qwen2.5vl-3b-lora-pokemon/sft-cli
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
save_only_model: false
report_to: none# train
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
learning_rate: 2.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000
resume_from_checkpoint: null# eval
val_size: 0.1
per_device_eval_batch_size: 2
eval_strategy: steps
eval_steps: 100

4.3 参数详解与修改说明

model 模块

参数	修改后	说明
model_name_or_path	Qwen/Qwen2.5-VL-3B-Instruct	使用 Hugging Face 的3B模型
image_max_pixels	262144	图像最大像素
trust_remote_code	true	允许在使用 Hugging Face Transformers 库时控制是否信任从远程下载的配置文件

method 模块

参数	修改后	说明
stage	sft	监督微调
finetuning_type	lora	使用 LoRA 微调
lora_rank	64	LoRA 矩阵秩
lora_alpha	128	通常为 rank 的 2 倍
lora_dropout	0.1	加入 Dropout
lora_target	all	应用于所有线性层

dataset 模块

参数	修改后	说明
dataset	pokemon_multimodal	数据集名称
dataset_dir	pokemon_sharegpt	数据集根目录
template	qwen2_vl	对应 Qwen 模型的模板
max_samples	10000	单个数据集中最大可加载的样本数

output 模块

参数	修改后	说明
output_dir	saves/qwen2.5vl-3b-lora-pokemon/sft-cli	输出目录
logging_steps	10	日志打印频率
save_steps	500	模型保存频率
plot_loss	true	绘制训练曲线

train 模块

参数	修改后	说明
per_device_train_batch_size	2	单卡批次大小
gradient_accumulation_steps	8	有效 batch size = 16
learning_rate	2.0e-4	微调推荐学习率
bf16	true	建议启用混合精度训练

eval 模块

参数	修改后	说明
val_size	0.1	验证集划分
eval_strategy	steps	按步数验证
eval_steps	100	每100步验证一次

5. 执行训练

# 激活环境
conda activate llama_factory# （可选）加速模型下载
export USE_MODELSCOPE_HUB=1# 执行训练
llamafactory-cli train my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml

命令行参数覆盖

llamafactory-cli train my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml \--learning_rate 1e-4 \--output_dir saves/qwen2.5vl-3b-lora-pokemon/sft-lr-1e-4

6. 推理与测试

llamafactory-cli chat my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml

该命令会自动加载模型、适配器、模板，一站式部署后进入对话测试。

7. 总结

🎉 恭喜！您已经掌握了使用 LLaMA-Factory 命令行和 YAML 配置进行模型微调的完整流程。

核心要点回顾：

• 命令行是王道：为了可复现性和自动化，命令行 + YAML 是更专业的选择。
• 模板优先：复制修改官方模板，事半功倍。
• 理解参数：认真理解 model, dataset, method, train 等关键模块。
• 小步快跑：利用命令行覆盖参数，快速实验。