LLaMA Factory 多模态微调实践

2. 教程数据集预处理流程

下载并部署数据集后，需执行以下检查步骤，避免训练报错：

# 1. 检查数据集文件完整性
ls data/train.json
wc -l data/train.json

# 2. 检查图像文件路径正确性
grep -o '"images": \[.*\]' data/train.json | head -1
ls data/$(grep -o '"images": \["[^"]*"' data/train.json | head -1 | awk -F'"' '{print $4}')

# 3. 修复路径问题（若图像路径为绝对路径，需改为相对路径）
sed -i 's|/absolute/path/to/images|data/images|g' data/train.json

3. 数据增强建议（可选）

针对文旅数据集样本量较少（261 条）的问题，可通过以下方式扩充数据，提升模型泛化能力：

• 图像增强：使用 torchvision.transforms 对图像进行随机裁剪、旋转、亮度调整（需确保文物特征不被破坏）；
• 文本增强：对用户指令进行同义改写（如'介绍这个文物'改为'讲讲这件展品'），对模型回答进行语气微调（保持导游风格一致性）；
• 数据混洗：在 dataset_info.json 中设置 shuffle: true，确保训练时样本顺序随机，避免模型学习顺序依赖。

二、模型微调：技术流程与参数深度解析

（一）Web UI 启动与底层配置

1. 启动命令与环境变量扩展

# 基础启动命令：从 ModelScope 下载模型
USE_MODELSCOPE_HUB=1 llamafactory-cli webui

# 进阶配置（显存不足时使用）：启用梯度检查点 + 限制线程数
USE_MODELSCOPE_HUB=1 MAX_THREADS=4 USE_GRADIENT_CHECKPOINTING=1 llamafactory-cli webui

• MAX_THREADS=4：限制数据加载线程数，避免 CPU 过载；
• USE_GRADIENT_CHECKPOINTING=1：牺牲部分速度换取显存，可减少约 30% 显存占用。

2. Web UI 界面功能布局

进入 UI 后，核心功能区分为「Train」（训练）、「Chat」（对话）、「Model」（模型管理）、「Dataset」（数据集管理）四大模块，其中「Train」模块关键功能：

• 模型加载：自动检测本地模型，若无则从 ModelScope 下载（Qwen2VL-2B-Chat 约 4GB，下载时间取决于网速）；
• 参数配置：支持可视化调整训练参数，实时显示参数说明；
• 日志查看：在「Training Log」标签页查看实时训练日志，包括损失值、学习率、显存占用等；
• 中断恢复：若训练中断，重新启动 UI 后选择「Resume Training」，从上次保存的检查点继续训练。

（二）核心参数配置：原理与优化

1. 模型配置技术细节

• 模型选择逻辑：Qwen2VL-2B-Chat 是通义千问开源的多模态模型，支持图像理解与文本生成，其优势在于：
  • 采用「视觉编码器 + 语言解码器」架构，视觉部分基于 ViT-L/14，文本部分基于 Qwen2 架构，适配文旅场景的图文交互需求；
  • 支持 4K 分辨率图像输入，可清晰识别文物细节（如神面纹玉戚的纹饰）；
  • 轻量化设计（2B 参数），适合中小算力场景微调与部署。
• 微调方法对比：

• 本教程选择 Full 微调，因 Qwen2-VL-2B 为小模型，全参微调可最大化利用数据集信息，避免 LoRA 秩数选择不当导致的效果损失。

2. 训练参数配置原理与调优

3. 输出与保存配置优化

• 输出目录结构：train_qwen2vl 目录下会生成以下文件，需理解各文件用途：

train_qwen2vl/
├── config.json # 模型配置文件（含视觉、文本编码器参数）
├── pytorch_model.bin # 完整模型权重（全参微调后生成）
├── special_tokens_map.json # 特殊 token 映射（如<image>）
├── training_args.bin # 训练参数记录（用于中断恢复）
└── logs/ # 训练日志（含损失曲线数据）

• 保存策略调整：
  • 保存间隔：默认 1000 步保存一次，若训练总步长为 2610（10 轮），则仅保存 2 次（1000 步、2000 步），最后一轮结束后自动保存最终权重；
  • 最优权重选择：在 training_args 中设置 metric_for_best_model: loss，自动选择损失最低的权重作为最佳模型；
  • 权重压缩：训练完成后，可使用 torch.save 对权重进行量化（如 torch.save(model.state_dict(), "qwen2vl_quantized.pt", _use_new_zipfile_serialization=False)），减少部署体积。

（三）微调过程监控与问题排查

1. 关键指标监控

在 Web UI「Training Log」标签页，需重点关注以下指标：

• 损失值（Loss）：
  • 训练损失（Train Loss）：应随轮数逐渐下降，最终稳定在 0.8~1.2 之间（文旅数据集）；
  • 验证损失（Val Loss，需在 dataset_info.json 中配置验证集）：若验证损失上升，说明模型过拟合，需减少轮数或增加权重衰减。
• 显存占用（GPU Memory）：
  • 加载模型后：约 8-10GB；
  • 训练过程中：峰值约 20-22GB（24GB 显存可容纳）；
  • 若出现 CUDA out of memory，需降低 batch_size（默认 4，可改为 2）或启用梯度检查点。
