LLaMA-Factory 微调 Qwen3-VL 多模态大模型指南

LLaMA-Factory 微调 Qwen3-VL 多模态大模型指南 | 极客日志

LLaMA-Factory 微调 Qwen3-VL 多模态大模型指南

1. 显卡驱动

显卡型号：NVIDIA GeForce RTX 3090 24G
显卡驱动：NVIDIA-SMI 535.171.04
CUDA: 12.2 ,Driver Version: 535.171.04

微调 Qwen3-VL-2B 模型，至少需要 12G 显存

2. 模型微调

项目采用大型语言模型工厂（LLaMA-Factory）对大模型微调，目前可支持 Qwen3 / Qwen2.5-VL / Gemma 3 / GLM-4.1V / InternLM 3 / MiniCPM-o-2.6 等大模型。下面以微调 Qwen3-VL-2B-Instruct 作为例子进行说明。

微调之前，请先下载 Qwen3-VL 基础模型。下载方法可以选择 modelscope 和 huggingface，国内建议选择 modelscope，避免翻墙问题。

modelscope 下载 Qwen3-VL-2B-Instruct 方法，模型默认保存在 ~/.cache/modelscope/hub/models/：

# 使用 modelscope 下载模型 Qwen3-VL-2B-Instruct # 模型保持在 ~/.cache/modelscope/hub/models/
modelscope download --model Qwen/Qwen3-VL-2B-Instruct

微调其他 Qwen3-VL 版本，请参考官方仓库地址。

LLaMA-Factory 安装教程，请参考官方文档：https://github.com/hiyouga/LLaMA-Factory

安装好 LLaMA-Factory 后，激活环境，然后终端输入（默认端口是 7860）：

export CUDA_VISIBLE_DEVICES=0 # 指定运行 GPU
export GRADIO_SERVER_PORT=30000 # 指定 gradio 的端口 (默认是 7860，这里修改为 30000)
export GRADIO_TEMP_DIR="~/.cache/gradio" # 指定 gradio 临时缓存路径，解决上传图片权限的问题
llamafactory-cli webui # 启动 llamafactory web 服务

浏览器打开 url http://0.0.0.0:30000/ (http://ip:port,默认端口是 7860，为避免端口冲突，可以通过 export GRADIO_SERVER_PORT=30000 修改端口),并按照配置如下信息:

模型名称：选择'Qwen3-VL-2B-Instruct'，你也可以使用 Qwen3-VL 更大参数量的模型，如 7B
模型路径：请填写服务器 Qwen3-VL-2B-Instruct 模型文件路径绝对地址
模型下载源：可以选择'modelscope'和'huggingface'，国内建议选择'modelscope'避免翻墙。注意：选择'modelscope'时，模型路径必须填写绝对地址，否则不能正常加载模型。
微调方法：建议选择'lora'
数据路径：数据路径必须包含 dataset_info.json，默认是 LLaMA-Factory 项目的./data 路径，由于我们使用外部数据训练，因此数据路径设置为项目根目录./data 绝对路径。
数据集：数据集采样 sharegpt 格式，项目已经构建了一个多模态数据集。
预览数据集：如果数据路径正常，点击'预览数据集'，可以正常查看数据的，反之数据路径错误。
预览命令：可以查看训练的命令行
开始：一切准备好后，点击开始训练

如果训练正常的，控制台会显示相应的训练日志信息。

3. 模型导出

基于 LoRA 训练的模型，默认情况下，输出目录只保存了增量的训练参数；你还需要将原始基础模型 (--model_name_or_path) 和 LoRA 适配器参数 (--adapter_name_or_path) 进行合并，生成一个独立的、无需额外加载适配器即可运行的完整模型，便于后续部署或分享。

