Fine-tuning com LoRA usando Unsloth no Google Colab

Dá para fazer fine-tuning com LoRA usando Unsloth direto no Google Colab, sem alugar GPU própria. O fluxo é este: abrir um notebook pronto da Unsloth, instalar a biblioteca, carregar um modelo aberto do Hugging Face em 4 bits, apontar para o seu dataset, treinar e salvar o adaptador LoRA. O Unsloth cuida do peso da memória, e é por isso que um modelo de 8 bilhões de parâmetros cabe numa GPU gratuita como a T4, algo que na configuração tradicional exigiria bem mais VRAM.

O ponto de atenção não é o código, que é curto, e sim o dataset e a decisão de treinar. Antes de começar, vale entender se o problema pede um modelo ajustado ou apenas um bom prompt com RAG. Este guia mostra o passo a passo real, com base na documentação oficial do Unsloth e do Hugging Face.

Resumo rápido

• Fine-tuning com LoRA ajusta apenas uma pequena fração dos pesos, o que reduz muito a VRAM necessária.
• Pela tabela oficial da Unsloth, um modelo de 8B em QLoRA (4 bits) precisa de cerca de 6 GB de VRAM; a T4 gratuita do Colab tem esse perfil.
• LoRA em 16 bits é mais preciso, mas consome da ordem de 4 vezes mais VRAM que o QLoRA.
• Dataset em formato de instrução (Alpaca) ou de conversa (ShareGPT) são os caminhos mais comuns para SFT.
• A documentação da Unsloth recomenda ranks como 16 ou 32 e 1 a 3 épocas como ponto de partida.
• Fine-tuning ensina comportamento e estilo; RAG entrega informação atualizada. Muita gente precisa dos dois.

Quando fine-tuning vale a pena (e quando não vale)

A própria documentação da Unsloth separa três objetivos que o fine-tuning atende: atualizar conhecimento, personalizar comportamento e otimizar para uma tarefa específica. O terceiro é o mais valioso na prática. Se você quer que o modelo responda sempre no tom da sua marca, siga um formato rígido de saída ou acerte em uma tarefa estreita que se repete muito, o ajuste tende a ajudar.

O erro clássico é tentar resolver com fine-tuning um problema de informação desatualizada. Se a sua dor é que o modelo não sabe o preço de hoje nem o conteúdo da sua base interna, isso é território de RAG: buscar o dado certo na hora e injetar no prompt. A documentação da Unsloth afirma que ferramentas de recuperação são excelentes para acessar informação atualizada de bases externas, e que combinar as duas abordagens rende os melhores resultados. Fine-tuning sozinho não substitui uma busca bem feita.

Cabe uma ressalva honesta. A Unsloth afirma que fine-tuning pode sim adicionar conhecimento novo, contrariando o mito de que ele só muda estilo. Isso é verdade, mas exige dataset de qualidade e cuidado, e continua sendo mais frágil para fatos que mudam toda semana do que uma busca em base viva.

Requisitos de GPU e VRAM

Segundo a documentação de requisitos da Unsloth, o treino roda em GPUs NVIDIA, AMD, Intel e em Mac. Para NVIDIA, o requisito mínimo é CUDA Compute Capability 7.0, faixa que inclui a T4 usada no Colab. O detalhe decisivo é a VRAM. A tabela oficial de requisitos, que a Unsloth descreve como mínimo absoluto, traz estes números:

Leia a tabela com atenção ao que ela implica para o Colab. Um modelo de 8B em QLoRA pede cerca de 6 GB, o que cabe na T4 gratuita. O mesmo modelo em LoRA de 16 bits pede em torno de 22 GB, o que já exige uma GPU maior, paga. A própria Unsloth explica que o QLoRA usa 4 bits e gasta cerca de 4 vezes menos VRAM que o LoRA de 16 bits, sendo um pouco mais lento e marginalmente menos preciso. Em outras palavras: a diferença entre caber no Colab gratuito ou não costuma ser a escolha entre QLoRA e LoRA.

Um aviso prático da documentação: um erro comum quando se estoura a memória é o tamanho do lote ser alto demais. A recomendação é usar valores pequenos, como 1, 2 ou 3, e compensar com acumulação de gradiente. Os números da tabela são mínimos e podem subir conforme o modelo e o comprimento de contexto.

Passo a passo no Google Colab

O caminho mais seguro no Colab é começar por um notebook pronto da Unsloth em vez de montar tudo do zero. A documentação mantém um catálogo de notebooks, e o guia de Colab mostra o exemplo abaixo como ponto de partida.

1. Abrir o notebook e conectar a GPU

No Colab, escolha um runtime com GPU (a opção gratuita oferece a T4). A documentação explica o básico do ambiente: cada célula tem um botão de play, as células devem rodar em ordem, e existe um botão para conectar ou reconectar a GPU. Rodar “tudo de uma vez” funciona como primeiro teste, mas pula a personalização.

2. Instalar a Unsloth e as dependências

