Qwen3-VL 视觉模型微调实战：LLaMA-Factory 与 WEBUI 部署

三、数据准备：构建高质量视觉指令数据集

3.1 数据格式规范（ShareGPT 风格）

LLaMA-Factory 默认采用 sharegpt 格式，每条样本包含 messages 和 images 字段：

[
  {
    "messages": [
      { "role": "user", "content": "<image>请识别这张身份证上的姓名？" },
      { "role": "assistant", "content": "张三丰" }
    ],
    "images": ["/path/to/id_card_001.jpg"]
  }
]

3.2 示例数据集构建

创建 /data/service/LLaMA-Factory/data/images/ 目录存放图像，并生成 qwen_vl_demo.json：

[
  {
    "messages": [
      { "role": "user", "content": "<image>请识别图片中的人名?" },
      { "role": "assistant", "content": "张三丰" }
    ],
    "images": ["/data/service/LLaMA-Factory/data/images/1.png"]
  }
]

3.3 注册数据集元信息

编辑 /data/service/LLaMA-Factory/data/dataset_info.json，添加：

"qwen_vl_demo": {
  "file_name": "qwen_vl_demo.json",
  "formatting": "sharegpt",
  "columns": {
    "messages": "messages",
    "images": "images"
  },
  "tags": {
    "role_tag": "role",
    "content_tag": "content",
    "user_tag": "user",
    "assistant_tag": "assistant"
  }
}

四、微调配置详解：YAML 驱动的精细化控制

复制模板并修改：

cp examples/train_lora/qwen2vl_lora_sft.yaml examples/train_lora/qwen3vl_lora_sft.yaml
vim examples/train_lora/qwen3vl_lora_sft.yaml

关键参数说明如下：

### model
model_name_or_path: /data/model/qwen3-vl-4b-instruct

### method
stage: sft # SFT 阶段微调
do_train: true
finetuning_type: lora # 使用 LoRA
lora_target: all # 对所有线性层注入适配器

### dataset
dataset: qwen_vl_demo
template: qwen2_vl # 当前仍沿用 qwen2_vl 模板
cutoff_len: 2048
max_samples: 1000
preprocessing_num_workers: 8

### output
output_dir: /data/output/qwen3-vl-lora-ft
logging_steps: 10
save_steps: 100
plot_loss: true

### training
per_device_train_batch_size: 1
gradient_accumulation_steps: 16
learning_rate: 1e-4
num_train_epochs: 3
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: false
ddp_timeout: 180000000

### evaluation
val_size: 0.1
eval_strategy: steps
eval_steps: 50

注意：

• template: qwen2_vl：目前 LLaMA-Factory 尚未正式支持 qwen3_vl 模板，但因架构兼容可临时使用。
• lora_target: all：Qwen3-VL 包含视觉编码器与语言模型两部分，建议同时微调以提升跨模态对齐能力。

五、启动微调：命令行与监控全流程

执行训练命令：

llamafactory-cli train examples/train_lora/qwen3vl_lora_sft.yaml

典型输出日志片段：

[INFO] loading configuration file /data/model/qwen3-vl-4b-instruct/config.json
[INFO] Model config Qwen3VLConfig { ... "model_type": "qwen3_vl" ... }
[INFO] Fine-tuning method: LoRA trainable params: 24,576,000 || all params: 4,200,000,000 || trainable%: 0.585%
***** Running training *****
Num examples = 90
Total optimization steps = 27
Epoch: 1.0, Step: 27/27, Loss: 0.214
Saving model checkpoint to /data/output/qwen3-vl-lora-ft

训练完成后会在输出目录生成：

/data/output/qwen3-vl-lora-ft/
├── adapter_model.bin # LoRA 权重
├── configuration.json
├── tokenizer_config.json
└── training_loss.png # 损失曲线图

六、模型合并与部署：集成到 Qwen3-VL-WEBUI

6.1 合并 LoRA 权重至基础模型

使用 HuggingFace API 合并：

from peft import PeftModel
from transformers import AutoModelForCausalLM

base_model = AutoModelForCausalLM.from_pretrained("/data/model/qwen3-vl-4b-instruct")
lora_model = PeftModel.from_pretrained(base_model, "/data/output/qwen3-vl-lora-ft")
merged_model = lora_model.merge_and_unload()
merged_model.save_pretrained("/data/model/qwen3-vl-4b-instruct-finetuned")

6.2 启动 Qwen3-VL-WEBUI 容器

拉取并运行官方镜像：

docker run -d \
-p 7860:7860 \
-v /data/model/qwen3-vl-4b-instruct-finetuned:/app/models \
--gpus all \
--shm-size="16gb" \
qwen3-vl-webui:latest

访问 http://localhost:7860 即可通过网页上传图片并测试微调后模型的表现。

七、常见问题与解决方案

问题 1：KeyError: 'qwen3_vl'

错误原因：Transformers 库版本过低，未注册 Qwen3-VL 模型类型。 解决方法：

pip install --upgrade transformers>=4.45.0

验证是否成功：

from transformers import AutoConfig
config = AutoConfig.from_pretrained("/data/model/qwen3-vl-4b-instruct")
print(config.model_type) # 应输出 'qwen3_vl'

问题 2：CUDA Error — Too Many Resources Requested

错误堆栈：

RuntimeError: CUDA error: too many resources requested for launch

根本原因：Qwen3-VL 默认使用 bfloat16 精度，某些旧 GPU（如 V100）不完全支持。 解决方案：修改模型配置文件

vi /data/model/qwen3-vl-4b-instruct/config.json

将 "torch_dtype": "bfloat16" 修改为 "torch_dtype": "float16"

八、总结

本实践完成了基于 LLaMA-Factory 的 Qwen3-VL 视觉语言模型微调全流程。通过 LoRA 技术实现参数高效微调，结合 Qwen3-VL-WEBUI 完成部署验证。解决了环境配置、数据格式、显存优化及版本兼容等关键问题，实现了定制化图文识别任务的落地。