#!/usr/bin/env bash
# TODO Lora+model 合并，参数说明：
#--model_name_or_path：原始基础模型路径，可使用 modelscope download --model Qwen/Qwen3-VL-2B-Instruct 下载
#--adapter_name_or_path：LoRA 适配器路径（即训练输出目录）
#--export_dir：合并后模型的保存路径
#--template default：Qwen3-VL 可使用 default，也可尝试 qwen_vl（但通常自动识别）
#--trust_remote_code True：Qwen 系列模型必需
export CUDA_VISIBLE_DEVICES=0
model_name_or_path=~/.cache/modelscope/hub/models/Qwen/Qwen3-VL-2B-Instruct
adapter_name_or_path=saves/Qwen3-VL-2B-Instruct/lora/train_2025-12-22-18-08-22/checkpoint-440
export_dir=saves/Qwen3-VL-2B-Instruct/lora/train_2025-12-22-18-08-22/Qwen3-VL-2B-Instruct
llamafactory-cli export \
  --model_name_or_path $model_name_or_path \
  --adapter_name_or_path $adapter_name_or_path \
  --template default \
  --finetuning_type lora \
  --export_dir $export_dir \
  --trust_remote_code True

llamafactory-cli export调用 LLaMA-Factory 的命令行接口（CLI），执行 export 操作，即导出合并后的模型。
model_name_or_path指定基础模型（base model）的路径或 Hugging Face 模型 ID。
adapter_name_or_path指定微调后保存的 LoRA 适配器（adapter）的路径。
template default指定对话模板（chat template）名称。
finetuning_type lora指定微调方法类型。
export_dir指定合并后模型的输出目录。
trust_remote_code True允许加载远程自定义代码。

4. 模型部署：vLLM 服务

模型训练好后，项目推荐使用 vLLM 部署模型。

源码：https://github.com/vllm-project/vllm
文档：https://vllm.hyper.ai/docs/
安装：pip install vllm

#!/usr/bin/env bash
# TODO 启动 vllm 服务
export CUDA_VISIBLE_DEVICES=0
# http://0.0.0.0:8000/v1
# model_path=~/.cache/modelscope/hub/models/Qwen/Qwen3-VL-2B-Instruct # 原始基础模型路径
model_path=saves/Qwen3-VL-2B-Instruct/lora/train_2025-12-22-18-08-22/Qwen3-VL-2B-Instruct # Lora 微调 (合并) 后的模型路径
vllm serve $model_path --dtype auto --max-model-len 7680 --max_num_seqs 32 --api-key token-abc123 --gpu_memory_utilization 0.95 --trust-remote-code

api-key 是自定义的服务接口的 API 访问密钥，后面接口调用需要使用。客户端请求需包含：Authorization: Bearer token-abc123，保护服务器免受未授权访问。
model_path 请填写 Lora 微调 (合并) 后的模型路径。
dtype auto 自动选择模型加载的数据类型。
max-model-len 设置模型支持的最大上下文长度（token 数）。
max_num_seqs 设置批处理的最大序列数。
gpu_memory_utilization 设置 GPU 内存利用率目标。

启动成功后，可以看到 Starting vLLM API server 0 on http://0.0.0.0:8000 等信息，这是就是 vLLM 服务接口，后续可以基于该接口实现聊天对话功能。

5. 测试效果

调用 vLLM API 进行多模态对话，测试脚本如下：

# -*- coding: utf-8 -*-
import os
import traceback
from openai import OpenAI
from pybaseutils import image_utils, base64_utils

url = "http://0.0.0.0:8000/v1" # vLLM 地址
key = "token-abc123" # API 密钥，需与启动服务时设置的 (--api-key) 保持一致

class Client():
    """调用 vLLM API 进行多模态对话"""
    def __init__(self, url, key, model=None):
        self.url = url
        self.key = key
        self.model = model
        self.services = OpenAI(api_key=self.key, base_url=self.url)
        print(f"url:{self.url}, key:{self.key}, model:{self.model}")

    def chat(self, messages, T=0.0):
        result = None
        try:
            response = self.services.chat.completions.create(model=self.model, messages=messages, seed=2024, temperature=T)
            contents = response.choices[0].message.content
            result = contents if isinstance(contents, str) else contents[0]['text']
        except Exception as e:
            traceback.print_exc()
         result

 __name__ == :
    image_file = 
     os.path.exists(image_file), 
    image = image_utils.read_image(image_file, use_rgb=)
    messages = [{
        : ,
        : [
            {: , : },
            {: , : {: image}},
        ]
    }]
    messages = base64_utils.serialization(messages, prefix=, use_rgb=)
    client = Client(url=url, key=key)
    output = client.chat(messages)
    (output)

测试图片及输出结果可根据实际运行情况验证。

LLaMA-Factory 微调 Qwen3-VL 多模态大模型指南