wshobson/vision-sft

SFT de Visión-Lenguaje

Este skill asume que finetuning-method-selection ya ha determinado que la forma de los datos es demostraciones de imagen+texto (no pares de preferencia ni señales de recompensa verificables), y que la base es un modelo de lenguaje y visión (VLM), no solo de texto. lora-qlora-recipes cubre la receta LoRA/QLoRA solo texto que este skill especializa para la torre de visión y el proyector; lee ese skill primero si los fundamentos de LoRA (rango, alfa, módulos objetivo) no te son familiares.

Entrada: un dataset de imagen+texto y un modelo base VLM ya seleccionado del catálogo de modelos. Formato de salida: una configuración de adaptador validada —qué componentes están congelados, módulos objetivo de LoRA y un presupuesto de min_pixels/max_pixels— que llm-finetuning-training-engineer consume directamente al generar un script ejecutable.

Referencia Rápida

Situación	Valor por Defecto
Adaptar comportamiento en imágenes familiares	Torre+proyector congelados, LoRA r=8-16, α=16-32
Cambio de dominio visual	Descongelar las últimas 6 capas ViT, LR de visión 5-10x menor
No cabe en bf16 con el rango objetivo	QLoRA — solo torre de visión congelada
fast_inference=True	finetune_vision_layers=False
Pérdida normal, evaluación no mejora	Revisar primero los Dos Asesinos Silenciosos abajo

La Receta de Consenso

Congela la torre de visión y el proyector. Coloca LoRA solo en el LLM, en todas las capas lineales (la misma lista de objetivos de atención + MLP que en SFT solo texto —ver lora-qlora-recipes—), con r=8-16, α=16-32. Esta es la configuración predeterminada establecida para adaptar el comportamiento de un VLM sin alterar su forma de ver.

• La torre de visión y el proyector se mantienen congelados por defecto. Ya codifican una representación visual general; reentrenarlos rara vez es necesario y añade riesgo sin añadir capacidad para la mayoría de las tareas.
• El rango de LoRA es menor que el valor por defecto general para solo texto (r=8-16 aquí frente a r=16-32 para SFT solo texto) porque el adaptador solo-LLM está adaptando el comportamiento, no inyectando nuevo conocimiento visual.
• QLoRA solo se permite con la torre de visión congelada. Cuantizar la base mientras se descongelan y entrenan capas de visión no es compatible y es inestable —trata esto como una regla de emparejamiento estricta, no ajustable. Si la torre de visión necesita descongelarse, abandona QLoRA y usa bf16 LoRA en su lugar.

# congelar torre + proyector; LoRA solo en 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",
]  # solo LLM, todas lineales — r=8-16, alpha=16-32

Cuándo Descongelar

Descongelar capas de visión es una escalada deliberada, no una decisión predeterminada —recurre a ello solo cuando el cambio de dominio sea visual, no textual.

• Descongela solo para cambios de dominio visual. Si la tarea es enseñar nuevo comportamiento en imágenes que la torre ya entiende (gráficos, fotos cotidianas), la receta con torre congelada es suficiente. Descongela cuando el dominio visual en sí mismo sea desconocido para la torre —imágenes satelitales, exploraciones médicas, diagramas técnicos densos— y la receta con torre congelada se estanque.
• Las últimas 6 capas ViT es el punto óptimo. Descongelar las últimas seis capas del transformador de visión (no toda la torre) midió +1.7pt en DocVQA con un costo de entrenamiento ~1.75x sobre la línea base congelada. Trata seis capas como el límite que vale la pena pagar; ir más allá gasta cómputo sin un resultado equivalente.
• La LR de visión debe ser 5-10x menor que la LR del LLM cuando está descongelada. La representación preentrenada de la torre de visión es más frágil que el adaptador del LLM; usar la misma LR para ambas corre el riesgo de sobrescribir la representación visual más rápido de lo que el adaptador del LLM puede compensar.
• Un rango alto de LoRA en la capa de incrustación de parches (patch embedding) corre el riesgo de NaN. Si la capa de incrustación de parches está en el conjunto descongelado, mantén su rango bajo y vigila de cerca la pérdida en pasos tempranos —es uno de los lugares más frágiles para aplicar LoRA en un VLM.

