Vision-Language SFT
このスキルは、finetuning-method-selection が既にこのルートに振り分けたことを前提としています。データの形状は画像＋テキストのデモンストレーションであり、嗜好ペアや検証可能な報酬信号ではなく、ベースモデルはテキスト専用ではなく視覚言語モデルです。lora-qlora-recipes はテキスト専用のLoRA/QLoRAレシピをカバーしており、このスキルは視覚タワーとプロジェクタ向けに特化しています。LoRAの基礎（ランク、アルファ、ターゲットモジュール）がまだ十分でない場合は、先にそのスキルを読んでください。
入力： 画像＋テキストデータセットと、モデルカタログから既に選択されたVLMベースモデル。
出力形式： 検証済みのアダプタ設定 — どのコンポーネントを凍結するか、LoRAターゲットモジュール、min_pixels/max_pixels バジェット — これを llm-finetuning-training-engineer が実行可能スクリプトを生成する際に直接使用します。
クイックリファレンス
| 状況 | デフォルト設定 |
|---|---|
| 馴染みのある画像で行動を適応させる場合 | 視覚タワー＋プロジェクタを凍結、LoRA r=8–16、α=16–32 |
| 視覚的なドメインシフトがある場合 | 最後の6層のViT層をアンフリーズ、視覚学習率はLLMの5–10倍低く |
| ターゲットランクでbf16に収まらない場合 | QLoRA — 視覚タワーのみ凍結 |
fast_inference=True | finetune_vision_layers=False |
| 損失は正常だが評価が改善しない場合 | まず以下の「2つのサイレントキラー」を確認 |
コンセンサスレシピ
視覚タワーとプロジェクタを凍結します。LoRAはLLMのみ、全線形層（テキスト専用SFTと同じアテンション＋MLPターゲットリスト — lora-qlora-recipesを参照）に、r=8–16、α=16–32 で適用します。これは、VLMの見え方を乱さずに行動を適応させるための確立されたデフォルトです。
- 視覚タワーとプロジェクタはデフォルトで凍結されます。 これらは既に一般的な視覚表現をエンコードしており、再訓練はほとんどのタスクでめったに必要なく、能力を追加せずにリスクを増やすだけです。
- LoRAランクはテキスト専用の一般的なデフォルトよりも低く設定します（ここではr=8–16、テキスト専用SFTではr=16–32）。これは、LLMのみのアダプタが行動を適応させるのであって、新しい視覚知識を注入するわけではないからです。
- QLoRAは視覚タワーが凍結されている場合のみ許可されます。 ベースを量子化しながら視覚層をアンフリーズして訓練することはサポートされておらず、不安定です — これは調整可能な設定ではなく、厳格なペアリングルールとして扱ってください。視覚タワーをアンフリーズする必要がある場合は、QLoRAをやめてbf16 LoRAを使用してください。
# タワー＋プロジェクタを凍結；LoRAはLLMのみ
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層がスイートスポットです。 最終6層の視覚トランスフォーマー層（タワー全体ではない）をアンフリーズすると、凍結ベースラインと比較して DocVQAで+1.7ポイント、訓練コストは約1.75倍 という結果が測定されています。6層を支払う価値のある上限として扱ってください。それ以上進むと、計算コストがかかるだけで、同等の結果は得られません。
- アンフリーズ時は、視覚学習率をLLM学習率より5～10倍低く設定する必要があります。 視覚タワーの事前学習済み表現はLLMのアダプタよりも壊れやすく、両方に同じ学習率を適用すると、LLMアダプタが補償するよりも早く視覚表現が上書きされるリスクがあります。
- パッチ埋め込み層への高いLoRAランクはNaNを引き起こすリスクがあります。 パッチ埋め込みがアンフリーズされたセットに含まれる場合、ランクを低く保ち、初期ステップの損失を注意深く監視してください — VLMでLoRAを適用するのに最も脆弱な場所の一つです。
2つのサイレントキラー
どちらも、エラーなしで訓練が行われるが学習は進まないという実行を引き起こします。損失曲線は正常に見え、モデルは改善せず、例外もスローされません — どちらも訓練ログがきれいなだけでは不十分で、明示的な訓練前チェックが必要です。
- 画像タグ/カウントの不一致。 テンプレート化されたテキスト内のすべての画像プレースホルダートークンは、実際にコレーターに渡されるメディアアイテムと1対1でマッピングされる必要があります。不一致（プレースホルダーが1つあるが画像が0または2つ添付されている、または画像があるがプレースホルダーがない）は、ほとんどのコレーターでエラーになりません — 画像とテキストを静かに誤整列させ、モデルは「訓練されるが何も学習しません」。訓練を開始する前に、すべての例で、サンプルだけでなく、プレースホルダーとメディアの1対1マッピングを検証してください。完全な検証チェックリストの詳細：
references/collators-and-pitfalls.md。 min_pixels/max_pixels解像度バジェット。 このペアは、VLM SFTにおける品質とメモリにとって最も重要なハイパーパラメータです — ランク、アルファ、学習率よりも重要です。低すぎると、タスクに必要な解像度よりも画像が静かにダウンサンプリングされます（小さい文書のテキストが読めなくなるが、訓練は「成功」しているように見える）；高すぎると、アクティベーションメモリのバジェットを超えるか、安定して訓練するにはバッチサイズが小さくなりすぎます。フレームワークのデフォルトに任せずに、データセットごとに意図的に設定してください。
Unsloth固有の設定
UnslothVisionDataCollatorはUnslothがVLM SFTに期待するコレーターです。references/collators-and-pitfalls.mdで説明されている画像タグの整列とアーキテクチャごとのプロセッサ契約を処理します。VLMデータにテキスト専用のコレーターを代用しないでください。finetune_vision_layers=Falseはfast_inference=Trueの場合に必須です。 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— アーキテクチャごとのコレーター表、画像プレースホルダーを含むデータセット形式の例、訓練前検証チェックリスト、および高度なパターンとしての2段階プロジェクタ整列レシピ。
関連スキル: finetuning-method-selection がここにルーティングします；lora-qlora-recipes がこのスキルが特化するテキスト専用LoRAの基礎をカバーします；grpo-rlvr-training がVLM-RLをカバーします（リファレンスのみ）；dataset-curation がこのスキルがカバーしない画像＋テキストデータセットの準備をカバーします。