A primeira célula instala o pacote da Unsloth e as bibliotecas de apoio. A instalação por pip já traz as versões compatíveis de torch, transformers e demais dependências, então não é preciso fixar versões na mão.

3. Carregar o modelo em 4 bits

O modelo é carregado com FastModel.from_pretrained. O guia de Colab da Unsloth traz um exemplo com o gpt-oss-20b, mas o mesmo padrão vale para outros modelos abertos do catálogo unsloth no Hugging Face. Os modelos pré-quantizados em 4 bits baixam mais rápido e evitam estouro de memória.

from unsloth import FastLanguageModel, FastModel
import torch
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset

max_seq_length = 2048
url = "https://huggingface.co/datasets/laion/OIG/resolve/main/unified_chip2.jsonl"
dataset = load_dataset("json", data_files={"train": url}, split="train")

model, tokenizer = FastModel.from_pretrained(
    model_name = "unsloth/gpt-oss-20b",
    max_seq_length = max_seq_length,
    load_in_4bit = True,
    load_in_8bit = False,
    load_in_16bit = False,
    full_finetuning = False,
)

4. Adicionar os adaptadores LoRA

É aqui que o LoRA entra. Em vez de ajustar todos os pesos do modelo, o LoRA adiciona matrizes finas e treina só uma pequena fração. A documentação da Unsloth resume: em um modelo de 70 bilhões de parâmetros, em vez de mudar os 70 bilhões de números, o LoRA acrescenta as matrizes A e B a cada peso e otimiza apenas cerca de 1% deles.

model = FastLanguageModel.get_peft_model(
    model,
    r = 16,
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj",
                      "gate_proj", "up_proj", "down_proj"],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = "unsloth",
    random_state = 3407,
    max_seq_length = max_seq_length,
)

Dois detalhes vêm da documentação de hiperparâmetros. Primeiro, o alvo LoRA deve cobrir as camadas lineares principais, de atenção (q_proj, k_proj, v_proj, o_proj) e MLP (gate_proj, up_proj, down_proj); a Unsloth diz que isso importa para igualar um fine-tuning completo e desaconselha remover módulos. Segundo, use_gradient_checkpointing = "unsloth" usa cerca de 30% menos VRAM e permite lotes maiores.

5. Preparar o dataset e treinar

O treino roda com o SFTTrainer. O exemplo oficial usa poucos passos apenas para demonstrar o fluxo.

trainer = SFTTrainer(
    model = model,
    train_dataset = dataset,
    tokenizer = tokenizer,
    args = SFTConfig(
        max_seq_length = max_seq_length,
        per_device_train_batch_size = 2,
        gradient_accumulation_steps = 4,
        warmup_steps = 10,
        max_steps = 60,
        logging_steps = 1,
        output_dir = "outputs",
        optim = "adamw_8bit",
        seed = 3407,
    ),
)
trainer.train()

6. Salvar o adaptador e testar

Ao final, salve o adaptador LoRA e faça inferência com ele para conferir o comportamento. A documentação do Unsloth também cobre salvar em GGUF, mesclar para 16 bits para uso com vLLM, continuar o treino a partir de um adaptador salvo e escrever um ciclo de avaliação.

Formatos de dataset que o Unsloth aceita

O dataset é a parte que mais decide o resultado. A documentação agrupa os formatos por tipo de treino: Raw Corpus para pré-treinamento continuado, Instruct e Conversation para ajuste supervisionado (SFT) e RLHF para aprendizado por reforço. Para a maioria dos casos de SFT, dois formatos dominam.

• Alpaca (instrução): cada exemplo tem os campos Instruction, Input (opcional) e Output. Serve para o modelo aprender a executar uma tarefa de um único turno e devolver o resultado esperado.
• ShareGPT (conversa): cada exemplo traz uma lista conversations com pares de from e value, alternando entre human e gpt. Serve para diálogos de múltiplos turnos.

A Unsloth recomenda aplicar o template de chat certo para o modelo escolhido. A biblioteca expõe CHAT_TEMPLATES, cujas chaves incluem, entre outras, chatml, llama-3, qwen-2.5, gemma-2 e mistral. Usar o template errado é uma das causas mais comuns de treino que não rende. O Hugging Face é a fonte natural de datasets: carregue dados com load_dataset e publique o resultado do seu ajuste em um repositório próprio.

Escolhendo os hiperparâmetros

A Unsloth recomenda usar os padrões da biblioteca como ponto de partida e só mexer nos parâmetros depois de entender o efeito. Os valores abaixo vêm do guia oficial de hiperparâmetros e não substituem um teste com os seus dados.

Vale entender a lógica. O rank controla a capacidade do adaptador: maior aprende mais, mas usa mais memória e pode levar a overfitting. As épocas têm retorno decrescente depois de três na maioria dos datasets de instrução. E o batch efetivo é o produto do batch size pela acumulação de gradiente; a Unsloth recomenda um valor em torno de 16 como ponto de partida e, para não estourar a memória, prefere sempre um batch size pequeno com acumulação maior.

Exemplo: consultoria de RH em Curitiba

