Qwen3-VL 基于 LLaMA-Factory 微调与部署实战指南

执行训练

设置可见 GPU 并启动训练脚本：

CUDA_VISIBLE_DEVICES=6 llamafactory-cli train examples/train_lora/qwen2_5vl_lora_sft.yaml

训练完成后，LoRA 权重将保存在 output_dir 指定的路径下。

4. 模型合并

微调结束后，需将 LoRA 权重合并回基座模型以便部署。

配置合并脚本

编辑 examples/merge_lora 下的 YAML 文件：

### model
model_name_or_path: /data/hcb/LLaMA-Factory-main/qwen3_vl_model # 原模型路径
adapter_name_or_path: saves/qwen3vl-2b/lora/sft # LoRA 权重路径
template: qwen3_vl
trust_remote_code: true

### export
export_dir: output/qwen3vl_lora_sft
export_size: 5
export_device: cpu
export_legacy_format: false

执行导出

运行以下命令完成合并：

llamafactory-cli export examples/merge_lora/qwen2_5vl_lora_sft.yaml

合并后的模型位于 export_dir 中，可直接用于推理服务。

5. 私有数据集构造

实际落地往往需要自定义数据。LLaMA-Factory 支持多种格式，多模态任务推荐参考 ShareGPT 格式。

注册新数据集

1. 将整理好的 JSON 文件放入 data 目录。
2. 在 dataset_info.json 中注册该数据集，指向文件名及图片存储路径。
3. 确保图片路径与 JSON 中的 images 字段一致。

例如，构造一个表格识别数据集 table_reg：

{
  "type": "sharegpt",
  "columns": {
    "messages": "messages",
    "images": "images"
  }
}

提示词中需包含图像占位符，并在 images 列表中添加相对路径。配置完成后，在训练 YAML 的 dataset 字段填入注册名称即可开始训练。

6. 模型部署 (vLLM)

为了支持高并发和工业级调用，推荐使用 vLLM 部署合并后的模型，并暴露 OpenAI 兼容接口。

安装 vLLM

在虚拟环境中安装指定版本：

pip install vllm==0.11.0 -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/

启动服务

使用以下命令启动 API 服务器。注意调整显存利用率和并行度以适应硬件：

export CUDA_VISIBLE_DEVICES=6
python -m vllm.entrypoints.openai.api_server \
  --host 0.0.0.0 \
  --port 8003 \
  --model /data/hcb/LLaMA-Factory-main/output/qwen3vl_lora_sft \
  --served-model-name qwen3_vl \
  --trust-remote-code \
  --dtype float16 \
  --gpu-memory-utilization 0.8 \
  --tp 1

启动成功后，服务将监听在 8003 端口。

客户端调用示例

编写 Python 脚本通过 OpenAI SDK 发起请求。注意处理 Base64 编码和多模态消息结构：

import openai
import base64
import os
from openai import OpenAI

def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode('utf-8')

def multimodal_chat(image_path=None, text_prompt="描述这张图片"):
    client = OpenAI(
        api_key="Empty",
        base_url="http://localhost:8003/v1/"
    )
    
    messages = [{"role": "system", "content": "你是一个多模态智能助手，可以理解和分析图像内容。"}]
    
    if image_path and os.path.exists(image_path):
        base64_image = encode_image(image_path)
        user_content = [
            {"type": "text", "text": text_prompt},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}}
        ]
    else:
        user_content = text_prompt
        
    messages.append({"role": "user", "content": user_content})
    
    payload = {
        "model": "qwen3_vl",
        "messages": messages,
        "temperature": 0.1,
        "max_tokens": 2000
    }
    
    try:
        response = client.chat.completions.create(**payload, timeout=30)
        return response
    except Exception as e:
        print(f"请求失败：{e}")
        return None

if __name__ == "__main__":
    image_path = r"/path/to/your/image.png"
    prompt = "描述这张图片中有什么"
    
    if os.path.exists(image_path):
        res = multimodal_chat(image_path=image_path, text_prompt=prompt)
        if res and res.choices:
            print("模型回复:")
            print(res.choices[0].message.content)
        else:
            print("请求失败")

至此，微调与部署流程全部完成。根据实际业务需求调整 batch size、学习率及显存参数，即可获得稳定的推理服务。