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

LlamaFactory 是一个统一的大模型训练与微调框架，旨在降低大模型定制的技术门槛。它支持全量微调、LoRA、QLoRA 等多种策略，提供 Web UI 和命令行两种交互方式，适合从实验到部署的全流程。

环境安装

推荐使用 uv 工具进行依赖管理，它能快速解决版本冲突问题。

首先克隆项目仓库：

git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git

进入目录并同步环境：

cd LlamaFactory uv sync

验证安装是否成功，启动 Web UI：

uv run llamafactory-cli webui

浏览器访问本地地址，若界面正常加载，说明环境配置无误。

文章配图

命令行基础用法

除了 Web UI，命令行模式更适合自动化脚本和服务器部署。核心命令格式为 llamafactory-cli + 任务 + 配置文件。

常用任务类型包括：

train：训练模型
export：导出合并后的模型
chat：在线推理
eval：评估模型效果

配置文件采用 YAML 格式，官方提供了丰富的示例，涵盖全量训练、LoRA 微调等场景。

训练示例

以 Qwen3 LoRA 微调为例：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
dataset: identity, alpaca_en_demo
template: llama3
cutoff_len: 1024
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16
output_dir: saves/llama3-8b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

执行命令：

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 权重文件和损失曲线图。

文章配图