基于ms-swift框架微调多模态模型（Ubuntu22.04）

作者：吴业亮 博客：wuyeliang.blog.csdn.net

本文从核心原理到实操步骤，完整讲解基于微软ms-swift（ModelScope Swift）框架在Ubuntu22.04系统上微调多模态模型（如Qwen-VL、LLaVA、MiniCPM-V等）的全流程。

一、核心原理

1. ms-swift框架简介

ms-swift（ModelScope Swift）是阿里云ModelScope联合微软推出的大模型开发工具包，核心定位是低代码、高效、通用的大模型微调/推理框架，特点：

• 原生支持多模态模型（视觉-语言为主），兼容Qwen-VL、LLaVA、MiniCPM-V、BLIP-2等主流多模态模型；
• 内置LoRA/QLoRA/全量微调等策略，针对多模态模型优化显存占用；
• 统一的配置化开发模式，通过YAML文件管理所有训练参数，无需大量代码开发；
• 深度集成ModelScope生态，可直接调用平台上的预训练模型和数据集。

2. 多模态模型微调核心逻辑

多模态模型（以视觉-语言模型为例）通常由视觉编码器（如ViT/CLIP-ViT）、模态桥接层（Projection Layer）、语言模型（如LLaMA/Qwen）三部分组成：

• 微调重点：模态桥接层（视觉特征到语言模型的投影层）是核心微调目标（预训练的桥接层泛化性不足），其次是语言模型的注意力层（LoRA微调）；视觉编码器通常冻结（显存占用高，且预训练充分）；
• 微调策略：优先使用LoRA/QLoRA（低秩适配），仅微调部分参数（占比<5%），大幅降低显存消耗（消费级GPU如RTX 3090/4090即可运行）；
• 数据核心：需保证图像-文本对的语义对齐，数据集需包含图像路径+结构化文本（如多轮对话），确保视觉特征与文本特征的一致性。

3. ms-swift的多模态微调优化

• 显存优化：支持混合精度（FP16/BF16）、梯度检查点（Gradient Checkpointing）、量化微调（QLoRA），7B模型微调显存可降至8GB以内；
• 配置解耦：将模型、数据、训练策略、硬件参数解耦为独立配置项，适配不同多模态模型；
• 一键式流程：训练、推理、部署全流程封装，无需手动处理模型加载、数据预处理。

二、环境准备（Ubuntu22.04）

1. 系统基础依赖安装

首先更新系统并安装基础工具（图像处理、编译依赖）：

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础依赖（图像处理、git、编译工具）
sudo apt install -y git python3-pip python3-venv libgl1-mesa-glx libglib2.0-0 build-essential

# 安装cmake（部分依赖需要编译）
sudo apt install -y cmake

2. CUDA & cuDNN安装（GPU必备）

多模态模型微调依赖NVIDIA GPU，需安装适配的CUDA和cuDNN（推荐CUDA 11.8，兼容性最佳）。

步骤1：验证GPU兼容性

# 查看GPU型号（确认支持CUDA）
lspci | grep -i nvidia

# 查看NVIDIA驱动版本（需≥450.80.02）
nvidia-smi

若未安装NVIDIA驱动，执行：

sudo apt install -y nvidia-driver-535 # 适配CUDA 11.8

步骤2：安装CUDA 11.8

# 添加NVIDIA源
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update

# 安装CUDA 11.8（仅安装核心组件，避免冗余）
sudo apt install -y cuda-11-8 cuda-toolkit-11.8

# 配置环境变量（临时生效，建议写入~/.bashrc）
export PATH=/usr/local/cuda-11.8/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH

# 验证CUDA安装
nvcc -V # 输出CUDA Version 11.8即可

步骤3：安装cuDNN（适配CUDA 11.8）

# 下载cuDNN（需登录NVIDIA官网，或通过源安装）
sudo apt install -y libcudnn8=8.9.2.26-1+cuda11.8 libcudnn8-dev=8.9.2.26-1+cuda11.8

# 验证cuDNN
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

3. Python环境配置

推荐使用Python 3.10（ms-swift兼容性最佳）：

# 创建虚拟环境
python3 -m venv swift-env

# 激活虚拟环境
source swift-env/bin/activate

# 升级pip
pip install –upgrade pip setuptools wheel

4. ms-swift安装

# 安装ms-swift（核心包）
pip install ms-swift[all] # [all]包含多模态所需的依赖（如torchvision、transformers）

# 验证安装
swift –version # 输出版本号即成功

若需最新功能（如支持新模型），可安装源码版：

git clone https://github.com/modelscope/swift.git
cd swift
pip install -e .[all]

三、数据准备

1. 多模态数据集格式（LLaVA格式，主流）

ms-swift兼容LLaVA格式的多模态数据集（JSON格式），单条数据示例：

{
"id": "001",
"image": "data/images/cat.jpg", # 图像相对路径
"conversations": [
{
"from": "user",
"value": "<image>\\n这只猫是什么品种？" # <image>是固定标记，代表图像输入
},
{
"from": "assistant",
"value": "这是英短蓝猫，特征是毛发短而密，脸部圆润。"
}
]
}

数据集目录结构建议：

custom_data/
├── images/ # 存放所有图像
│ ├── cat.jpg
│ ├── dog.jpg
│ └── …
└── data.json # 标注文件

2. 自定义数据集制作示例

创建简单的图文问答数据集：

# 创建数据集目录
mkdir -p custom_data/images

# 下载示例图像（可选）
wget -O custom_data/images/cat.jpg https://example.com/cat.jpg

# 创建标注文件
cat > custom_data/data.json << EOF
[
{
"id": "001",
"image": "images/cat.jpg",
"conversations": [
{"from": "user", "value": "<image>\\n这只猫是什么颜色？"},
{"from": "assistant", "value": "这只猫是蓝色的，属于英短蓝猫。"}
]
}
]
EOF

