Ajuste Fino com Unsloth

Visão Geral

Unsloth treina LLMs com kernels customizados que reduzem o uso de VRAM e o tempo de passo sem alterar a matemática, o que torna o ajuste fino em GPU única prático em hardware que, de outra forma, daria OOM (Out Of Memory). Esta habilidade cobre o Unsloth Core — a API Python — pois é o que um agente pode controlar programaticamente; o aplicativo Desktop e a interface web Studio são interativos e estão fora do escopo.

As partes difíceis de uma execução do Unsloth não são a chamada de treinamento. São dimensionar o trabalho em relação à VRAM disponível, acertar o template de chat e a máscara de perda, e escolher um formato de exportação que o runtime de destino realmente consiga carregar. Esta habilidade cobre esses três.

Quando Usar Esta Habilidade

• Use ao ajustar fino um LLM em uma única GPU e a VRAM é a restrição limitante.
• Use quando uma execução de treinamento dá OOM e precisa ser redimensionada em vez de reescrita.
• Use ao fazer pós-treinamento de preferência ou RL (GRPO, DPO) em hardware de consumidor.
• Use quando um modelo ajustado fino deve ser exportado para GGUF, vLLM ou pesos de 16 bits mesclados.
• Use quando um ajuste fino "funcionou bem", mas o formato de saída do modelo está incorreto — geralmente um bug no template de chat ou na máscara de perda, não um bug de hiperparâmetro.

Não use esta habilidade quando

• O treinamento é multi-nó ou multi-GPU em larga escala. Use TRL puro com Accelerate/DeepSpeed.
• A arquitetura não é suportada pelo Unsloth. Volte para TRL; não force.
• O usuário deseja treinamento gerenciado na nuvem. Isso é Hugging Face Jobs, não Unsloth local.
• O usuário deseja a GUI Desktop ou Studio. Aponte-o para o instalador, não para esta habilidade.

Como Funciona

Passo 1: Dimensionar a execução antes de escrever o código

A VRAM é a restrição que decide todo o resto. Estime os pesos primeiro, depois deixe espaço para ativações e estado do otimizador:

Adicione aproximadamente 2-6 GB para ativações, escalando com max_seq_length e tamanho do lote. Trate esses como figuras de planejamento e confirme contra nvidia-smi na primeira execução — eles variam por arquitetura, implementação de atenção e tamanho do vocabulário.

Se a estimativa não couber, reduza nesta ordem: max_seq_length, depois o tamanho do lote (aumentando gradient_accumulation_steps para manter o lote efetivo constante), depois o rank do LoRA, depois o tamanho do modelo. Cortar o rank antes do comprimento da sequência geralmente custa mais qualidade do que economiza memória.

Passo 2: Carregar o modelo

import unsloth deve vir antes de transformers, trl ou peft. Unsloth aplica patches nessas bibliotecas no momento da importação; importá-las primeiro desabilita silenciosamente as otimizações.

import unsloth  # must be first
import os
import re
from unsloth import FastLanguageModel

def reviewed_revision(variable):
    revision = os.environ.get(variable, "")
    if re.fullmatch(r"[0-9a-fA-F]{40}", revision) is None:
        raise RuntimeError(f"{variable} must be a reviewed full 40-character Hub commit SHA")
    return revision.lower()

model_revision = reviewed_revision("UNSLOTH_MODEL_REVISION")
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = "unsloth/Qwen3-8B",
    revision = model_revision,
    max_seq_length = 2048,
    load_in_4bit = True,
    dtype = None,  # auto-detects bf16 where supported
)

Escolha o carregador que corresponde à modalidade: FastLanguageModel para LMs causais apenas de texto, FastVisionModel para modelos de visão-linguagem, FastModel quando a modalidade é decidida em tempo de execução.

O namespace do Hub unsloth/ contém cópias pré-quantizadas que baixam mais rápido e pulam um passe de quantização local. Repositórios upstream como Qwen/ ou meta-llama/ funcionam de forma idêntica. Antes de definir UNSLOTH_MODEL_REVISION, inspecione esse commit exato do Hub e obtenha aprovação para o download. Registre o repositório e a revisão completa com a execução; nunca substitua um branch, tag, intervalo ou padrão móvel.

Passo 3: Corrigir o template de chat antes do treinamento

Esta é a falha silenciosa mais comum. Uma execução com o template incorreto converge limpa e produz um modelo que ignora seus tokens de parada ou emite andaimes de prompt na inferência.

from unsloth.chat_templates import (
    get_chat_template,
    standardize_data_formats,

…