多模态：LLaVA / Qwen2-VL / Qwen3-VL 微调

9.1 多模态模型在 LLaMA-Factory 里的统一处理

无论 LLaVA / Qwen-VL / Qwen2-VL / Qwen3-VL / InternVL / MiniCPM-V / GLM-4V，LLaMA-Factory 都用一个统一的"多模态插件"机制：

简单说：多模态被转成"含特殊 token 的文本序列"，剩下的流程和文本 SFT 一模一样。这就是为什么第 4 章那一份 6-args 配置体系完全能扩展到多模态。

9.2 一份多模态 YAML 长什么样

仓库自带 examples/train_lora/qwen3vl_lora_sft.yaml：

### model
model_name_or_path: Qwen/Qwen3-VL-4B-Instruct
image_max_pixels: 262144           # ★ 多模态特有：单图最大像素
video_max_pixels: 16384            # ★ 多模态特有：单帧最大像素
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: mllm_demo,identity,alpaca_en_demo    # ★ mllm_demo 是图文数据
                                              # video: mllm_video_demo
template: qwen3_vl_nothink                     # ★ template 必须是 _vl_ 版
cutoff_len: 2048
max_samples: 1000
preprocessing_num_workers: 16
dataloader_num_workers: 4
...

和文本 SFT YAML 比对，多模态要改的就 4 个字段：

9.3 多模态数据格式

LLaMA-Factory 多模态走 sharegpt 格式 + images / videos 列。仓库 data/mllm_demo.json 是参考。一条样本长这样：

{
  "messages": [
    {
      "role": "user",
      "content": "<image>描述这张图片"
    },
    {
      "role": "assistant",
      "content": "这是一只猫，坐在窗台上看着窗外。"
    }
  ],
  "images": ["data/images/cat.jpg"]
}

在 data/dataset_info.json 中要这样注册：

{
  "mllm_demo": {
    "file_name": "mllm_demo.json",
    "formatting": "sharegpt",
    "columns": {
      "messages": "messages",
      "images":   "images"
    }
  }
}

占位符必须出现在 content 里，个数和列表元素数对齐。一条样本里有 2 张图，那 content 必须出现 2 个 <image>。

9.4 mm_plugin：每个模型一个适配器

src/llamafactory/data/mm_plugin.py 维护一组 Plugin，每个对应一种多模态架构。它们负责：

1. 读取图像 / 视频文件（PIL / decord）；
2. 调模型自己的 image_processor / video_processor；
3. 把处理后的 visual feature 用正确数量的 placeholder token 占位到序列里；
4. 训练时把 visual feature 替换回去。

遇到没列出的多模态新模型，通常是因为 LLaMA-Factory 还没适配。给项目提 PR 加一个 Plugin 是常见贡献方式。

9.5 多模态训练的特别注意

显存分布

多模态训练显存 ≈ 文本部分 + visual encoder + 处理后的 visual feature。image_max_pixels 越大，第二项越大：

训练时如果一张样本含一张 1024×1024 大图 + 2048 文本 token，序列实际长度约 6000 token。cutoff_len 必须够大。

vision tower 是否参与训练

默认情况下 LLaMA-Factory冻结 visual encoder，只训语言侧 LoRA + projector。如果要训 vision tower：

finetuning_type: lora
lora_target: all                  # 默认只覆盖 language 部分
freeze_vision_tower: false        # 把 vision tower 放开
freeze_multi_modal_projector: false  # connector 也放开

这种全开训练通常需要 ≥ 80 GB 显存。

视频训练

视频 = 多帧图像。LLaMA-Factory 在 mm_plugin 里做帧采样（默认稀疏均匀采样），video_max_pixels 限制每帧分辨率。常见 YAML 加一行：

video_fps: 1.0                    # 每秒采 1 帧
video_max_pixels: 16384           # 每帧 ≈ 128×128
video_min_pixels: 256

9.6 多模态 + DPO / RM

