Qwen3-VL 视觉大模型微调实践：部署、训练与评估全流程

2.2 注册数据集到 LLaMA-Factory

编辑 data/dataset_info.json 文件，添加自定义数据集元信息：

{
  "SCB": {
    "file_name": "/root/LLaMA-Factory/data/SCB.json",
    "formatting": "sharegpt",
    "columns": {
      "messages": "messages",
      "images": "images"
    },
    "tags": {
      "role_tag": "role",
      "content_tag": "content",
      "user_tag": "user",
      "assistant_tag": "assistant"
    }
  }
}

⚠️ 注意事项：

• 路径建议使用绝对路径避免加载失败
• 图像文件必须存在且可读
• 支持 JPG/PNG/WebP 等常见格式

三、基于 WebUI 的可视化微调训练

3.1 启动训练界面

通过浏览器访问 http://<ip>:6006，进入 LLaMA-Factory WebUI。

配置要点如下：

💡 提示：首次训练建议先用小样本验证流程是否通畅。

3.2 开始训练

点击 Start 按钮后，系统会自动执行以下流程：

1. 加载预训练模型
2. 构建 LoRA 适配器（rank=8, alpha=16）
3. 数据预处理（图像编码 + 文本 tokenize）
4. 多卡 DDP 分布式训练（若有多张 GPU）
5. 定期保存 checkpoint 到 saves/ 目录

训练过程中可在页面实时查看 loss 曲线、学习率变化及显存占用情况。

四、命令行方式高级训练（非 WebUI）

对于自动化脚本或批量实验，推荐使用 CLI 方式训练。

4.1 完整训练命令示例

llamafactory-cli train \
--stage sft \
--do_train True \
--model_name_or_path /root/Qwen/Qwen3-VL-4B-Instruct \
--preprocessing_num_workers 16 \
--finetuning_type lora \
--template qwen3_vl \
--flash_attn auto \
--dataset_dir data \
--dataset SCB \
--cutoff_len 2048 \
--learning_rate 5e-05 \
--num_train_epochs 2.0 \
--max_samples 100000 \
--per_device_train_batch_size 2 \
--gradient_accumulation_steps 8 \
--lr_scheduler_type cosine \
--max_grad_norm 1.0 \
--logging_steps 5 \
--save_steps 100 \
--warmup_steps 0 \
--packing False \
--enable_thinking True \
--report_to none \
--output_dir saves/Qwen3-VL-4B-Instruct/lora/train_$(date +%Y-%m-%d-%H-%M) \
--bf16 True \
--plot_loss True \
--trust_remote_code True \
--ddp_timeout 180000000 \
--include_num_input_tokens_seen True \
--optim adamw_torch \
--lora_rank 8 \
--lora_alpha 16 \
--lora_dropout 0 \
--lora_target all \
--freeze_vision_tower True \
--freeze_multi_modal_projector True \
--image_max_pixels 589824 \
--image_min_pixels 1024 \
--video_max_pixels 65536 \
--video_min_pixels 256 

📌 关键参数解析：

• --enable_thinking True: 启用思维链模式，增强推理能力
• --bf16 True: 使用 bfloat16 加速训练并节省显存
• --lora_target all: 对所有线性层注入 LoRA（包括 QKV 和 FFN）
• --freeze_vision_tower: 冻结 ViT 主干，仅训练投影模块和语言模型部分

五、模型导出与合并

训练完成后需将 LoRA 权重合并回原始模型，以便独立部署。

5.1 导出融合模型命令

llamafactory-cli export \
--model_name_or_path /root/Qwen/Qwen3-VL-4B-Instruct \
--adapter_name_or_path saves/Qwen3-VL-4B-Instruct/lora/train_2025-xx-xx-xx-xx \
--template qwen3_vl \
--trust_remote_code True \
--export_dir /root/merged_models/Qwen3-VL-4B-Instruct-SCB \
--export_size 4 \
--export_device cuda \
--export_legacy_format false 

✅ 输出目录将包含标准 HuggingFace 格式的模型文件，可用于后续推理。

六、模型评估与性能分析

为量化微调效果，我们编写了专用评估脚本，支持从 JSON 文件加载测试集并输出分类指标。

6.1 评估脚本核心逻辑（evaluate_behavior_json.py）

from transformers import Qwen3VLForConditionalGeneration, AutoProcessor
from qwen_vl_utils import process_vision_info
import json
from sklearn.metrics import precision_score, recall_score, f1_score

def load_model(model_path):
    model = Qwen3VLForConditionalGeneration.from_pretrained(
        model_path, torch_dtype="auto", device_map="auto"
    )
    processor = AutoProcessor.from_pretrained(model_path)
    return model, processor

def get_prediction(prompt, image_path, model, processor):
    messages = [{
        "role": "user",
        "content": [{"type": "image", "image": image_path}, {"type": "text", "text": prompt}]
    }]
    text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    images, videos, video_kwargs = process_vision_info(messages, return_video_kwargs=True)
    # Qwen3-VL 特有处理：分离 metadata
    video_metadatas = None
    if videos:
        videos, video_metadatas = zip(*videos)
        videos, video_metadatas = list(videos), list(video_metadatas)
    inputs = processor(
        text=[text],
        images=images,
        videos=videos,
        video_metadata=video_metadatas,
        return_tensors="pt",
        do_resize=False,
        **video_kwargs
    ).to(model.device)
    outputs = model.generate(**inputs, max_new_tokens=64)
    response = processor.batch_decode(outputs, skip_special_tokens=True)[0]
    return response.strip()

6.2 评估结果示例（微调前后对比）

📊 分析发现，'指导'、'巡视'等细粒度行为识别准确率显著提升，说明微调有效增强了领域语义理解能力。

七、最佳实践与避坑指南

✅ 成功经验总结

❌ 常见问题与解决方案