vision-sft

视觉-语言 SFT

本技能假设 finetuning-method-selection 已经将任务路由到这里：数据形态是 图像+文本演示，而非偏好对 或可验证的奖励信号，且基座是 视觉-语言模型而非纯文本 模型。lora-qlora-recipes 涵盖了纯文本 LoRA/QLoRA 配方，而本技能针对 视觉塔和投影器做了专门化；如果对 LoRA 基础 （rank、alpha、目标模块）尚不熟悉，请先阅读 该技能。

输入： 一个图像+文本数据集，以及已从模型 目录中选定的 VLM 基座模型。 输出格式： 一份经过验证的适配器配置—— 哪些组件被冻结、LoRA 目标模块， 以及 min_pixels/max_pixels 预算——供 llm-finetuning-training-engineer 在生成可运行 脚本时直接使用。

快速参考

情况	默认值
在熟悉的图像上适配行为	冻结塔+投影器，LoRA r=8–16，α=16–32
视觉领域偏移	解冻最后 6 层 ViT，视觉 LR 低 5–10 倍
目标 rank 下无法装入 bf16	QLoRA——仅冻结视觉塔
fast_inference=True	finetune_vision_layers=False
损失正常，评估不提升	先检查下方的两个隐性杀手

共识配方

冻结视觉塔和投影器。只对 LLM 应用 LoRA，全线性（与纯文本 SFT 相同的 注意力 + MLP 目标列表—— 见 lora-qlora-recipes），r=8–16， α=16–32。这是在不干扰 VLM 视觉方式的前提下 适配其行为的既定默认方案。

• 视觉塔和投影器默认保持冻结。 它们已经编码了通用的视觉 表示；重新训练它们很少 必要，对大多数任务而言只会增加风险 而不会增加能力。
• LoRA rank 低于纯文本 通用默认值（此处 r=8–16，而纯文本 SFT 为 r=16–32），因为仅 LLM 的适配器 是在适配行为，而非注入新的视觉 知识。
• QLoRA 仅在视觉塔冻结时 允许使用。 在量化基座的同时 解冻并训练视觉层是不受支持且 不稳定的——请将此视为硬性 配对规则，而非可调项。如果视觉塔 需要解冻，请放弃 QLoRA 并改用 bf16 LoRA。

# freeze tower + projector; LoRA on LLM only
for name, param in model.named_parameters():
    if "vision_tower" in name or "projector" in name:
        param.requires_grad = False

target_modules = [
    "q_proj", "k_proj", "v_proj", "o_proj",
    "gate_proj", "up_proj", "down_proj",
]  # LLM-only, all-linear — r=8-16, alpha=16-32

何时解冻

解冻视觉层是有意的 升级，而非默认决策——仅在 领域偏移是视觉性而非文本性时 才采用它。

• 仅针对视觉领域 偏移解冻。 如果任务是在塔已经 理解的图像（图表、日常照片）上 教授新行为， 上述冻结塔配方就已 足够。当视觉领域本身 对塔而言不熟悉时——卫星影像、 医学扫描、密集技术图表—— 且冻结塔配方进入平台期时， 才解冻。
• 最后 6 层 ViT 是 最佳平衡点。 解冻最后六层 视觉 Transformer 层（而非 整个塔）相比冻结基线实测 +1.7pt DocVQA， 训练成本约 1.75 倍。 将六层视为值得付出的 上限；再往前则只花费算力 而无相应结果。
• 解冻时视觉 LR 必须比 LLM LR 低 5–10 倍。 视觉 塔的预训练表示比 LLM 的适配器 更脆弱； 两者使用相同 LR 可能导致 视觉表示被覆盖的速度快于 LLM 适配器能够补偿的速度。
• 在 patch 嵌入层上使用高 LoRA rank 有 NaN 风险。 如果 patch 嵌入在解冻集合中，请保持 其 rank 较低，并密切观察早期步的损失 ——这是 VLM 中应用 LoRA 最脆弱的 位置之一。

两个静默杀手

两者都会产生一次训练过程无报错、却没有学到任何东西的运行：损失曲线看起来正常，模型没有改进，而且两者都不会抛出异常——两者都需要在训练前进行显式检查，而不仅仅是一份干净的训练日志。

• 图像标记/数量不匹配。 模板化文本中的每个图像占位符 token 都必须与实际传递给 collator 的媒体项一一对应。不匹配（一个占位符，却附加了零张或两张图像；或者一张图像没有对应的占位符）在大多数 collator 中不会报错——它会静默地使图像与文本错位，模型"训练了但什么也没学到"。在训练开始前，对每一个样本（而不只是抽样）验证占位符与媒体的一一对应关系。完整的验证清单细节： references/collators-and-pitfalls.md。
• min_pixels/max_pixels 分辨率预算。 这一对参数是 VLM SFT 中影响质量和内存的最关键超参数——比 rank、alpha 或 LR 更重要。设置过低会静默地将图像下采样到低于任务所需（即使训练"成功"，小号文档文字也会变得无法辨认）；设置过高会撑爆激活内存预算，或迫使 batch 过小以至于无法稳定训练。要针对每个数据集刻意设置它，不要让它停留在框架默认值。

Unsloth 特有事项

• UnslothVisionDataCollator 是 Unsloth 对 VLM SFT 所期望使用的 collator——它负责处理 references/collators-and-pitfalls.md 中所述的图像标记对齐以及各架构的 processor 契约。不要用纯文本 collator 替代它来处理 VLM 数据。
• 当 fast_inference=True 时，finetune_vision_layers=False 是必需的。 vLLM 无法在视觉层上提供 LoRA 适配器服务，因此一个同时解冻视觉层的快速推理配置即使在训练时成功，也会在服务时失败。如果配方要求解冻最后 6 层 ViT（参见上文"何时解冻"），那么该次运行就无法使用快速推理——二者只能选其一，不能同时选。

模型选择

基础 VLM 的选择不在本 skill 的范围内——它只存在于一个地方，即 finetuning-method-selection 的 references/model-catalog.md 中的模型目录。本 skill 及其参考文档仅按架构族系描述配方，从不推荐某个模型优于另一个。

VLM 强化学习（VLM-GRPO）在本插件中仅为参考资料——VLM-RL 特有的碎片化工具链和奖励攻击失效模式在 grpo-rlvr-training 中讲述，不在此处。本 skill 的范围止于监督微调。

失效模式

上述每一节中反复出现的错误，是把一条干净的损失曲线当作训练运行健康的证据。一条看起来正常的曲线既与一次正常运行的训练相容，也与任意一个静默杀手相容，因为无论哪种情况，模型都在某个东西上进行训练——只是当存在杀手时，训练的不是对齐的图像-文本信号。当评估分数持平而损失曲线正常时，意味着在改动任何超参数之前，都要重新运行 references/collators-and-pitfalls.md 中的检查清单。

参考资料

• references/collators-and-pitfalls.md —— 各架构 collator 对照表、带图像占位符的数据集格式示例、一份训练前验证清单，以及作为高级模式的两阶段 projector 对齐配方。

相关 skill：finetuning-method-selection 会路由到这里；lora-qlora-recipes 涵盖本 skill 所专门化的纯文本 LoRA 基础；grpo-rlvr-training 涵盖 VLM-RL（仅为参考资料）；dataset-curation 涵盖本 skill 不涉及的图像+文本数据集准备。