3. 数据集上传到ModelScope（可选）

若需复用ModelScope的数据集管理能力，可将自定义数据集上传到ModelScope平台（参考ModelScope数据集上传文档）。

四、微调配置

ms-swift通过YAML配置文件管理所有训练参数，以下以Qwen-VL-Chat-7B模型、LoRA微调为例编写配置文件。

1. 配置文件编写（qwen_vl_lora.yaml）

# 基础配置
experiment_name: qwen_vl_7b_lora # 实验名称
model_type: qwen–vl–chat # 模型类型（ms-swift内置）
framework: pt # 框架（pt=pytorch）

# 模型配置
model_id: qwen/Qwen–VL–Chat–7B # ModelScope模型ID（自动下载）
model_args:
torch_dtype: fp16 # 精度（fp16/bf16/int8）
device_map: auto # 自动分配设备

# 数据集配置
dataset:
train:
– type: custom_multi_modal # 自定义多模态数据集类型
dataset_root: ./custom_data # 数据集根目录
file_name: data.json # 标注文件
image_folder: images # 图像文件夹（相对dataset_root）
eval: null # 暂不设置验证集

# 微调策略配置（LoRA）
sft_type: lora # 微调策略（lora/qlora/full）
lora_args:
r: 8 # LoRA秩（越小显存占用越低）
lora_alpha: 32
lora_dropout: 0.05
target_modules: ['c_attn', 'qkv_proj'] # Qwen-VL的目标模块
lora_target: all # 微调所有目标模块

# 训练参数
train_args:
num_train_epochs: 3 # 训练轮数
per_device_train_batch_size: 2 # 单卡批次大小（根据显存调整）
gradient_accumulation_steps: 4 # 梯度累积（弥补批次大小不足）
learning_rate: 1e-4 # 学习率（LoRA建议1e-4~1e-3）
weight_decay: 0.01 # 权重衰减
lr_scheduler_type: cosine # 学习率调度器
warmup_ratio: 0.05 # 预热比例
logging_steps: 10 # 日志打印步数
save_steps: 100 # 模型保存步数
output_dir: ./output/qwen_vl_lora # 输出目录
fp16: true # 混合精度训练
gradient_checkpointing: true # 梯度检查点（节省显存）

# 其他配置
evaluation_strategy: no # 关闭验证（快速测试）
seed: 42 # 随机种子

2. 关键参数说明（适配GPU显存）

五、执行微调

1. 启动微调命令

在激活的虚拟环境中执行：

swift train –config qwen_vl_lora.yaml

• 首次运行会自动下载Qwen-VL-Chat-7B预训练模型（约14GB），需保证网络通畅；
• 训练过程中会实时打印loss、显存占用、学习率等信息。

2. 训练过程监控

• 日志查看：训练日志默认保存在output/qwen_vl_lora/logs目录；
• 显存监控：实时查看GPU使用情况：watch -n 1 nvidia-smi
• Loss曲线：若配置了tensorboard，可启动查看：tensorboard –logdir ./output/qwen_vl_lora/runs

六、推理验证

1. 一键推理（使用swift命令）

swift infer \\
–model_id qwen/Qwen-VL-Chat-7B \\
–adapter_name_or_path ./output/qwen_vl_lora \\ # 微调后的适配器权重
–multi_modal_inputs '{"image": "./custom_data/images/cat.jpg", "text": "这只猫是什么颜色？"}'

2. 自定义推理脚本（进阶）

创建infer.py：

import torch
from swift.llm import (
get_model_tokenizer,
get_infer_args,
infer_multi_modal
)

# 配置参数
model_id = "qwen/Qwen-VL-Chat-7B"
adapter_path = "./output/qwen_vl_lora"
image_path = "./custom_data/images/cat.jpg"
question = "这只猫是什么颜色？"

# 加载模型和tokenizer
model, tokenizer = get_model_tokenizer(
model_id,
adapter_name_or_path=adapter_path,
torch_dtype=torch.float16,
device_map="auto"
)

# 多模态推理
result = infer_multi_modal(
model,
tokenizer,
image=image_path,
text=question
)

print(f"问题：{question}")
print(f"回答：{result}")

执行脚本：

python infer.py

七、常见问题与优化

1. 显存不足

• 解决方案1：改用QLoRA（配置sft_type: qlora，torch_dtype: int8）；
• 解决方案2：开启梯度检查点（gradient_checkpointing: true）；
• 解决方案3：减小per_device_train_batch_size，增大gradient_accumulation_steps；
• 解决方案4：冻结视觉编码器（ms-swift默认冻结，无需额外配置）。

2. 训练Loss不下降

• 调整学习率：LoRA微调建议学习率范围1e-4~1e-3，若loss震荡可降至5e-5；
• 增加数据量：确保数据集样本数≥100（少量数据易过拟合）；
• 检查数据格式：确认<image>标记正确，图像路径无误。

3. 推理速度慢

• 使用量化推理：加载模型时指定torch_dtype=torch.int8；
• 开启模型加速：使用vllm或tensorrt加速推理（ms-swift支持集成）：pip install vllm
  swift infer –model_id qwen/Qwen-VL-Chat-7B –vllm True

4. 模型权重保存与复用

• 微调后的适配器权重保存在output/qwen_vl_lora目录，可直接用于推理；
• 若需合并适配器权重到主模型（方便部署）：swift export –adapter_name_or_path ./output/qwen_vl_lora –output_dir ./merged_model

八、总结

ms-swift框架大幅降低了多模态模型微调的门槛，核心步骤可总结为：

通过调整LoRA参数、批次大小、精度等，可适配不同硬件条件，实现消费级GPU上的多模态模型微调。