LLaMA-Factory 多模态也可以走偏好对齐：

stage: dpo
finetuning_type: lora
template: qwen3_vl_nothink
dataset: dpo_mllm_demo           # 同样格式 + chosen/rejected + images
pref_loss: sigmoid

data/dpo_mllm_demo.json 演示了 schema：

{
  "conversations": [
    {"from": "human", "value": "<image>评价这张图的构图"},
    {"from": "gpt", "value": "..."}
  ],
  "chosen": {"from": "gpt", "value": "好回复"},
  "rejected": {"from": "gpt", "value": "差回复"},
  "images": ["..."]
}

9.7 多模态推理

llamafactory-cli chat \
  model_name_or_path=Qwen/Qwen3-VL-4B-Instruct \
  adapter_name_or_path=saves/qwen3-vl-4b/lora/sft \
  template=qwen3_vl_nothink

在 chat CLI 中用 <image>path/to/img.png 这种语法直接附图：

User: <image>/tmp/cat.jpg 请描述这张图
Assistant: 一只橘色的猫坐在窗台上...

9.8 常见踩坑

9.9 CompositeModel：每个 VLM 在源码里"长什么样"

多模态模型形态千差万别，LLaMA-Factory 在 src/llamafactory/model/model_utils/visual.py:39 的 CompositeModel dataclass 用统一 schema 描述：

# visual.py:39
@dataclass
class CompositeModel:
    projector_keys: list[str]        # 多模态 projector 路径，如 ["multi_modal_projector"]
    vision_model_keys: list[str]     # 视觉塔路径，默认会被 freeze
    language_model_keys: list[str]   # 文本侧路径，用于选择性 freeze
    lora_conflict_keys: list[str]    # 与 LoRA 不兼容的模块名

仓库里已经注册了若干 VLM 族（同文件后续）：

"我想训 Qwen3-VL 时只动 LM、冻 vision tower 和 projector"——这是默认行为（freeze_vision_tower: true + freeze_multi_modal_projector: true 默认 True）。要联训 projector，加一行 freeze_multi_modal_projector: false；要训 vision tower，再加 freeze_vision_tower: false。三者解耦。

9.10 mm_plugin：多模态数据预处理插件

每个 VLM 族的 image / video / audio 怎么 resize、怎么变 token、怎么拼到 prompt 里——逻辑都在 src/llamafactory/data/mm_plugin.py 的 plugin 类里，按模型族分实现。每个 plugin 实现这几个方法：

典型 plugin 命名：Qwen2vlPlugin / Qwen2omniPlugin / InternvlPlugin / LlavaPlugin / LlavaNextPlugin / Gemma3Plugin / PaliGemmaPlugin 等。template 注册时通过 mm_plugin=... 参数关联。"加一个新 VLM 支持"流程：

1. 写一个 MyVlmPlugin(BasePlugin) 子类；
2. 在 visual.py 注册一个 CompositeModel，标 projector / vision keys；
3. 在 data/template.py 注册 template，传入新 plugin；
4. 在 data/dataset_info.json 允许 columns 映射 images / videos / audios 字段。

9.11 关键 processor 字段（YAML 入口）

多模态 processor 的运行时行为，通过 patcher.py:290–305 从 ModelArguments 抽出来塞给 HF processor：

调显存最直接的两个旋钮：image_max_pixels 和 video_maxlen。前者控单图 token 数（Qwen2-VL 用 28×28 patch，768*768 约 729 个 visual token）；后者控视频总帧数。

9.12 projector 的 dtype 转换

QLoRA 跑 VLM 时偶尔 NaN，多半是 projector 输出 dtype 不一致。visual.py:139–159 的 autocast_projector_dtype() 给所有 projector 注册了一个 post-hook，把输出强转到 compute_dtype。这是仓库自动加的，但你需要知道它存在——自定义 VLM plugin 时要把新的 projector 路径加进 projector_keys，否则 dtype 链就断了。