用 ms-swift 微调 MOSS-VL：从环境搭建到指标翻倍的实战指南

MOSS-VL 已经合入 ms-swift 主分支。本文给出一套从安装环境到启动 LoRA 或 Full SFT 的完整流程，所有示例使用公开模型和公开数据，不依赖内部文件路径。

1. 环境准备

建议使用 Linux、Python 3.10–3.12 和支持 CUDA 的 PyTorch 环境。

git clone https://github.com/modelscope/ms-swift.git
cd ms-swift
python -m venv --system-site-packages .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install "transformers>=4.57.1,<5" "torchcodec==0.7.0" joblib

torchcodec==0.7.0 对应 PyTorch 2.8；如果使用其他 PyTorch 版本，需要安装与之匹配的 TorchCodec。

2. 准备多模态数据

ms-swift 使用 messages 保存对话，通过 images 或 videos 指向媒体文件。视频在用户消息中使用 <video> 占位：

[
  {
    "messages": [
      {
        "role": "user",
        "content": "<video>\nDescribe the video."
      },
      {
        "role": "assistant",
        "content": "The player makes a jump shot."
      }
    ],
    "videos": [
      "/absolute/path/to/example.mp4"
    ]
  }
]

媒体路径推荐使用绝对路径。使用相对路径时，将 ROOT_IMAGE_DIR 设置为媒体路径的基准目录；该变量同时用于图片、视频和音频。每个 <video> 占位符必须和 videos 中的一个视频对应。

下面的训练命令使用公开的 lmms-lab/VideoChatGPT:Generic 数据，可以直接下载并运行。训练自有数据时，只需将 --dataset 替换为本地 JSON 或 JSONL 文件。

3. LoRA SFT

LoRA 适合先验证数据与任务，默认冻结视觉塔和多模态对齐模块，只在语言侧线性层注入 LoRA。

source .venv/bin/activate

export VIDEO_MIN_PIXELS=256
export VIDEO_MAX_PIXELS=16384
export FPS=1
export FPS_MAX_FRAMES=256
export CUDA_VISIBLE_DEVICES=0

args=(
  --model OpenMOSS-Team/MOSS-VL-Instruct-0708
  --dataset "lmms-lab/VideoChatGPT:Generic#1000"
  --use_hf true
  --split_dataset_ratio 0.01
  --tuner_type lora
  --target_modules all-linear
  --freeze_vit true
  --freeze_aligner true
  --torch_dtype bfloat16
  --attn_impl eager
  --num_train_epochs 1
  --per_device_train_batch_size 1
  --per_device_eval_batch_size 1
  --gradient_accumulation_steps 16
  --learning_rate 1e-4
  --lora_rank 8
  --lora_alpha 32
  --gradient_checkpointing true
  --vit_gradient_checkpointing false
  --gradient_checkpointing_kwargs '{"use_reentrant": false}'
  --packing false
  --max_length 4096
  --max_pixels 262144
  --eval_steps 50
  --save_steps 50
  --save_total_limit 2
  --logging_steps 5
  --warmup_ratio 0.05
  --dataset_num_proc 4
  --dataloader_num_workers 4
  --report_to none
  --output_dir output/moss_vl_lora
)

swift sft "${args[@]}"

4. Full SFT

Full SFT 会训练语言模型、视觉塔和对齐模块。下面使用 8 卡 DeepSpeed ZeRO-3，并显式启用语言与视觉非重入 Gradient Checkpointing。

source .venv/bin/activate

export VIDEO_MIN_PIXELS=256
export VIDEO_MAX_PIXELS=16384
export FPS=1
export FPS_MAX_FRAMES=256
export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
export NPROC_PER_NODE=8

args=(
  --model OpenMOSS-Team/MOSS-VL-Instruct-0708
  --dataset "lmms-lab/VideoChatGPT:Generic#1000"
  --use_hf true
  --split_dataset_ratio 0.01
  --tuner_type full
  --freeze_llm false
  --freeze_vit false
  --freeze_aligner false
  --torch_dtype bfloat16
  --attn_impl eager
  --num_train_epochs 1
  --per_device_train_batch_size 1
  --per_device_eval_batch_size 1
  --gradient_accumulation_steps 2
  --learning_rate 1e-5
  --gradient_checkpointing true
  --vit_gradient_checkpointing true
  --gradient_checkpointing_kwargs '{"use_reentrant": false}'
  --packing false
  --max_length 4096
  --max_pixels 262144
  --deepspeed zero3
  --eval_steps 50
  --save_steps 50
  --save_total_limit 1
  --save_only_model true
  --logging_steps 5
  --warmup_ratio 0.05
  --dataset_num_proc 4
  --dataloader_num_workers 4
  --report_to none
  --output_dir output/moss_vl_full
)

swift sft "${args[@]}"

save_only_model=true 只保存可独立推理的完整模型，能显著减少磁盘占用，但不保存 optimizer 和 scheduler，不能用于严格断点续训。需要续训时删除该参数。

5. 训练效果示例

我们使用篮球比赛短视频训练 1 epoch，并在未参与训练的视频上进行固定评测。下面只展示 Base 已经具备一定能力、Full SFT 后继续提升的代表性指标。

这次 Full SFT 训练后的checkpoint 可以直接由 Swift 加载，验证推理均无运行错误。

6. 使用限制

• MOSS-VL 当前不支持 packing=true 或 padding-free 训练。

• Gradient Checkpointing 必须使用 use_reentrant=false。

• Full SFT 的显存、Checkpoint 和 optimizer state 占用较大，应提前确认 GPU 与磁盘资源。

• 视频帧数和分辨率会直接影响显存与速度，建议先使用较小样本完成 LoRA smoke。

模型：OpenMOSS-Team/MOSS-VL-Instruct-0708 训练框架：modelscope/ms-swift 适配 PR：modelscope/ms-swift#9944