Para fazer fine-tuning com QLoRA em uma GPU de consumo de 16 GB, comece com um modelo pequeno, limite o comprimento das sequências e meça o pico de memória durante um treino curto. O tamanho anunciado da placa não garante que determinado modelo caiba: pesos, ativações, adaptadores e buffers disputam a mesma memória.
Este roteiro organiza um experimento de classificação de solicitações em português. A proposta é validar instalação, dados e salvamento do adaptador antes de ampliar o treinamento. O código é uma base reproduzível para adaptação, não um benchmark executado nesta reportagem nem uma promessa de desempenho no seu computador.
Resumo rápido
- Separe memória dos pesos de memória usada durante o treinamento.
- Comece com lote unitário e sequências curtas.
- Use dados sintéticos apenas para testar o funcionamento.
- Compare o adaptador com o modelo original em exemplos separados.
- Guarde versões, configuração e pico de memória junto ao resultado.
1. Defina o que o experimento precisa demonstrar
QLoRA combina uma base quantizada com pequenos conjuntos de parâmetros treináveis chamados adaptadores. A base permanece congelada; o aprendizado atualiza os adaptadores. A documentação do PEFT descreve esse caminho e a preparação necessária para treinar sobre pesos quantizados.
O primeiro objetivo aqui é operacional: carregar a base, completar algumas atualizações e salvar um adaptador que possa ser recarregado. O segundo, separado, é verificar se o comportamento melhorou. Um treino que termina sem erro não demonstra qualidade de classificação, domínio de português ou adequação a dados internos.
Se você ainda está escolhendo a técnica, consulte a introdução a LoRA e QLoRA. Se a necessidade é consultar informações que mudam frequentemente, compare também fine-tuning e RAG. Aqui o foco está no orçamento de memória e na execução de um pequeno ensaio local.
Defina previamente as categorias aceitas, quem revisa erros e quais casos podem permanecer sem classificação. Um modelo que responde qualquer rótulo com confiança aparente precisa de validação externa. Para uso operacional, a aplicação deve aceitar somente valores previstos e encaminhar saídas diferentes para revisão.
2. Faça o orçamento de memória antes do download
Quatro bits por parâmetro representam meio byte em uma conta idealizada dos pesos. Essa conta não inclui escalas de quantização, camadas mantidas em outra precisão, ativações, estados do otimizador, contexto CUDA ou memória ocupada pela interface gráfica. Portanto, não use a multiplicação como estimativa do consumo total.
| Componente | O que aumenta o consumo | Primeira ação |
|---|---|---|
| Pesos da base | Mais parâmetros e módulos não quantizados | Escolher uma base menor |
| Ativações | Sequências e lotes maiores | Reduzir comprimento e lote |
| Adaptadores | Rank e quantidade de camadas | Começar com rank modesto |
| Otimizador | Quantidade de parâmetros treináveis | Conferir parâmetros liberados |
| Ambiente | Outros processos e buffers | Medir memória livre antes do treino |
Não comprometa toda a memória nominal no planejamento. Registre a memória livre no início e o pico observado no primeiro teste. A margem necessária depende do ambiente; evite transformar uma folga arbitrária em regra universal. Um monitor conectado à mesma placa e outros aplicativos podem alterar a disponibilidade entre execuções.
Gradient checkpointing economiza ativações armazenadas ao refazer parte do cálculo. Acumulação de gradientes permite combinar vários microlotes antes da atualização. Essas técnicas têm custos e não tornam o consumo independente do comprimento. Aumente apenas uma variável por ensaio para descobrir qual mudança provocou o problema.
3. Prepare o ambiente e um conjunto mínimo
Use um ambiente Python isolado, com PyTorch instalado para a combinação de sistema, driver e CUDA da máquina. Consulte os requisitos oficiais do bitsandbytes antes de instalar: ter 16 GB de VRAM não demonstra compatibilidade com todos os kernels. O roteiro abaixo pressupõe uma GPU NVIDIA acessível pelo PyTorch e usa uma única placa.
Em um terminal Linux ou WSL com acesso à GPU, crie o ambiente e instale as bibliotecas depois de configurar o PyTorch compatível. O comando não fixa versões porque a escolha precisa acompanhar seu ambiente; após validar o teste, gere um arquivo de versões e reutilize esse conjunto nos próximos ensaios.
python -m venv .venv
source .venv/bin/activate
python -m pip install transformers peft accelerate bitsandbytes datasets
python -m pip freeze > ambiente.txt
python -c "import torch; print(torch.cuda.is_available())"
nvidia-smiSe a verificação retornar falso, resolva a instalação antes de baixar a base. Não tente compensar um ambiente sem GPU com mudanças no adaptador. Guarde a saída de diagnóstico, o sistema operacional e o modelo exato da placa. Esses dados tornam uma falha reproduzível para quem prestar suporte.
O cartão oficial de Qwen2.5-0.5B-Instruct fornece uma base pequena para o ensaio. A escolha reduz a complexidade inicial e não constitui recomendação de qualidade para sua tarefa. Leia a licença e registre a revisão do repositório usada. Para reprodução rigorosa, passe essa revisão ao carregamento do modelo e do tokenizer.
4. Execute um treino curto e salve o adaptador
Salve o código abaixo como treinar.py. Os exemplos são artificiais e repetidos de propósito para um teste de funcionamento. Eles não servem para avaliar generalização. O comprimento de 128 tokens, o rank 8 e os quatro passos são escolhas conservadoras deste roteiro, não limites das bibliotecas.
import torch
from datasets import Dataset
from transformers import (AutoTokenizer, AutoModelForCausalLM,
BitsAndBytesConfig, TrainingArguments, Trainer,
DataCollatorForLanguageModeling)
from peft import (LoraConfig, get_peft_model,
prepare_model_for_kbit_training)
if not torch.cuda.is_available():
raise RuntimeError("Configure uma GPU CUDA antes de continuar")
base = "Qwen/Qwen2.5-0.5B-Instruct"
bf16 = torch.cuda.is_bf16_supported()
dtype = torch.bfloat16 if bf16 else torch.float32
tokenizer = AutoTokenizer.from_pretrained(base)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "right"
pares = [
("Preciso da segunda via da cobrança", "financeiro"),
("O aplicativo não abre", "suporte"),
("Quero conhecer os planos", "comercial"),
]
textos = [tokenizer.apply_chat_template([
{"role": "user", "content": "Classifique: " + pergunta},
{"role": "assistant", "content": resposta}
], tokenize=False) for pergunta, resposta in pares] * 8
dados = Dataset.from_dict({"text": textos})
dados = dados.map(lambda x: tokenizer(x["text"],
truncation=True, max_length=128),
batched=True, remove_columns=["text"])
quant = BitsAndBytesConfig(load_in_4bit=True,
bnb_4bit_quant_type="nf4", bnb_4bit_use_double_quant=True,
bnb_4bit_compute_dtype=dtype)
modelo = AutoModelForCausalLM.from_pretrained(base,
quantization_config=quant, device_map={"": 0})
modelo.config.use_cache = False
modelo = prepare_model_for_kbit_training(modelo)
modelo = get_peft_model(modelo, LoraConfig(r=8, lora_alpha=16,
target_modules="all-linear", lora_dropout=0.05,
bias="none", task_type="CAUSAL_LM"))
modelo.print_trainable_parameters()
args = TrainingArguments(output_dir="ensaio-qlora",
per_device_train_batch_size=1,
gradient_accumulation_steps=4, max_steps=4,
learning_rate=2e-4, gradient_checkpointing=True,
bf16=bf16, fp16=False, optim="adamw_torch",
logging_steps=1, save_strategy="no", report_to="none")
treinador = Trainer(model=modelo, args=args, train_dataset=dados,
data_collator=DataCollatorForLanguageModeling(
tokenizer=tokenizer, mlm=False))
torch.cuda.reset_peak_memory_stats()
treinador.train()
print("Pico alocado GiB:", torch.cuda.max_memory_allocated()/2**30)
print("Pico reservado GiB:", torch.cuda.max_memory_reserved()/2**30)
modelo.save_pretrained("adaptador-ensaio")
tokenizer.save_pretrained("adaptador-ensaio")Execute python treinar.py e guarde o log. O código treina a sequência completa, incluindo a pergunta. Para um treinamento supervisionado real que calcule a perda apenas sobre a resposta, prepare uma máscara de rótulos e teste essa máscara explicitamente. Não presuma que o collator simples faça essa separação.
A ausência de BF16 leva este exemplo a computação em float32, com outro perfil de memória e velocidade. Isso privilegia clareza no ensaio e não é uma configuração universalmente eficiente. A escolha de precisão deve ser revisada depois que o caminho básico estiver validado no hardware disponível.
5. Exemplo: triagem de atendimento em Campinas
Considere, como situação ilustrativa, uma distribuidora de Campinas que recebe mensagens sobre cobrança, suporte e orçamento. A equipe dispõe de uma estação com GPU de 16 GB e quer avaliar se um adaptador mantém a resposta restrita às três categorias. Não há resultado comercial medido neste exemplo.
O responsável seleciona mensagens autorizadas, remove identificadores desnecessários e divide os dados por conversa, evitando que trechos da mesma interação apareçam no treino e no teste. Mensagens quase iguais também precisam ser agrupadas. Caso contrário, a avaliação pode premiar memorização de textos já vistos.
Depois do teste sintético, a equipe substitui o conjunto de treino por exemplos revisados e mantém a avaliação separada. Compara o modelo original e o adaptador nas mesmas entradas, com a mesma instrução e os mesmos parâmetros de geração. Registra acertos por classe, saídas inválidas e casos ambíguos.
Uma mensagem como “paguei, mas meu acesso continua bloqueado” pode envolver financeiro e suporte. A decisão sobre rótulo único, múltiplos rótulos ou revisão humana pertence ao processo de atendimento. A equipe precisa resolver essa convenção antes de atribuir o erro ao tamanho do modelo.
Antes de ampliar o piloto, recarregue a base e o adaptador em um processo novo usando PeftModel.from_pretrained. Execute algumas entradas conhecidas e confirme que o diretório salvo contém os arquivos esperados. Salvar não basta: a restauração deve fazer parte do critério de aceitação.
Erros comuns
Confundir carregar com treinar. O carregamento pode funcionar e a primeira retropropagação falhar. Meça o pico durante o treino inteiro, não apenas depois do download. Observe também a memória reservada e outros processos com ferramentas do sistema.
Aumentar todas as configurações juntas. Se faltar memória, reduza primeiro o comprimento ou use uma base menor, mantendo registro das mudanças. Reinicie o processo após a falha para evitar comparar estados diferentes do alocador. Não apague checkpoints úteis para tentar corrigir falta de VRAM.
Avaliar nos exemplos repetidos. A perda menor no conjunto sintético apenas mostra adaptação àqueles textos. Não autoriza implantação. Separe um conjunto realista, documente erros e confira se o modelo deixou de seguir instruções que antes atendia.
Esquecer a dependência da base. O adaptador não substitui automaticamente todos os pesos originais. Preserve identificador, revisão, licença, tokenizer e configuração. Mudanças nesses componentes podem alterar o resultado ou impedir o carregamento.
Perguntas frequentes
Qualquer GPU de 16 GB funciona?
Não. Capacidade é apenas um requisito. Arquitetura, drivers, sistema e bibliotecas determinam compatibilidade. Este roteiro pressupõe CUDA; outros backends exigem configuração própria e consulta aos requisitos oficiais.
Posso trocar a base por um modelo maior?
Pode testar uma base compatível, mas não existe garantia de caber. Refaça o orçamento, confira licença e tokenizer, comece com lote unitário e meça o primeiro treino antes de aumentar o comprimento.
Preciso manter os textos originais?
Mantenha apenas o que sua política de dados autoriza. Para rastreabilidade, registre a versão do conjunto, critérios de preparação e divisão. Evite deixar dados pessoais desnecessários em logs e diretórios de experimentos.
O adaptador melhora automaticamente o português?
Não. O resultado depende da base, dos exemplos e da tarefa. Avalie especificamente linguagem, categorias e situações que importam para o trabalho. Um pequeno teste operacional não mede fluência geral.