Imagine uma consultoria de RH em Curitiba que responde às mesmas dezenas de dúvidas trabalhistas toda semana, sempre com um formato parecido: uma explicação curta e uma orientação. A equipe já tem um bom arquivo de respostas antigas, revisadas por advogados, no tom que a empresa usa com os clientes.

Nesse caso, o fine-tuning faz sentido pela parte de comportamento e formato. O dataset de conversa, no formato ShareGPT, é montado com esses pares de pergunta e resposta já aprovados. O objetivo não é ensinar leis novas ao modelo, e sim fazer com que ele responda no tom da casa e siga o formato que a consultoria adotou, inclusive em perguntas parecidas que cheguem ligeiramente diferentes. O treino roda no Colab com um modelo aberto pequeno em QLoRA, dado que cabe na GPU gratuita pela tabela oficial.

Já a parte de informação atualizada, como uma mudança recente na legislação ou um caso específico de um cliente, não deveria ser resolvida pelo ajuste. É trabalho de RAG: buscar o documento certo na hora de responder. Este é um cenário ilustrativo, para mostrar onde cada técnica encaixa. Não há aqui números de resultado nem de acurácia, porque variam demais de dataset para dataset.

Erros comuns

• Tentar resolver informação desatualizada com fine-tuning. Para dados que mudam, RAG é o caminho. A Unsloth recomenda combinar as duas abordagens.
• Estourar a VRAM por batch size alto. A documentação aponta esse como o erro mais comum de memória. Use lotes pequenos e acumulação.
• Usar LoRA de 16 bits achando que cabe no Colab gratuito. Um modelo de 8B pede cerca de 22 GB nesse modo, contra 6 GB em QLoRA.
• Deixar o template de chat errado. O dataset tem que seguir o template que o modelo espera, ou o treino não rende.
• Remover módulos do alvo LoRA para economizar memória. A Unsloth desaconselha: a economia é pequena e a qualidade cai.
• Passar de três épocas por padrão. O retorno diminui e o risco de decorar os dados aumenta.
• Ignorar o mínimo de CUDA Compute Capability. GPUs antigas demais não são suportadas para treino.

Perguntas frequentes

Dá para fazer fine-tuning de graça no Colab?

Sim, desde que o modelo caiba na memória da GPU gratuita. Pela tabela oficial da Unsloth, um modelo de 8B em QLoRA (4 bits) precisa de cerca de 6 GB de VRAM, o que cabe na T4 oferecida pelo Colab. Modelos maiores ou treino em 16 bits exigem GPU maior.

Qual a diferença entre LoRA e QLoRA?

LoRA usa precisão de 16 bits; QLoRA usa 4 bits. O LoRA é um pouco mais rápido e um pouco mais preciso, mas consome da ordem de 4 vezes mais VRAM. Em ambiente com memória limitada, como o Colab gratuito, o QLoRA costuma ser a escolha prática.

Fine-tuning substitui o RAG?

Não. A documentação da Unsloth afirma que RAG é excelente para acessar informação atualizada de bases externas e recomenda combinar as duas técnicas. O fine-tuning ensina comportamento e formato; o RAG entrega o dado do momento. Em muitos projetos, o ideal é usar os dois.

Quais formatos de dataset o Unsloth aceita?

De forma geral, Raw Corpus para pré-treinamento continuado, Instruct e Conversation para ajuste supervisionado (SFT) e RLHF para aprendizado por reforço. Na prática, o formato Alpaca (instrução) e o ShareGPT (conversa) cobrem a maior parte dos casos de SFT.

Quanto tempo leva o treino?

Depende do modelo, do dataset e do hardware. É por isso que este guia não cita tempos nem números de acurácia: variam demais de caso para caso. Comece com poucos passos para validar o fluxo, como faz o exemplo oficial, e só depois rode o treino completo.

Preciso de GPU NVIDIA?

Para NVIDIA, o requisito é CUDA Compute Capability 7.0 ou superior. A Unsloth também suporta GPUs AMD e Intel, além de Mac, com guias próprios. A T4 do Colab atende ao requisito de treino em NVIDIA.

Fontes e leitura recomendada

• Unsloth: Google Colab, mostra o exemplo oficial de fine-tuning no Colab e o passo a passo do ambiente.
• Unsloth: Requirements, traz a tabela de VRAM por tamanho de modelo em QLoRA e LoRA.
• Unsloth: Datasets Guide, descreve os formatos Alpaca e ShareGPT e como aplicar o template de chat.
• Unsloth: LoRA Hyperparameters Guide, recomenda rank, alpha, épocas, batch e acumulação de gradiente.
• Unsloth: FAQ e quando fine-tuning é a escolha certa, compara fine-tuning com RAG.
• Hugging Face: guia conceitual de LoRA (PEFT), explica a técnica por trás do adaptador.
• Hugging Face: Datasets, mostra como carregar e publicar conjuntos de dados para o treino.
• IA Mágica: Integrações com OpenAI e ChatGPT, para comparar o caminho de modelos abertos ajustados com o de modelos hospedados.