使用 LLaMA-Factory 框架对 Qwen3-VL 视觉语言模型进行 LoRA 微调。内容涵盖软硬件环境搭建、ShareGPT 格式数据集构建、YAML 配置文件详解、训练命令执行、LoRA 权重合并以及通过 Qwen3-VL-WEBUI 容器进行部署验证。包含常见错误排查方案，如 Transformers 版本兼容性、CUDA 资源限制处理等，助力开发者完成定制化视觉识别任务落地。
随着多模态大模型的快速发展，Qwen3-VL 作为阿里云推出的最新一代视觉语言模型，凭借其强大的图文理解能力、长上下文支持以及对视频、GUI 操作等复杂任务的支持，正在成为企业级 AI 应用的重要基础设施。然而，预训练模型虽然具备通用能力，但在特定业务场景下——如识别公司内部文档格式、定制化图像标签生成或自动化表单填写——往往表现不足。
本文将带你从零开始完成一次完整的 Qwen3-VL-4B-Instruct 模型微调实践，使用开源工具 LLaMA-Factory 实现高效参数微调（LoRA），并借助 Qwen3-VL-WEBUI 镜像快速部署和验证效果。
LLaMA-Factory 是一个专为大型语言模型设计的开源微调框架，支持超过 100 种主流模型（包括 Qwen 系列），提供命令行与 WebUI 双模式操作，极大降低了微调门槛。
核心优势：
Qwen3-VL-WEBUI 是阿里官方发布的 Docker 镜像，集成了预加载的 Qwen3-VL-4B-Instruct 模型、完整依赖环境（PyTorch、Transformers ≥4.45.0）以及内置 Gradio Web 界面，支持上传图片/视频进行交互式测试。
使用该镜像可避免繁琐的环境配置，尤其适用于资源有限但需快速验证微调结果的团队。
| 组件 | 最低要求 | 推荐配置 |
|---|---|---|
| GPU | NVIDIA RTX 3090 (24GB) | A100/A6000/V100 × 2 或更高 |
| 显存 | ≥24GB | ≥48GB（便于全参数微调探索） |
| 存储 | ≥100GB SSD | ≥500GB NVMe（用于缓存模型与数据集） |
注意：若仅使用 LoRA 微调 Qwen3-VL-4B，单卡 4090D（24GB）即可满足基本训练需求。
# 创建虚拟环境
conda create -n qwen_vl python=3.10
conda activate qwen_vl
# 克隆项目
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
安装核心依赖：
pip install -e ".[torch,metrics]" -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install flash-attn==2.6.3 --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install bitsandbytes==0.43.1 deepspeed==0.14.4
pip install --upgrade transformers>=4.45.0
推荐从 ModelScope 下载 Qwen3-VL-4B-Instruct：
git lfs install
git clone https://www.modelscope.cn/qwen/Qwen3-VL-4B-Instruct.git /data/model/qwen3-vl-4b-instruct
确保目录结构如下：
/data/model/qwen3-vl-4b-instruct/
├── config.json
├── model.safetensors.index.json
├── preprocessor_config.json
└── tokenizer_config.json
LLaMA-Factory 默认采用 sharegpt 格式，每条样本包含 messages 和 images 字段：
[
{
"messages": [
{ "role": "user", "content": "<image>请识别这张身份证上的姓名？" },
{ "role": "assistant", "content": "张三丰" }
],
"images": ["/path/to/id_card_001.jpg"]
}
]
创建 /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"]
}
]
编辑 /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"
}
}
复制模板并修改：
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 # V100 不支持 BF16，改用 fp16
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 # 损失曲线图
使用 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")
拉取并运行官方镜像：
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 即可通过网页上传图片并测试微调后模型的表现。
错误原因：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'
错误堆栈：
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 微调全流程，获得定制化视觉识别能力 |
| 部署验证 | 实现模型合并并在 WEBUI 中完成可视化测试 |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online