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 等關鍵模塊。
• 小步快跑：利用命令行覆蓋參數，快速實驗。