1. 引言

本教程將詳細介紹如何使用 LLaMA-Factory 的圖形化 WebUI 界面，對強大的開源多模態模型 Qwen2.5-VL-3B-Instruct 進行 LoRA 微調。LLaMA-Factory 是一個功能強大、簡單易用的一站式大模型微調平臺，它集成了多種主流的微調方法（如 LoRA、QLoRA、全量微調等），并通過簡潔的 WebUI 和命令行工具，極大地降低了個人或小型團隊進行模型訓練的門檻。我們將以經典的寶可夢圖文數據集為例，一步步帶您完成從環境搭建到模型評估的全過程。

1.1 為什么選擇 Qwen2.5-VL-3B-Instruct？

• 參數量適中：3B（30億）參數量，對消費級顯卡友好，顯存占用較低。
• 多模態能力強：原生支持圖像和文本的深度理解，能處理復雜的圖文交互任務。
• 中文支持優秀：阿里通義千問系列對中文的優化使其在國內場景中表現出色。
• 開源且可商用：模型權重開源，允許商業用途，社區活躍，生態豐富。

1.2 環境要求

經過驗證，以下是穩定運行所需的配置：

• GPU：至少 16GB 顯存。推薦使用 24GB 或更高顯存的顯卡（如 RTX 3090/4090）以獲得更佳的訓練體驗（例如更大的批量大小）。
• Python 版本：3.10 或 3.11。官方推薦 3.10，本教程也將基于此版本。
• CUDA 版本：11.8 或更高版本。這是 PyTorch 2.x 所推薦的穩定版本。

2. 環境搭建

2.1 安裝 LLaMA-Factory

首先，我們克隆項目并搭建一個干凈的 Python 虛擬環境。

# 1. 克隆項目倉庫
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory# 2. 創建并激活 Conda 虛擬環境
conda create -n llama_factory python=3.10
conda activate llama_factory# 3. 安裝核心依賴
# LLaMA-Factory 提供了便捷的安裝指令，包含torch和評估指標庫
pip install -e .[torch,metrics]

2.2 驗證安裝

安裝完成后，可以通過命令行工具檢查版本以確認安裝成功。

llamafactory-cli version

如果終端顯示歡迎信息和版本號（如 Welcome to LLaMA Factory, version 0.9.x），則說明環境已準備就緒。

3. 數據集準備與配置

3.1 數據集結構

對于多模態任務，LLaMA-Factory 需要特定的文件結構。具體可參考我上一篇文章【LLaMA-Factory 實戰系列】一、數據準備篇 - 從文本到多模態的完整流程：

pokemon_sharegpt/
├── dataset_info.json     # 數據集配置文件，告訴 LLaMA-Factory 如何解析數據
├── images/               # 存放所有圖片的文件夾
│   ├── pokemon_0001.png
│   ├── pokemon_0002.png
│   └── ...
└── pokemon_sharegpt.json # ShareGPT 格式的圖文對話數據

3.2 數據格式

數據文件是一個 JSON 列表，每個元素代表一輪或多輪對話。圖像通過特殊占位符 <image> 插入，并通過 images 字段關聯。

[{"conversations": [{"from": "human","value": "詳細描述一下這只寶可夢。<image>"},{"from": "gpt","value": "這是皮卡丘，一只電屬性的寶可夢，擁有黃色的皮毛和紅色的臉頰。"}],"images": ["images/pokemon_0001.png"]}
]

3.3 數據集聲明

此文件是數據集的“身份證”，用于向 LLaMA-Factory 注冊。

{"pokemon_multimodal": {"file_name": "pokemon_sharegpt.json","formatting": "sharegpt","columns": {"messages": "conversations","images": "images"}}
}

• pokemon_multimodal: 您為該數據集指定的唯一名稱，稍后將在 WebUI 中選擇。
• file_name: 對話數據文件的名稱。
• formatting: 指定數據格式為 sharegpt。
• columns: 映射 JSON 文件中的鍵到 LLaMA-Factory 的內部字段。

4. 啟動 WebUI 并配置訓練

4.1 啟動命令

為了加速模型下載，特別是對于國內用戶，建議設置 USE_MODELSCOPE_HUB 環境變量。

