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）對模型進行全面的評估和測試。
• 小步快跑：利用命令行覆蓋參數的特性，可以高效地進行超參數搜索和對比實驗。