vision-sft

Vision-Language SFT

このスキルは、finetuning-method-selection がすでにここへルーティング済みであることを前提としています。データの形は画像+テキストのデモンストレーションであり、選好ペアでも検証可能な報酬シグナルでもなく、ベースはテキスト専用ではなく vision-language モデルです。lora-qlora-recipes はテキスト専用の LoRA/QLoRA レシピを扱っており、このスキルはそれを vision tower と projector 向けに特化させたものです。LoRA の基本（rank、alpha、target modules）にまだ馴染みがない場合は、先にそちらのスキルを読んでください。

入力: 画像+テキストのデータセットと、モデルカタログからすでに選択済みの VLM ベースモデル。 出力形式: 検証済みのアダプター設定 — どのコンポーネントを凍結するか、LoRA の target modules、そして min_pixels/max_pixels のバジェット — であり、llm-finetuning-training-engineer が実行可能なスクリプトを生成する際にこれを直接消費します。

クイックリファレンス

状況	デフォルト
馴染みのある画像に対する振る舞いの適応	tower+projector を凍結、LoRA r=8–16、α=16–32
視覚ドメインのシフト	最後の6つの ViT 層を凍結解除、vision の LR は 5–10倍低く
目標の rank で bf16 に収まらない	QLoRA — vision tower のみ凍結
fast_inference=True	finetune_vision_layers=False
損失は正常だが eval が改善しない	まず以下の「2つの静かな殺し屋」を確認

コンセンサスレシピ

vision tower と projector を凍結します。LoRA は LLM のみに適用し、all-linear（テキスト専用 SFT と同じ attention + MLP の target リスト — lora-qlora-recipes を参照）で、r=8–16、α=16–32 とします。これは、VLM の「見え方」を乱すことなくその振る舞いを適応させるための、定着したデフォルトです。

• vision tower と projector はデフォルトで凍結したままにします。 これらはすでに汎用的な視覚表現をエンコードしています。再学習が必要になることはほとんどなく、ほとんどのタスクでは能力を追加することなくリスクだけを増やします。
• LoRA の rank はテキスト専用の汎用デフォルトよりも低く設定します（ここでは r=8–16、テキスト専用 SFT では r=16–32）。これは、LLM のみのアダプターが新しい視覚知識を注入するのではなく、振る舞いを適応させているためです。
• QLoRA は vision tower を凍結した場合にのみ許可されます。 ベースを量子化しつつ vision 層を凍結解除して学習させることはサポートされておらず、不安定です — これは調整可能な項目ではなく、厳格な組み合わせルールとして扱ってください。vision tower を凍結解除する必要がある場合は、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

いつ凍結解除するか

vision 層の凍結解除は、デフォルトの判断ではなく意図的なエスカレーションです — ドメインシフトがテキストではなく視覚である場合にのみ手を伸ばしてください。

• 視覚ドメインのシフトに対してのみ凍結解除します。 タスクが、tower がすでに理解している画像（チャート、日常的な写真）に対する新しい振る舞いを教えることである場合、上記の凍結 tower レシピで十分です。凍結解除するのは、視覚ドメイン自体が tower にとって馴染みのない場合 — 衛星画像、医療スキャン、高密度の技術図 — であり、かつ凍結 tower レシピが頭打ちになる場合です。
• 最後の6つの ViT 層がスイートスポットです。 最後の6つの vision-transformer 層（tower 全体ではなく）を凍結解除すると、凍結ベースラインに対して DocVQA で +1.7pt、トレーニングコストは約1.75倍 という結果が測定されています。6層を、対価を払う価値のある上限として扱ってください。それ以上進めると、釣り合う結果なしに計算資源を消費します。
• 凍結解除する場合、vision の LR は LLM の LR より 5–10倍低く設定する必要があります。 vision tower の事前学習済み表現は LLM のアダプターよりも壊れやすく、両方に同じ LR を使うと、LLM アダプターが補償できるよりも速く視覚表現を上書きしてしまうリスクがあります。
• patch-embedding 層に高い LoRA rank を使うと NaN のリスクがあります。 patch embedding が凍結解除の対象に含まれる場合、その rank を低く保ち、初期ステップの損失を注意深く監視してください — VLM において LoRA を適用する最も壊れやすい箇所の一つです。

2 つのサイレントキラー

どちらも、エラーなく学習が進むのに学習されない実行を生み出します。損失曲線は正常に見え、モデルは改善せず、どちらも例外をスローしません。どちらも、きれいな学習ログだけでなく、明示的な学習前チェックが必要です。

• 画像タグと個数の不一致。 テンプレート化されたテキスト内のすべての画像プレースホルダートークンは、実際にコレーターに渡されるメディア項目と 1:1 で対応している必要があります。不一致（プレースホルダーが 1 つに対して画像が 0 個または 2 個添付されている、あるいはプレースホルダーのない画像がある）は、ほとんどのコレーターではエラーになりません。画像とテキストがサイレントにずれ、モデルは「学習するが何も学ばない」状態になります。学習を開始する前に、サンプルだけでなくすべての例で、プレースホルダーとメディアの 1:1 対応を検証してください。検証チェックリストの詳細: references/collators-and-pitfalls.md。
• min_pixels/max_pixels の解像度バジェット。 このペアは、VLM SFT における品質とメモリにとって最も影響の大きいハイパーパラメータです。rank、alpha、LR よりも重要です。低すぎると、タスクに必要な解像度を下回るまで画像がサイレントにダウンサンプリングされます（学習は「成功」しても、小さな文書テキストが読めなくなります）。高すぎると、アクティベーションメモリのバジェットを超えたり、安定して学習するにはバッチが小さすぎることを強いられたりします。データセットごとに意図的に設定し、フレームワークのデフォルトのままにしないでください。

Unsloth 固有の事項

• UnslothVisionDataCollator は、VLM SFT で Unsloth が想定するコレーターです。references/collators-and-pitfalls.md で説明されている画像タグの位置合わせと、アーキテクチャごとのプロセッサ契約を処理します。VLM データに対してテキスト専用のコレーターで代用しないでください。
• fast_inference=True の場合、finetune_vision_layers=False が必須です。 vLLM はビジョン層の LoRA アダプターを提供できないため、高速推論のセットアップでビジョン層も同時にアンフリーズすると、学習が成功しても提供時に失敗します。レシピが最後の 6 つの ViT 層のアンフリーズを求める場合（上記の「いつアンフリーズするか」を参照）、その実行では高速推論は選択肢から外れます。どちらか一方を選び、両方は選ばないでください。

モデルの選択

ベース VLM の選択はこのスキルの範囲外です。それは 1 か所、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 はこのスキルが扱わない画像とテキストのデータセット準備を扱います。