# 使用 ModelScope Hub 下載模型（國內網絡推薦）
export USE_MODELSCOPE_HUB=1# 啟動 WebUI 服務
llamafactory-cli webui

啟動后，終端會顯示訪問地址，通常是 http://0.0.0.0:7860。在瀏覽器中打開此地址。

4.2 WebUI 訓練配置詳解

我們將重點關注 Train (訓練) 標簽頁的配置。

---

模塊一：模型與方法
打開頁面后，可在語言下拉框中選擇zh，在模型名稱中搜索vl，即可看到相關的多模態模型，選擇其一，就會下載指定的模型權重到本地，這里我們選擇Qwen/Qwen2.5-VL-3B-Instruct：

參數	推薦值	說明
語言	zh	將界面切換為中文，方便操作。
模型名稱	Qwen/Qwen2.5-VL-3B-Instruct	LLaMA-Factory 會自動從 HuggingFace 或 ModelScope 下載。
模型路徑	默認	若已有本地模型，可填寫絕對路徑。
微調方法	LoRA	低秩適應微調，在效果和資源消耗之間取得了最佳平衡，是目前的主流選擇。
量化等級	none (不量化)	4-bit 量化可大幅節省顯存，但對模型精度有輕微影響。初次訓練建議不量化。
對話模板	qwen2_vl	至關重要。必須與模型（Qwen2.5-VL）嚴格匹配，否則模型無法正確理解輸入。

---

模塊二：訓練設置

參數	推薦值	說明
訓練階段	Supervised Fine-Tuning	監督微調，適用于我們準備的“問答”式標注數據。
數據目錄	./pokemon_sharegpt	指向您準備好的數據集文件夾。
數據集	pokemon_multimodal	選中我們剛才在 dataset_info.json 中定義的數據集名稱。
截斷長度	4096	模型能處理的最大序列長度。對于圖文模型，建議不低于 2048 以確保圖像編碼有足夠空間。
學習率	2e-4	這是 LoRA 微調 3B 級別模型的黃金學習率。如果 Loss 不下降可升至 3e-4，若震蕩則降至 1e-4。
訓練輪數	3	對于中小規模數據集（< 10k 條），3-5 輪通常足夠。過多輪次可能導致過擬合。
批處理大小	2	每張 GPU 一次處理的樣本數。受顯存限制，24GB 顯存可嘗試 2-4，16GB 建議 1-2。
梯度累積	8	“模擬”大批量訓練的技巧。有效批量 = 批處理大小 × 梯度累積。這里有效批量為 16，是公認的穩定值。
計算類型	bf16	強烈推薦。適用于新架構顯卡（A100, RTX 30/40系），數值穩定性優于 fp16。
學習率調節器	cosine	余弦退火調度器，能使學習率平滑下降，有助于模型收斂到更優的點。
驗證集比例	0.1	從訓練集中劃分 10% 的數據用于驗證，以監控模型是否過擬合。
輸出目錄	saves/qwen25-vl-pokemon-lora	保存 LoRA 權重、日志和訓練圖表的文件夾。
日志間隔	10	每訓練 10 步在控制臺和日志文件中輸出一次 Loss 等信息。
保存間隔	500	每訓練 500 步保存一次模型權重（checkpoint）。
LoRA 秩	64	LoRA 矩陣的維度。越大，可訓練參數越多，擬合能力越強，但顯存占用也越高。64 是一個很好的平衡點。
LoRA 縮放系數	128	通常設為 rank 的 2倍，這是一個廣泛驗證過的有效配置。
LoRA 隨機丟棄	0.1	在 LoRA 模塊中加入 Dropout，能有效防止過擬合，增強模型泛化能力。
LoRA 作用模塊	all	將 LoRA 應用于模型的所有線性層。對于初學者來說，這是最簡單且效果不錯的選擇。

---

4.3 開始訓練

1. 預覽命令：點擊 Preview command 按鈕，可以查看 WebUI 根據你的配置生成的等效命令行。這是一個很好的學習和檢查方式。
2. 開始訓練：點擊 Start 按鈕，訓練正式開始。下方的日志窗口會實時滾動輸出訓練信息。

