vision-sft

Configures supervised fine-tuning recipes for vision-language models on image-text datasets.

39.3k|4.2k|Updated Jul 24, 2025
One-click install
npx skills add https://github.com/wshobson/agents --skill vision-sft
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vision-sft
Source: https://github.com/wshobson/agents/tree/main/plugins/llm-finetuning/skills/vision-sft
Command: npx skills add https://github.com/wshobson/agents --skill vision-sft

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Fine-tuning a vision-language model often fails silently: the loss curve looks normal while the model learns nothing, due to image-placeholder mismatches or wrong resolution budgets. This Skill provides a validated adapter configuration recipe so VLM fine-tunes actually learn.

Core Features & Use Cases

  • Consensus LoRA Recipe: Freeze the vision tower and projector, apply LoRA to the LLM only at r=8-16, alpha=16-32, with QLoRA permitted only alongside a frozen vision tower.
  • Unfreezing Guidance: Escalate to unfreezing the last six ViT layers only for genuine visual domain shift, with vision learning rate 5-10x lower than the LLM rate.
  • Silent-Failure Detection: Pre-training validation checklist covering image-tag-to-media 1:1 mapping, min_pixels/max_pixels resolution budgets, and loss-mask verification per architecture family (Qwen-VL, InternVL, Gemma 3).
  • Use Case: You are adapting a VLM to read dense technical diagrams and the frozen-tower baseline plateaus; the Skill tells you to unfreeze the last six ViT layers at a reduced vision LR and validates the collator before training.

Quick Start

Ask the agent to configure a LoRA fine-tune for your vision-language model on your image-text dataset and validate the data collator before training.

Frequently Asked Questions about vision-sft

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fine-tune a vision-language model with LoRA?

Freeze the vision tower and projector, then apply LoRA to the LLM only across all linear layers (q/k/v/o and gate/up/down projections) at rank 8-16 with alpha 16-32. This is the settled default for adapting VLM behavior without disturbing visual representations.

When should I unfreeze the vision tower during VLM fine-tuning?

Unfreeze only for genuine visual domain shift, such as satellite imagery or medical scans, after the frozen-tower recipe plateaus. Unfreeze at most the last six ViT layers and run the vision learning rate 5-10x lower than the LLM rate.

Why does my VLM fine-tune train normally but not improve?

Two silent killers cause this: image placeholder tokens not mapping 1:1 to media items passed to the collator, and a min_pixels/max_pixels budget that downsamples images below task requirements. Run the pre-training validation checklist on one collated batch before relaunching.

Can I use QLoRA when unfreezing vision layers?

No. QLoRA is permitted only with a frozen vision tower; quantizing the base while training vision layers is unsupported and unstable. If the vision tower must unfreeze, switch to bf16 LoRA instead.

Does Unsloth fast inference work with vision-layer LoRA adapters?

No. When fast_inference=True, you must set finetune_vision_layers=False because vLLM cannot serve LoRA adapters on vision layers. Choose either unfrozen vision layers or fast inference, not both.