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

1. 引言

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

本教程将详细介绍如何使用 llamafactory-cli 命令，结合精心编写的 .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 根目录下
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 文件，并根据我们的“宝可梦”任务进行修改。

修改后的完整配置如下：

# 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_name_or_path: 指向基础模型。
• lora_target: 设置为 all，对所有线性层应用 LoRA。
• dataset: 指向我们声明的宝可梦多模态数据集。
• template: 使用 qwen2_vl 专属模板。
• output_dir: 训练结果保存路径。
• bf16: 设为 true，以加速训练。

5. 执行训练

# 激活环境
conda activate llama_factory

# （可选）加速模型下载
export USE_MODELSCOPE_HUB=1

# 执行训练
llamafactory-cli train my_configs/qwen2.5vl_3b_pokemon_lora_sft.yaml

6. 模型评估与预测

6.1 在 MMLU Benchmark 上评估

6.1.1 创建配置文件

my_configs/eval_mmlu.yaml

# model
model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct
adapter_name_or_path: saves/qwen2.5vl-3b-lora-pokemon/sft-cli
image_max_pixels: 262144
video_max_pixels: 16384
trust_remote_code: true

# method
finetuning_type: lora

# dataset
task: mmlu_test
template: fewshot
lang: en
n_shot: 5

# output
save_dir: saves/qwen2.5vl-3b-lora-pokemon/eval-mmlu

# eval
batch_size: 4

6.1.2 执行评估

llamafactory-cli eval my_configs/eval_mmlu.yaml

6.1.3 查看评估结果

终端输出预期示例：

Average: 64.14
STEM: 60.47
Social Sciences: 74.85
Humanities: 56.62
Other: 68.32

6.2 自定义数据集上生成预测

6.2.1 创建预测配置文件

my_configs/predict_pokemon.yaml

# model
model_name_or_path: Qwen/Qwen2.5-VL-3B-Instruct
adapter_name_or_path: saves/qwen2.5vl-3b-lora-pokemon/sft-cli
image_max_pixels: 262144
video_max_pixels: 16384
trust_remote_code: true

# method
stage: sft
do_predict: true
finetuning_type: lora

# dataset
eval_dataset: pokemon_multimodal
dataset_dir: pokemon_sharegpt
template: qwen2_vl
cutoff_len: 4096
max_samples: 100
overwrite_cache: true
preprocessing_num_workers: 1

# output
output_dir: saves/qwen2.5vl-3b-lora-pokemon/predict
overwrite_output_dir: true

# eval
per_device_eval_batch_size: 1
predict_with_generate: true
report_to: none

6.2.2 执行预测

llamafactory-cli train my_configs/predict_pokemon.yaml

6.2.3 查看预测结果

all_results.json 示例：

{
  "predict_bleu-4": 46.05964000000001,
  "predict_rouge-1": 54.763231999999995,
  "predict_rouge-2": 27.012867999999997,
  "predict_rouge-l": 46.45837499999999,
  "predict_runtime": 92.8343,
  "predict_samples_per_second": 1.077,
  "predict_steps_per_second": 1.077
}

7. 总结

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

核心要点回顾：

• 命令行是王道：为了可复现性和自动化，命令行 + YAML 是更专业的选择。
• 模板优先：复制修改官方模板，事半功倍，并为不同任务（训练、评估、预测）创建独立的配置文件。
• 理解参数：认真理解 do_train, do_predict, task, adapter_name_or_path 等关键参数，它们决定了程序的行为。
• 评估是关键：我们不仅完成了模型的训练，还学会了如何使用标准基准（MMLU）和自定义数据集（计算 ROUGE/BLEU）对模型进行全面的评估和测试。
• 小步快跑：利用命令行覆盖参数的特性，可以高效地进行超参数搜索和对比实验。