Receitas LoRA & QLoRA

Esta habilidade assume que a decisão de roteamento já aconteceu — finetuning-method-selection já deveria ter apontado para cá porque a forma dos dados são demonstrações (SFT), não pares de preferência ou um sinal de recompensa verificável. O que se segue é a receita atual de melhores práticas para configurar o adaptador em si: quais módulos mirar, como dimensionar rank e alpha, qual taxa de aprendizado usar, e quando QLoRA oferece ganho real de espaço versus quando apenas adiciona risco. Preparação e verificações de qualidade do dataset são uma preocupação separada — veja dataset-curation.

Entrada: uma decisão de roteamento (SFT via LoRA/ QLoRA) mais uma classe de tamanho alvo. Formato de saída: uma configuração de adaptador validada — os valores de kwarg abaixo, não conselhos em formato livre — que llm-finetuning-training-engineer consome diretamente ao gerar um script executável.

A Receita de Referência

A receita de referência é "LoRA Sem Arrependimentos" (Thinking Machines/Schulman, 2025-09), agora a convenção estabelecida para SFT LoRA/QLoRA.

Módulos Alvo

Mire em módulos todos-lineares, não apenas atenção:

target_modules = [
    "q_proj", "k_proj", "v_proj", "o_proj",   # attention
    "gate_proj", "up_proj", "down_proj",      # MLP — matters most
]

As camadas MLP (gate_proj, up_proj, down_proj) são as mais importantes — o direcionamento apenas para atenção era a convenção antiga e mais fraca. Descartar módulos para economizar memória é um Modo de Falha abaixo, não uma otimização válida.

Alpha e Taxa de Aprendizado

• lora_alpha = 2 * r é a convenção estabelecida (resultado de "dimensões intrusas" da NeurIPS 2025). Não ajuste manualmente o alpha independentemente do rank — derive-o do rank a cada vez.
• Taxa de aprendizado LoRA ≈ 10x a LR equivalente de fine-tune completo. Especificamente para QLoRA, 2e-4 é o ponto de partida padrão. Tabelas completas de hiperparâmetros e exemplos práticos: references/hyperparameters.md.

Rank por Tarefa

O rank é moldado pela tarefa, não um único padrão global:

Rank mais alto não é automaticamente melhor — ele aumenta a capacidade de memorizar tão rápido quanto aumenta a capacidade de generalizar. Comece na linha que corresponde à tarefa e só suba uma linha se o rank menor subajustar mensuravelmente em avaliações retidas, não como uma proteção padrão.

Tamanho Efetivo do Lote

Mantenha o tamanho efetivo do lote abaixo de 32. Esta receita foi validada nessa escala — aumentar o tamanho efetivo do lote é uma extrapolação não testada, não um ganho de throughput gratuito.

Padrões Unsloth

Unsloth é a implementação de referência que este plugin assume como o caminho rápido padrão — exceto para SFT conversacional em formato de mensagens com assistant_only_loss=True, onde o trainer compilado do Unsloth 2026.7.x não tem caminho em formato de mensagens e a saída de escape TRL simples (references/unsloth-trl-mapping.md) é o padrão para essa combinação, não uma falha rara de regressão. Seus padrões de fábrica, e por que cada um está definido dessa forma:

• lora_dropout=0 — o caminho do kernel otimizado assume zero dropout; definir um valor não nulo anula a aceleração do kernel fundido.
• bias="none" — termos de bias adicionam parâmetros de adaptador para um ganho de qualidade negligenciável nesta faixa de rank.
• use_gradient_checkpointing="unsloth" — variante de checkpointing do Unsloth, não checkpointing vanilla do HF; economiza aproximadamente 30% de VRAM em relação a nenhum checkpointing.
• optim="adamw_8bit" — AdamW de 8 bits corta a memória do estado do otimizador com impacto negligenciável na qualidade na escala do adaptador LoRA/QLoRA.
• random_state fixo — fixa a inicialização LoRA para reprodutibilidade entre execuções; trate-o como qualquer outra seed, não como algo ajustável.

Estes aparecem juntos na chamada get_peft_model:

model = FastLanguageModel.get_peft_model(
    model,
    r=32,
    target_modules=target_modules,
    lora_alpha=64,               # 2 * r
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",
    random_state=3407,
)

Nomes exatos de kwarg e seus equivalentes em TRL puro/PEFT, mais uma configuração completa incluindo SFTConfig: references/unsloth-trl-mapping.md e references/hyperparameters.md.

LoRA vs QLoRA vs FT Completo

…