• 学习率（Learning Rate）：
  • 预热阶段：从 0 线性升至 1e-4（前 100 步）；
  • 衰减阶段：若启用学习率衰减（默认 cosine 衰减），后期逐渐降至 1e-6，避免模型震荡。

2. 常见问题与解决方案

三、模型测试：效果验证与对比分析

（一）微调后模型测试：场景化验证

1. 测试流程与用例设计

2. 测试结果量化评估（可选）

若需量化模型效果，可从以下维度打分（1-5 分）：

• 准确性：文物信息（年代、尺寸、出土地点）是否正确；
• 相关性：回答是否匹配用户问题（无答非所问）；
• 流畅性：语句是否通顺，是否符合导游口语化风格；
• 图文一致性：回答是否基于上传图像内容（无编造信息）。

通过对 20 条测试用例打分，若平均得分 >4.0，说明模型微调效果达标。

（二）原始模型对比测试：差异分析

1. 对比测试核心结论

2. 失败案例分析

• 原始模型回答失败案例：
  • 用户输入：上传'神面纹玉戚'图像，问'这件文物来自哪个时代？'
  • 原始模型回答：'这是一件玉器，看起来有一定年代，但具体时代我无法确定。'
• 失败原因：原始模型训练数据中缺乏'神面纹玉戚''新石器时代'等文旅专有信息，无法进行领域关联推理；微调后模型通过样本学习，可准确回答'这件文物来自新石器时代'。

四、模型部署与扩展：从测试到落地

（一）模型导出与格式转换

1. 导出为部署格式

训练完成后，需将模型导出为适合部署的格式（如 PyTorch 原生格式、ONNX 格式）：

# 1. 导出为 PyTorch 完整模型（含配置文件）
llamafactory-cli export --model_name_or_path train_qwen2vl --export_dir qwen2vl_tourism --export_format pytorch

# 2. 导出为 ONNX 格式（支持推理加速）
llamafactory-cli export --model_name_or_path train_qwen2vl --export_dir qwen2vl_tourism_onnx --export_format onnx --device cuda

• ONNX 格式优势：可使用 TensorRT 或 ONNX Runtime 加速推理，相比原生 PyTorch 可提升 50% 以上的生成速度。

（二）轻量化部署方案

1. 本地部署（适合测试）

from llamafactory.chat import ChatModel
from PIL import Image

# 加载模型
model = ChatModel(
    model_path="train_qwen2vl",
    device="cuda",
    dtype="bfloat16"
)

# 准备图像与 prompt
image = Image.open("test_image.jpg").convert("RGB")
prompt = "你是一个导游，请生动有趣地回答游客提出的问题\n用户：给我讲讲这个东西<image>"

# 生成回答
response = model.generate(
    prompt=prompt,
    images=[image],
    max_new_tokens=512,
    temperature=0.7  # 控制回答多样性（0.7 适合文旅场景，兼顾准确与生动）
)
print(response)

2. 线上部署（适合实际应用）

推荐使用 FastAPI + Uvicorn 构建 API 服务，支持多用户并发访问：

# main.py
from fastapi import FastAPI, UploadFile, File
from fastapi.responses import JSONResponse
from PIL import Image
import io
from llamafactory.chat import ChatModel

app = FastAPI(title="文旅多模态大模型 API")

# 加载模型（启动时加载，避免重复加载）
model = ChatModel(
    model_path="train_qwen2vl",
    device="cuda",
    dtype="bfloat16"
)

@app.post("/tourism/chat")
async def chat(file: UploadFile = File(...), question: str = "给我讲讲这个东西"):
    # 读取图像
    image_bytes = await file.read()
    image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
    
    # 构建 prompt
    prompt = f"你是一个导游，请生动有趣地回答游客提出的问题\n用户：{question}<image>"
    
    # 生成回答
    try:
        response = model.generate(
            prompt=prompt,
            images=[image],
            max_new_tokens=512,
            temperature=0.7
        )
        return JSONResponse(content={"response": response})
    except Exception as e:
        return JSONResponse(content={"error": str(e)}, status_code=500)

# 启动服务：uvicorn main:app --host 0.0.0.0 --port 8000 --workers 2

（三）模型迭代与优化方向

• 数据迭代：
  • 扩充样本量：收集更多景区、博物馆的图文数据（如故宫、兵马俑等）；
  • 标注优化：对文物信息进行结构化标注（如年代、材质、用途），提升模型回答准确性。
• 模型优化：
  • 采用 LoRA 微调：在 7B 模型（如 Qwen2-VL-7B-Chat）上使用 LoRA 微调，平衡效果与算力；
  • 量化部署：使用 GPTQ 或 AWQ 对模型进行 4 位量化，减少显存占用（从 24GB 降至 8GB 以下），支持在边缘设备（如 Jetson AGX）部署。
• 功能扩展：
  • 多语言支持：添加英文、日语等多语言文旅数据，支持国际游客；
  • 语音交互：集成 ASR（语音转文字）与 TTS（文字转语音），实现'语音提问 + 语音回答'的导览体验。

本文档详细梳理了使用 LLaMA Factory 对 Qwen2-VL 进行多模态微调的完整流程，涵盖了环境准备、数据适配、参数配置、微调监控、效果测试与部署落地的各个环节，旨在为文旅场景下的多模态大模型微调提供实践指南。