LlamaFactory 多模态大模型微调实战指南

执行命令：

uv run llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml 

导出与推理

导出模型（合并 LoRA 权重）：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora
export_dir: models/llama3_lora_sft
export_size: 2
export_device: cpu
export_legacy_format: false

运行：

llamafactory-cli export merge_config.yaml 

在线推理：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
infer_backend: huggingface

运行：

llamafactory-cli chat inference_config.yaml 

微调 Qwen3-VL 多模态模型

下面通过一个实际案例，演示如何使用 QLoRA 微调 Qwen3-VL 模型。

1. 模型准备

国内网络下载 HuggingFace 模型可能超时，建议设置镜像源：

export HF_ENDPOINT="https://hf-mirror.com"

本次选用 Qwen/Qwen3-VL-2B-Instruct。

2. 数据准备

数据集配置位于 data/dataset_info.json。LlamaFactory 支持 alpaca 和 sharegpt 两种格式。

• Alpaca 格式：包含 instruction, input, output。
• ShareGPT 格式：包含 messages 列表，适合多轮对话及多模态任务。

本次使用 COCO 数据集，属于 ShareGPT 格式。需在 dataset_info.json 中注册配置：

"coco-400": {
  "file_name": "coco-400.json",
  "formatting": "sharegpt",
  "columns": {
    "messages": "conversations",
    "id": "id"
  },
  "tags": {
    "role_tag": "from",
    "content_tag": "value",
    "user_tag": "user",
    "assistant_tag": "assistant"
  }
}

确保 JSON 文件结构符合 ShareGPT 规范，包含音频或图像路径信息。

3. 参数配置

基于官方提供的 QLoRA 示例模板进行修改。关键参数如下：

• 模型路径：model_name_or_path
• 量化位宽：quantization_bit (推荐 4bit)
• 数据集：dataset
• 模板：template (视觉模型需用 qwen3_vl_nothink，语言模型用 qwen3_nothink，选错会报错)

修改后的配置文件示例：

model_name_or_path: Qwen/Qwen3-VL-2B-Instruct
quantization_bit: 4
quantization_method: bnb
trust_remote_code: true

stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

dataset: coco-3000
template: qwen3_vl_nothink
cutoff_len: 2048
preprocessing_num_workers: 16
dataloader_num_workers: 4

output_dir: saves/qwen3-2b-coco-3000/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
report_to: none

per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 1e-5
num_train_epochs: 2
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true

4. 启动训练

执行训练命令：

uv run llamafactory-cli train examples/train_qlora/qwen3-coco.yaml 

训练过程中会输出日志，关注 Loss 变化及显存占用。以下是清洗后的典型训练日志片段：

[INFO|trainer.py] Running training...
Num examples = 600
Num Epochs = 2
Instantaneous batch size per device = 2
Total train batch size (w. parallel) = 8
Gradient Accumulation steps = 4
Total optimization steps = 150

{'loss': 4.3662, 'grad_norm': 5.82, 'learning_rate': 6e-06, 'epoch': 0.13}
{'loss': 4.0005, 'grad_norm': 6.60, 'learning_rate': 9.7e-06, 'epoch': 0.4}
{'loss': 3.1868, 'grad_norm': 3.40, 'learning_rate': 8.5e-06, 'epoch': 0.67}
... loss 持续下降 ...
{'loss': 2.6784, 'grad_norm': 1.99, 'learning_rate': 1.3e-09, 'epoch': 2.0}

Saving model checkpoint to saves/qwen3-2b-coco-3000/lora/sft/checkpoint-150
train_loss = 3.1502
train_runtime = 0:01:33
Figure saved at: saves/qwen3-2b-coco-3000/lora/sft/training_loss.png

训练完成后，可在 output_dir 下找到生成的 LoRA 权重文件和损失曲线图。