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

【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 和命令行工具，极大地降低了个人或小型团队进行模型训练的门槛。我们将以经典的宝可梦图文数据集为例，一步步带您完成从环境搭建到模型评估的全过程。

LLaMA-Factory github链接
LLaMA-Factory官方文档

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.gitcd LLaMA-Factory# 2. 创建并激活 Conda 虚拟环境conda create -n llama_factory python=3.10conda 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 列表，每个元素代表一轮或多轮对话。图像通过特殊占位符 插入，并通过 images 字段关联。

[ { \"conversations\": [ { \"from\": \"human\", \"value\": \"详细描述一下这只宝可梦。\" }, { \"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 数据集，设置一个小的最大样本数（如 100）进行快速评估。
3. 开始评估：点击 开始。评估完成后会给出 BLEU、ROUGE 等量化指标。
   

6.2 对话测试

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

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

7. 最佳实践与进阶优化

7.1 数据为王

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

  \"这只宝可梦是什么颜色的？\"\"分析一下它的战斗特点。\"\"它看起来开心还是难过？\"

7.2 进阶调优技巧

• 混合数据集：在 WebUI 中可以同时选择多个数据集进行训练，这能提升模型的泛化能力。
• 使用 LoRA+：在“高级设置”中勾选 使用 LoRA+ 并设置 LoRA+ 学习率比例 为 16.0。LoRA+ 是一种改进算法，理论上能以相同的成本提升模型性能，值得尝试。
• 调整 LoRA 目标：如果发现模型在图像理解上出现问题，可以尝试仅微调语言部分。在 LoRA 作用模块 中手动填入 q_proj,v_proj,k_proj,o_proj 等，避免改动视觉编码器。

8. 总结

恭喜！通过本教程，您已经掌握了使用 LLaMA-Factory 对先进的多模态大模型进行 LoRA 微调的核心技能。成功的关键在于不断实践，记住以下黄金法则：

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

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