【LLaMA-Factory 实战系列】二、WebUI 篇 - Qwen2.5-VL 多模态模型 LoRA 微调保姆级教程
- 1. 引言
- 1.1 为什么选择 Qwen2.5-VL-3B-Instruct？
- 1.2 环境要求
- 2. 环境搭建
- 2.1 安装 LLaMA-Factory
- 2.2 验证安装
- 3. 数据集准备与配置
- 3.1 数据集结构
- 3.2 数据格式
- 3.3 数据集声明
- 4. 启动 WebUI 并配置训练
- 4.1 启动命令
- 4.2 WebUI 训练配置详解
- 4.3 开始训练
- 5. 训练过程监控与故障排除
- 5.1 监控关键指标
- 5.2 常见问题与解决方案
- 6. 模型评估与测试
- 6.1 评估
- 6.2 对话测试
- 7. 最佳实践与进阶优化
- 7.1 数据为王
- 7.2 进阶调优技巧
- 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 虚拟环境。
# 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 开始训练
- 预览命令：点击 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 数据为王
- 质量优先：确保图文描述精准对应，高质量的标注远胜于海量低质量数据。
- 增加多样性：不仅是描述外观，可以加入属性、进化链、栖息地等多种信息。
- 数据增强：可以为同一张图编写不同角度的问题，如：
"这只宝可梦是什么颜色的？<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 微调的核心技能。成功的关键在于不断实践，记住以下黄金法则：
- 高质量的数据是模型效果的基石。
- 合适的超参数是充分挖掘模型潜力的钥匙（从本教程的推荐值开始）。
- 耐心的调试和对比实验是通往成功的必经之路。
现在，去创造属于你自己的强大图文模型吧！
