视觉语言监督微调 (Vision-Language SFT)
本技能假定finetuning-method-selection已路由至此：数据形式为图像+文本演示，而非偏好对或可验证的奖励信号，且基础模型是视觉语言模型而非纯文本模型。lora-qlora-recipes涵盖了本技能针对视觉塔和投影仪专门化的纯文本LoRA/QLoRA配方；如果LoRA基础知识（秩、alpha、目标模块）尚不熟悉，请先阅读该技能。
输入： 一个图像+文本数据集以及从模型目录中选取的VLM基础模型。
输出格式： 一个验证过的适配器配置——哪些组件被冻结、LoRA目标模块以及min_pixels/max_pixels预算——llm-finetuning-training-engineer在生成可运行脚本时会直接使用。
快速参考
| 情况 | 默认配置 |
|---|---|
| 在熟悉的图像上适配行为 | 冻结塔+投影仪，LoRA r=8–16，α=16–32 |
| 视觉域迁移 | 解冻最后6层ViT层，视觉学习率低5–10倍 |
| 在目标秩下无法适配bf16 | QLoRA——仅冻结视觉塔 |
fast_inference=True | finetune_vision_layers=False |
| 损失正常，评估未见提升 | 首先检查下方的“两个静默杀手” |
共识配方
冻结视觉塔和投影仪。仅在LLM上应用LoRA，所有线性层（与纯文本SFT相同的注意力+MLP目标模块列表——参见lora-qlora-recipes），秩r=8–16，α=16–32。这是适配VLM行为而不干扰其视觉能力的既定默认方案。
- 视觉塔和投影仪默认保持冻结。 它们已经编码了通用的视觉表示；重新训练它们很少有必要，并且对大多数任务而言增加了风险而未增加能力。
- LoRA秩低于纯文本通用默认值（此处r=8–16，而纯文本SFT为r=16–32），因为仅限LLM的适配器是在适配行为，而非注入新的视觉知识。
- 仅允许在冻结视觉塔的情况下使用QLoRA。 同时量化基础模型并解冻训练视觉层是不支持且不稳定的——请将此视为硬性配对规则，而非可调参数。如果需要解冻视觉塔，则放弃QLoRA，改用bf16 LoRA。
# 冻结塔 + 投影仪；仅对LLM应用LoRA
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，所有线性层——r=8-16, alpha=16-32
何时解冻
解冻视觉层是一个刻意的升级，而非默认决策——仅在视觉域发生迁移时才考虑，而非文本域。
- 仅在视觉域迁移时解冻。 如果任务是让模型在塔已理解的图像（图表、日常照片）上学习新行为，上述冻结塔配方已足够。当视觉域本身对塔而言不熟悉——卫星图像、医学扫描、密集技术图表——且冻结塔配方达到平台期时，才进行解冻。
- 最后6层ViT层是最佳选择。 解冻最后六层视觉变换器层（而非整个塔）在冻结基线上测得DocVQA提升+1.7pt，训练成本增加约1.75倍。将六层视为值得付出的上限；进一步投入计算资源但无匹配的回报。
- 解冻时视觉学习率必须比LLM学习率低5–10倍。 视觉塔的预训练表示比LLM的适配器更脆弱；两者使用相同学习率的风险是视觉表示被覆盖的速度快于LLM适配器能够补偿的速度。
- 在补丁嵌入层上使用高LoRA秩存在NaN风险。 如果补丁嵌入包含在解冻集内，请保持其秩低并密切关注早期步的损失——这是VLM中应用LoRA最脆弱的位置之一。
两个静默杀手
两者都会导致训练进行但无错误且无学习效果：损失曲线看似正常，模型未改善，且两者均不抛出异常——两者都需要在训练前进行显式检查，而非仅依赖干净的训练日志。
- 图像标签/计数不匹配。 模板化文本中的每个图像占位符令牌必须与实际传递给收集器的媒体项一一对应。不匹配（一个占位符，但附加零个或两个图像；或者一个图像没有占位符）在大多数收集器中不会报错——它会静默地使图像和文本错位，模型“训练但学不到任何东西”。在训练开始前，对每个样本（而非仅仅抽样）验证一对一的占位符到媒体的映射。完整的验证检查清单细节：
references/collators-and-pitfalls.md。 min_pixels/max_pixels分辨率预算。 这对参数是VLM SFT中质量和内存最关键的超参数——比秩、alpha或学习率更重要。设置过低会静默地将图像降采样到任务所需的水平以下（即使训练“成功”，小文档文本也变得不可读）；设置过高会超出激活内存预算或迫使批次过小，无法稳定训练。请根据每个数据集有意设置，不要使用框架默认值。
Unsloth 特定说明
UnslothVisionDataCollator是Unsloth期望用于VLM SFT的收集器——它处理references/collators-and-pitfalls.md中描述的图像标签对齐和按架构的处理器合约。不要为VLM数据替换为纯文本收集器。- 当
fast_inference=True时，必须设置finetune_vision_layers=False。 vLLM无法在视觉层上服务LoRA适配器，因此即使训练成功，同时启用快速推理和解冻视觉层的设置在服务时也会失败。如果配方要求解冻最后6层ViT层（参见上方的“何时解冻”），则该次运行无法使用快速推理——二选一，不能同时使用。
模型选择
基础VLM的选择超出了本技能的范围——它统一存在于finetuning-method-selection的references/model-catalog.md中的模型目录中。本技能及其参考仅按架构家族描述配方，绝不推荐某个模型优于另一个。
VLM强化学习（VLM-GRPO）在本插件中仅作为参考——与VLM-RL相关的碎片化工具和奖励黑客故障模式在grpo-rlvr-training中介绍，而非此处。本技能的范畴仅限于监督微调。
故障模式
上述每一节反复出现的错误是将干净的损失曲线视为运行健康的证明。正常的损失曲线既可能对应正常的运行，也可能对应任一静默杀手的存在，因为无论哪种情况模型都在对某些内容进行训练——只是当存在静默杀手时，不是对齐的图像-文本信号。如果在正常损失曲线旁出现平坦的评估分数，请在调整任何超参数之前重新运行references/collators-and-pitfalls.md中的检查清单。
参考资料
references/collators-and-pitfalls.md——按架构的收集器表格、带有图像占位符的数据集格式示例、训练前验证检查清单，以及作为高级模式的两阶段投影仪对齐配方。
相关技能：finetuning-method-selection路由至此；lora-qlora-recipes涵盖本技能专门化的纯文本LoRA基础知识；grpo-rlvr-training涵盖VLM-RL（仅参考）；dataset-curation涵盖本技能未涉及的图像+文本数据集准备。