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. 耐心的调试和对比实验是通往成功的必经之路。

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