5. 訓練過程監控與故障排除

5.1 監控關鍵指標

• Loss：最重要的指標。你應該觀察到 loss 值隨著訓練進行而持續下降，并在訓練后期趨于平穩。
• Learning Rate：會根據選擇的 cosine 調度器從初始值 2e-4 平滑下降。
• Loss 曲線圖：訓練完成后，在輸出目錄（saves/qwen25-vl-pokemon-lora）下會生成 training_loss.png。一條健康的曲線應平滑下降并收斂。

5.2 常見問題與解決方案

問題	可能原因	解決方案
CUDA out of memory	批量大小過大或截斷長度過長。	1. 降低批處理大小 至 1。 2. 如仍溢出，降低 LoRA 秩 至 32。 3. 最終手段：降低截斷長度。
Loss 不下降或上升	學習率過低或數據有問題。	1. 提高學習率 至 3e-4。 2. 仔細檢查數據集格式和內容。
Loss 劇烈震蕩	學習率過高。	降低學習率 至 1e-4。
訓練速度過慢	硬件限制或配置問題。	1. 確認已安裝 flash-attn。 2. 適當減少梯度累積步數。

6. 模型評估與測試

6.1 評估

訓練完成后，切換到 Evaluate 標簽頁。

1. 選擇適配器：在 檢查點路徑 下拉框中，選擇剛剛訓練好的模型（位于 saves/... 目錄下）。
2. 配置評估：選擇 pokemon_multimodoal 數據集，設置一個小的最大樣本數 (Max samples)（如 100）進行快速評估。
3. 開始評估：點擊 開始。評估完成后會給出 BLEU、ROUGE 等量化指標。
   

6.2 對話測試

這是檢驗模型效果最直觀的方式。

1. 切換到 Chat 標簽頁。
2. 加載適配器：同樣，在 適配器路徑 中選中你的模型。
3. 加載模型：點擊 *加載模型 按鈕，等待模型加載完成。
4. 開始對話：
   • 點擊“上傳文件”按鈕，選擇一張本地的寶可夢圖片。
   • 在輸入框中輸入提示詞，如：“請詳細描述這只寶可夢的外形、屬性和特點。”
   • 觀察模型的回答質量。
5. 對比測試：要感受微調帶來的提升，可以點擊 卸載模型，然后不選擇任何適配器，再次點擊 加載模型 加載原始的 Qwen2.5-VL-3B-Instruct 模型，用同樣的問題進行測試，對比效果差異。
   

7. 最佳實踐與進階優化

7.1 數據為王

• 質量優先：確保圖文描述精準對應，高質量的標注遠勝于海量低質量數據。
• 增加多樣性：不僅是描述外觀，可以加入屬性、進化鏈、棲息地等多種信息。
• 數據增強：可以為同一張圖編寫不同角度的問題，如：

  "這只寶可夢是什么顏色的？<image>"
  "分析一下它的戰斗特點。<image>"
  "它看起來開心還是難過？<image>"
  

7.2 進階調優技巧

• 混合數據集：在 WebUI 中可以同時選擇多個數據集進行訓練，這能提升模型的泛化能力。
• 使用 LoRA+：在“高級設置”中勾選 使用 LoRA+ (Use LoRA+) 并設置 LoRA+ 學習率比例 (LoRA+ lr ratio) 為 16.0。LoRA+ 是一種改進算法，理論上能以相同的成本提升模型性能，值得嘗試。
• 調整 LoRA 目標：如果發現模型在圖像理解上出現問題，可以嘗試僅微調語言部分。在 LoRA 作用模塊 中手動填入 q_proj,v_proj,k_proj,o_proj 等，避免改動視覺編碼器。

8. 總結

恭喜！通過本教程，您已經掌握了使用 LLaMA-Factory 對先進的多模態大模型進行 LoRA 微調的核心技能。成功的關鍵在于不斷實踐，記住以下黃金法則：

1. 高質量的數據是模型效果的基石。
2. 合適的超參數是充分挖掘模型潛力的鑰匙（從本教程的推薦值開始）。
3. 耐心的調試和對比實驗是通往成功的必經之路。

現在，去創造屬于你自己的強大圖文模型吧！