Ajuste Fino Supervisionado Visão-Linguagem (Vision-Language SFT)
Este skill assume que finetuning-method-selection já encaminhou para aqui: o formato dos dados são demonstrações de imagem+texto, não pares de preferência ou um sinal de recompensa verificável, e a base é um modelo de linguagem visual (VLM), não um modelo apenas de texto. lora-qlora-recipes cobre a receita LoRA/QLoRA apenas para texto que este skill especializa para a torre de visão e o projetor; leia esse skill primeiro se os fundamentos do LoRA (rank, alpha, módulos alvo) ainda não forem familiares.
Entrada: um conjunto de dados de imagem+texto e um modelo base VLM já selecionado do catálogo de modelos.
Formato de saída: uma configuração de adaptador validada — quais componentes estão congelados, módulos alvo do LoRA e um orçamento min_pixels/max_pixels — que o llm-finetuning-training-engineer consome diretamente ao gerar um script executável.
Referência Rápida
| Situação | Padrão |
|---|---|
| Adaptar comportamento em imagens familiares | Torre+projetor congelados, LoRA r=8–16, α=16–32 |
| Mudança de domínio visual | Descongelar últimas 6 camadas ViT, LR da visão 5–10x menor |
| Não cabe em bf16 com o rank alvo | QLoRA — apenas torre de visão congelada |
fast_inference=True | finetune_vision_layers=False |
| Perda normal, avaliação não melhora | Verifique primeiro os Dois Assassinos Silenciosos abaixo |
A Receita Consensual
Congele a torre de visão e o projetor. Aplique LoRA apenas no LLM, em todas as camadas lineares (a mesma lista de alvos de atenção + MLP do SFT apenas para texto — veja lora-qlora-recipes), com r=8–16, α=16–32. Este é o padrão consolidado para adaptar o comportamento de um VLM sem perturbar sua capacidade de visão.
- A torre de visão e o projetor permanecem congelados por padrão. Eles já codificam uma representação visual geral; retreiná-los raramente é necessário e adiciona risco sem adicionar capacidade para a maioria das tarefas.
- O rank do LoRA é menor que o padrão geral apenas para texto (r=8–16 aqui vs r=16–32 para SFT apenas texto) porque o adaptador apenas no LLM está adaptando comportamento, não injetando novo conhecimento visual.
- QLoRA é permitido apenas com a torre de visão congelada. Quantizar a base enquanto também descongela e treina camadas de visão não é suportado e é instável — trate isso como uma regra de pareamento rígida, não um parâmetro ajustável. Se a torre de visão precisar ser descongelada, abandone o QLoRA e use LoRA em bf16.
# congelar torre + projetor; LoRA apenas no 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",
] # Apenas LLM, todas lineares — r=8-16, alpha=16-32
Quando Descongelar
Descongelar camadas de visão é uma escalada deliberada, não uma decisão padrão — recorra a ela apenas quando a mudança de domínio for visual, não textual.
- Descongele apenas para mudança de domínio visual. Se a tarefa é ensinar um novo comportamento em imagens que a torre já entende (gráficos, fotos do cotidiano), a receita de torre congelada acima é suficiente. Descongele quando o domínio visual em si for desconhecido para a torre — imagens de satélite, exames médicos, diagramas técnicos densos — e a receita de torre congelada estagnar.
- Últimas 6 camadas ViT é o ponto ideal. Descongelar as últimas seis camadas do transformador de visão (não a torre inteira) mediu +1,7 p.p. no DocVQA com ~1,75x o custo de treinamento em comparação com a linha de base congelada. Trate seis camadas como o teto que vale a pena pagar; ir além gasta computação sem um resultado correspondente.
- O LR da visão deve ser 5–10x menor que o LR do LLM quando descongelado. A representação pré-treinada da torre de visão é mais frágil que o adaptador do LLM; o mesmo LR para ambos corre o risco de sobrescrever a representação visual mais rápido do que o adaptador do LLM pode compensar.
- Rank alto de LoRA na camada de patch embedding corre risco de NaN. Se a camada de patch embedding estiver no conjunto descongelado, mantenha seu rank baixo e monitore a perda nos primeiros passos de perto — um dos lugares mais frágeis para aplicar LoRA em um VLM.
Os Dois Assassinos Silenciosos
Ambos produzem uma execução que treina sem erro e sem aprendizado: a curva de perda parece normal, o modelo não melhora e nenhum deles lança uma exceção — ambos precisam de uma verificação explícita pré-treinamento, não apenas de um log de treinamento limpo.
- Incompatibilidade na contagem de tags de imagem. Cada token de placeholder de imagem no texto formatado deve mapear 1:1 para um item de mídia realmente passado ao collator. Uma incompatibilidade (um placeholder, zero ou duas imagens anexadas; ou uma imagem sem placeholder) não gera erro na maioria dos collators — ela silenciosamente desalinha imagem e texto, e o modelo "treina mas não aprende nada". Valide o mapeamento 1:1 de placeholder para mídia antes do treinamento começar, em cada exemplo, não apenas em uma amostra. Detalhe completo da lista de verificação:
references/collators-and-pitfalls.md. - Orçamento de resolução
min_pixels/max_pixels. Este par é o hiperparâmetro único mais consequente para qualidade e memória no SFT de VLM — mais que rank, alpha ou LR. Muito baixo silenciosamente reduz a resolução das imagens abaixo do necessário para a tarefa (texto pequeno de documento se torna ilegível mesmo que o treinamento "tenha sucesso"); muito alto estoura o orçamento de memória de ativação ou força um batch muito pequeno para treinar de forma estável. Defina-o deliberadamente por conjunto de dados, não deixe no padrão do framework.
Especificidades do Unsloth
UnslothVisionDataCollatoré o collator que o Unsloth espera para SFT de VLM — ele lida com o alinhamento de tags de imagem e o contrato do processador por arquitetura descrito emreferences/collators-and-pitfalls.md. Não substitua um collator apenas de texto para dados de VLM.finetune_vision_layers=Falseé obrigatório quandofast_inference=True. vLLM não pode servir adaptadores LoRA em camadas de visão, portanto, uma configuração de inferência rápida que também descongela camadas de visão falha no momento do serviço, mesmo que o treinamento tenha sucesso. Se a receita exigir descongelar as últimas 6 camadas ViT (veja Quando Descongelar acima), a inferência rápida está fora de questão para essa execução — escolha um ou outro, não ambos.
Escolha do Modelo
A escolha do modelo VLM base está fora do escopo deste skill — ela reside em um único lugar, o catálogo de modelos em references/model-catalog.md do finetuning-method-selection. Este skill e suas referências descrevem receitas apenas por família de arquitetura, nunca recomendando um modelo em detrimento de outro.
O aprendizado por reforço de VLM (VLM-GRPO) é apenas de referência neste plugin — as ferramentas fragmentadas e modos de falha de recompensa específicos de VLM-RL são cobertos em grpo-rlvr-training, não aqui. O escopo deste skill termina no ajuste fino supervisionado.
Modos de Falha
O erro recorrente em cada seção acima é tratar uma curva de perda limpa como prova de que a execução está saudável. Uma curva de aparência normal é consistente tanto com uma execução funcional quanto com qualquer um dos assassinos silenciosos, já que o modelo treina em algo de qualquer forma — apenas não no sinal alinhado de imagem-texto quando um assassino está presente. Uma pontuação de avaliação plana ao lado de uma curva de perda normal significa executar novamente a lista de verificação em references/collators-and-pitfalls.md antes de tocar em qualquer hiperparâmetro.
Referências
references/collators-and-pitfalls.md— tabela de collators por arquitetura, exemplos de formato de conjunto de dados com placeholders de imagem, uma lista de verificação de validação pré-treinamento e a receita de alinhamento do projetor em dois estágios como um padrão avançado.
Skills relacionados: finetuning-method-selection roteia para cá; lora-qlora-recipes cobre os fundamentos do LoRA apenas para texto que este skill especializa; grpo-rlvr-training cobre VLM-RL (apenas referência); dataset-curation cobre a preparação de conjuntos de dados de imagem+texto que este skill não aborda.