【LLaMA-Factory 实战系列】二、WebUI 篇 - Qwen2.5-VL 多模态模型 LoRA 微调保姆级教程

- [1. 引言](#1. 引言)
- - [1.1 为什么选择 Qwen2.5-VL-3B-Instruct？](#1.1 为什么选择 Qwen2.5-VL-3B-Instruct？)
  - [1.2 环境要求](#1.2 环境要求)
- [2. 环境搭建](#2. 环境搭建)
- - [2.1 安装 LLaMA-Factory](#2.1 安装 LLaMA-Factory)
  - [2.2 验证安装](#2.2 验证安装)
- [3. 数据集准备与配置](#3. 数据集准备与配置)
- - [3.1 数据集结构](#3.1 数据集结构)
  - [3.2 数据格式](#3.2 数据格式)
  - [3.3 数据集声明](#3.3 数据集声明)
- [4. 启动 WebUI 并配置训练](#4. 启动 WebUI 并配置训练)
- - [4.1 启动命令](#4.1 启动命令)
  - [4.2 WebUI 训练配置详解](#4.2 WebUI 训练配置详解)
  - [4.3 开始训练](#4.3 开始训练)
- [5. 训练过程监控与故障排除](#5. 训练过程监控与故障排除)
- - [5.1 监控关键指标](#5.1 监控关键指标)
  - [5.2 常见问题与解决方案](#5.2 常见问题与解决方案)
- [6. 模型评估与测试](#6. 模型评估与测试)
- - [6.1 评估](#6.1 评估)
  - [6.2 对话测试](#6.2 对话测试)
- [7. 最佳实践与进阶优化](#7. 最佳实践与进阶优化)
- - [7.1 数据为王](#7.1 数据为王)
  - [7.2 进阶调优技巧](#7.2 进阶调优技巧)
- [8. 总结](#8. 总结)

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 虚拟环境。

bash 复制代码

# 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 验证安装

安装完成后，可以通过命令行工具检查版本以确认安装成功。

bash 复制代码

llamafactory-cli version

如果终端显示欢迎信息和版本号（如 Welcome to LLaMA Factory, version 0.9.x），则说明环境已准备就绪。

3. 数据集准备与配置

3.1 数据集结构

对于多模态任务，LLaMA-Factory 需要特定的文件结构。具体可参考我上一篇文章【LLaMA-Factory 实战系列】一、数据准备篇 - 从文本到多模态的完整流程：

text 复制代码

pokemon_sharegpt/
├── dataset_info.json     # 数据集配置文件，告诉 LLaMA-Factory 如何解析数据
├── images/               # 存放所有图片的文件夹
│   ├── pokemon_0001.png
│   ├── pokemon_0002.png
│   └── ...
└── pokemon_sharegpt.json # ShareGPT 格式的图文对话数据

3.2 数据格式

数据文件是一个 JSON 列表，每个元素代表一轮或多轮对话。图像通过特殊占位符 <image> 插入，并通过 images 字段关联。

json 复制代码

[
  {
    "conversations": [
      {
        "from": "human",
        "value": "详细描述一下这只宝可梦。<image>"
      },
      {
        "from": "gpt",
        "value": "这是皮卡丘，一只电属性的宝可梦，拥有黄色的皮毛和红色的脸颊。"
      }
    ],
    "images": ["images/pokemon_0001.png"]
  }
]

3.3 数据集声明

此文件是数据集的"身份证"，用于向 LLaMA-Factory 注册。

json 复制代码

{
  "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 环境变量。

bash 复制代码

# 使用 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 开始训练

预览命令 ：点击 Preview command 按钮，可以查看 WebUI 根据你的配置生成的等效命令行。这是一个很好的学习和检查方式。
开始训练 ：点击 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 标签页。

选择适配器 ：在 检查点路径 下拉框中，选择刚刚训练好的模型（位于 saves/... 目录下）。
配置评估 ：选择 pokemon_multimodoal 数据集，设置一个小的最大样本数 (Max samples) （如 100）进行快速评估。
开始评估 ：点击开始。评估完成后会给出 BLEU、ROUGE 等量化指标。

6.2 对话测试

这是检验模型效果最直观的方式。

切换到 Chat 标签页。
加载适配器 ：同样，在 适配器路径 中选中你的模型。
加载模型 ：点击 *加载模型 按钮，等待模型加载完成。
开始对话 ：
- 点击"上传文件"按钮，选择一张本地的宝可梦图片。
- 在输入框中输入提示词，如："请详细描述这只宝可梦的外形、属性和特点。"
- 观察模型的回答质量。
对比测试 ：要感受微调带来的提升，可以点击 卸载模型 ，然后不选择任何适配器 ，再次点击 加载模型 加载原始的 Qwen2.5-VL-3B-Instruct 模型，用同样的问题进行测试，对比效果差异。

7. 最佳实践与进阶优化

7.1 数据为王

质量优先：确保图文描述精准对应，高质量的标注远胜于海量低质量数据。
增加多样性：不仅是描述外观，可以加入属性、进化链、栖息地等多种信息。

数据增强 ：可以为同一张图编写不同角度的问题，如：

text 复制代码

"这只宝可梦是什么颜色的？<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 微调的核心技能。成功的关键在于不断实践，记住以下黄金法则：

高质量的数据是模型效果的基石。
合适的超参数是充分挖掘模型潜力的钥匙（从本教程的推荐值开始）。
耐心的调试和对比实验是通往成功的必经之路。

现在，去创造属于你自己的强大图文模型吧！