Los Dos Asesinos Silenciosos

Ambos producen una ejecución que entrena sin errores y sin aprendizaje: la curva de pérdida se ve normal, el modelo no mejora y ninguno lanza una excepción —ambos necesitan una verificación explícita previa al entrenamiento, no solo un registro de entrenamiento limpio.

• Desajuste de etiqueta/recuento de imágenes. Cada token marcador de imagen en el texto con plantilla debe mapear 1:1 a un elemento multimedia realmente pasado al collator. Un desajuste (un marcador sin imagen adjunta o con dos imágenes; o una imagen sin marcador) no genera error en la mayoría de los collators —desalinea silenciosamente imagen y texto, y el modelo "entrena pero no aprende nada". Valida el mapeo 1:1 de marcador a multimedia antes de comenzar el entrenamiento, en cada ejemplo, no solo en una muestra. Detalle completo de la lista de verificación: references/collators-and-pitfalls.md.
• Presupuesto de resolución min_pixels/max_pixels. Este par es el hiperparámetro más importante para calidad y memoria en SFT de VLM —más que el rango, alfa o LR. Un valor demasiado bajo reduce la resolución de las imágenes por debajo de lo que la tarea necesita (el texto pequeño en documentos se vuelve ilegible aunque el entrenamiento "tenga éxito"); demasiado alto supera el presupuesto de memoria de activaciones o fuerza un tamaño de lote demasiado pequeño para entrenar de manera estable. Ajústalo deliberadamente por dataset, no lo dejes en el valor predeterminado del framework.

Aspectos Específicos de Unsloth

• UnslothVisionDataCollator es el collator que Unsloth espera para SFT de VLM —maneja la alineación de etiquetas de imagen y el contrato del procesador por arquitectura descrito en references/collators-and-pitfalls.md. No sustituyas un collator solo texto para datos VLM.
• finetune_vision_layers=False es obligatorio cuando fast_inference=True. vLLM no puede servir adaptadores LoRA en capas de visión, por lo que una configuración de inferencia rápida que también descongele capas de visión falla en el momento de servir incluso si el entrenamiento tiene éxito. Si la receta requiere descongelar las últimas 6 capas ViT (ver Cuándo Descongelar arriba), la inferencia rápida queda descartada para esa ejecución —elige uno u otro, no ambos.

Elección del Modelo

La elección del VLM base está fuera del alcance de este skill —se encuentra en un solo lugar, el catálogo de modelos en finetuning-method-selection's references/model-catalog.md. Este skill y sus referencias describen recetas solo por familia de arquitectura, nunca recomendando un modelo sobre otro.

El aprendizaje por refuerzo en VLM (VLM-GRPO) es solo de referencia en este plugin —las herramientas fragmentadas y los modos de fallo por manipulación de recompensa específicos de VLM-RL se cubren en grpo-rlvr-training, no aquí. El alcance de este skill se detiene en el ajuste fino supervisado.

Modos de Falla

El error recurrente en todas las secciones anteriores es tratar una curva de pérdida limpia como prueba de que la ejecución es saludable. Una curva de aspecto normal es consistente tanto con una ejecución que funciona como con cualquiera de los asesinos silenciosos, ya que el modelo entrena con algo en cualquier caso —simplemente no con la señal alineada de imagen-texto cuando hay un asesino presente. Una puntuación de evaluación plana junto a una curva de pérdida normal significa volver a ejecutar la lista de verificación en references/collators-and-pitfalls.md antes de tocar cualquier hiperparámetro.

Referencias

• references/collators-and-pitfalls.md — tabla de collators por arquitectura, ejemplos de formato de dataset con marcadores de imagen, una lista de verificación de validación previa al entrenamiento y la receta de alineación del proyector en dos etapas como un patrón avanzado.

Skills relacionados: finetuning-method-selection enruta aquí; lora-qlora-recipes cubre los fundamentos de LoRA solo texto que este skill especializa; grpo-rlvr-training cubre VLM-RL (solo referencia); dataset-curation cubre la preparación de datasets de imagen+texto que este skill no aborda.