Hospedar modelos de linguagem locais é o primeiro passo para a soberania de dados. Contudo, para extrair resultados verdadeiramente corporativos e alinhados a regras de negócios complexas, muitas vezes a inferência de fábrica (out-of-the-box) não é suficiente. Nesses casos, entender como fazer fine-tuning em modelos locais torna-se uma habilidade indispensável para desenvolvedores e engenheiros de IA.

Fazer o ajuste fino de modelos de ia 8b e 14b (como o Llama 3 8B ou Qwen 2.5 14B) permite alinhar o comportamento do assistente a padrões específicos de formatação (ex: saídas rigorosas em JSON ou XML), guiar o tom de comunicação e otimizar o uso de ferramentas de software corporativas. Conforme explicamos detalhadamente em nossa análise teórica sobre como tornar modelos de IA 8B e 14B mais inteligentes, o fine-tuning deve ser focado em moldar o comportamento e o estilo de raciocínio da IA, enquanto o conhecimento factual dinâmico deve vir de bases RAG.

Neste guia prático passo a passo, detalharemos nossa metodologia de treinamento e forneceremos os comandos e códigos Python necessários para você fazer o fine-tuning de modelos de parâmetros médios no seu próprio hardware. Para quem quer integrar esse modelo diretamente no editor de código, vale a pena ver o guia de programação com IAs locais utilizando Ollama e Continue. E se o seu objetivo é o desenvolvimento de software puro, verifique as diferenças entre os modelos na nossa análise sobre a melhor IA para código.

Nossa Metodologia de Teste e Transparência

Para estruturar este guia de como fazer fine-tuning, nossa equipe realizou diversos ciclos de treinamento utilizando hardware de consumo disponível no mercado corporativo. Estabelecemos os seguintes critérios objetivos para documentar esta metodologia:

• Hardware de Teste: Realizamos os treinamentos em uma única GPU Nvidia RTX 4090 (24 GB de VRAM) e em instâncias de nuvem baratas equipadas com GPUs Nvidia A10G (24 GB) e L4 (24 GB).
• Dataset Utilizado: Utilizamos o dataset estruturado tatsu-lab/alpaca para tarefas gerais de instrução e datasets sintéticos proprietários formatados em JSONL.
• Estabilidade do Treinamento: Monitoramos o consumo de VRAM e a perda de convergência (loss convergence) para garantir que as configurações propostas evitem erros fatais durante o treinamento.
• Imparcialidade: Nossa análise técnica baseia-se exclusivamente em bibliotecas open-source e em benchmarks de mercado. Não possuímos links patrocinados com fornecedores de hardware ou nuvem.

O que é Fine-Tuning e Quando Utilizar?

O fine-tuning (ajuste fino) consiste em pegar um modelo pré-treinado em bilhões de palavras e treiná-lo adicionalmente em um conjunto menor de dados de domínio específico. Diferentemente do pré-treino básico, que consome supercomputadores e milhões de dólares, o fine-tuning pode ser feito de forma econômica.

Existem dois cenários bem distintos onde o ajuste fino é recomendado:

• Ajuste de Formatação de Saída: Quando você precisa que o modelo responda estritamente em um layout sem textos explicativos adicionais. Útil para APIs e microsserviços.
• Adoção de Tom de Voz Corporativo: Fazer o modelo falar de acordo com o manual de estilo de atendimento e diretrizes da marca (branding).
• Ensino de Tarefas de Raciocínio Niche: Treinar a IA a classificar documentos sob critérios altamente subjetivos e específicos da sua empresa.

Se você precisa que a IA apenas consulte informações dinâmicas (como “qual o preço do produto X no estoque hoje”), **não use fine-tuning**. Para isso, implemente um sistema RAG comum.

Preparando o Ambiente Linux para Fine-Tuning

Antes de escrever qualquer código em Python, é fundamental preparar o ambiente do sistema operacional Linux (preferencialmente Ubuntu 22.04 LTS ou superior) com os drivers corretos. É altamente recomendável ter o driver NVIDIA e a versão do CUDA instalada de acordo com os requisitos do framework oficial PyTorch.

Execute os seguintes comandos no terminal para instalar as dependências de sistema necessárias:

# Atualizar o gerenciador de pacotes do sistema
sudo apt-get update && sudo apt-get upgrade -y

# Instalar o python3-pip e ambiente virtual
sudo apt-get install python3-pip python3-venv -y

# Criar e ativar um ambiente virtual dedicado
python3 -m venv llm-env
source llm-env/activate

# Instalar PyTorch com suporte para CUDA 12.1
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Com o PyTorch instalado e validando a GPU via `torch.cuda.is_available()`, instale as bibliotecas principais do ecossistema Hugging Face, incluindo a biblioteca de código aberto TRL (Transformer Reinforcement Learning), amplamente documentada na documentação oficial da Hugging Face:

# Instalar bibliotecas de transformers, PEFT (LoRA), TRL e bitsandbytes para quantização
pip install transformers peft trl bitsandbytes datasets accelerate tensorboard

Como Fazer Fine-Tuning do Llama 3 8B com QLoRA

A técnica do **QLoRA** quantiza os pesos do modelo original em 4 bits de precisão e insere pequenas matrizes extras (adapters) em pontos estratégicos de atenção. Isso permite que você ajuste o modelo de 8B consumindo menos de 10 GB de VRAM ativa durante o treino.

A forma mais moderna e integrada de rodar o Supervised Fine-Tuning (SFT) é criar um script Python completo configurando o `SFTTrainer`. Veja o código de treinamento prático abaixo:

import torch
from datasets import load_dataset
from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    BitsAndBytesConfig,
    TrainingArguments
)
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer

# 1. Definir os modelos e caminhos
model_id = "meta-llama/Meta-Llama-3-8B-Instruct"
dataset_name = "tatsu-lab/alpaca"

# 2. Configurar a quantização de 4 bits para QLoRA
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_use_double_quant=True
)

# 3. Carregar o modelo quantizado
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=bnb_config,
    device_map="auto"
)
model.config.use_cache = False

# 4. Carregar o Tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "right"

# 5. Configurar LoRA (Adaptadores de baixo ranking)
peft_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

# 6. Carregar o Dataset
dataset = load_dataset(dataset_name, split="train[:5000]")

# 7. Configurar os argumentos de treinamento
training_args = TrainingArguments(
    output_dir="./llama3-8b-qlora-output",
    num_train_epochs=1,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    optim="paged_adamw_8bit",
    save_steps=100,
    logging_steps=10,
    learning_rate=2e-4,
    weight_decay=0.001,
    fp16=True,
    max_grad_norm=0.3,
    warmup_ratio=0.03,
    lr_scheduler_type="cosine",
    report_to="tensorboard"
)

# 8. Inicializar e executar o SFTTrainer
trainer = SFTTrainer(
    model=model,
    train_dataset=dataset,
    peft_config=peft_config,
    dataset_text_field="text",
    max_seq_length=512,
    tokenizer=tokenizer,
    args=training_args
)

print("🚀 Iniciando o treinamento do modelo...")
trainer.train()

# 9. Salvar os adaptadores treinados
trainer.model.save_pretrained("./llama3-8b-qlora-final")
print("✅ Adaptador LoRA salvo com sucesso!")

Para iniciar o script acima, basta salvá-lo como `train.py` no diretório de trabalho e rodar o comando:

python3 train.py

Ajustes de Hardware para o Qwen 2.5 14B

Quando passamos para modelos maiores, como o **Qwen 2.5 14B**, a complexidade técnica e a demanda de VRAM aumentam de forma não linear. Embora a arquitetura do Qwen 2.5 ofereça melhor capacidade de raciocínio de código e suporte nativo a múltiplos idiomas, o treino de 14B exige ajustes finos nos hiperparâmetros de hardware:

• Gradient Accumulation (Acúmulo de Gradientes): Se você não possui VRAM suficiente para rodar batch sizes grandes, reduza o `per_device_train_batch_size` para 1 ou 2 e aumente o `gradient_accumulation_steps` para 8 ou 16. Isso simula um lote maior de dados sem estourar o limite de VRAM física da sua GPU.
• Otimizador de 8 bits Paged: Sempre utilize a opção `optim=”paged_adamw_8bit”`. Ela move partes do estado do otimizador para a memória RAM do sistema operacional quando a GPU está saturada, evitando falhas de alocação de memória.
• Max Sequence Length reduzido: Em modelos de 14B, diminua o `max_seq_length` inicial para 512 ou 1024 tokens. Contextos de 4k ou 8k exigem quantidades massivas de VRAM em modelos desse tamanho.

Tabela Comparativa de Recursos e VRAM Necessários

Para planejar seu setup computacional antes de iniciar o treinamento, estruturamos a seguinte tabela com base em testes reais de consumo de memória gráfica em diferentes estágios:

Erros comuns que impedem resultados

Ao iniciar o treinamento de modelos locais, é comum se deparar com comportamentos instáveis ou falhas de software. Os principais erros que você deve evitar incluem:

• 1. CUDA Out Of Memory (OOM): Acontece quando a GPU não consegue alocar espaço suficiente para as ativações e tensores de pesos do modelo. Resolva reduzindo o batch size ou desativando o uso de gradientes em contextos muito longos.
• 2. Pad Token ID indefinido: Llama 3 e modelos similares do ecossistema Meta não possuem um `pad_token` configurado de fábrica em seu tokenizer. Se você esquecer de declarar `tokenizer.pad_token = tokenizer.eos_token`, o script de treinamento falhará de forma catastrófica ou gerará respostas infinitas e desconexas.
• 3. Fusão incorreta do modelo final (Merge): Após o treinamento dos adaptadores, muitos desenvolvedores esquecem de fundir (merge) os pesos dos adaptadores LoRA de volta ao modelo base em 16 bits para uso em produção, resultando em latência desnecessária no carregamento posterior.

Vale a pena?

Entender **como fazer fine-tuning** e configurar o pipeline local **vale muito a pena** se a sua operação exige segurança, conformidade e velocidade em um fluxo de trabalho especializado e recorrente. O controle sobre os pesos do modelo permite customizações que seriam impossíveis de replicar em APIs prontas na nuvem.

Por outro lado, se a sua demanda técnica muda constantemente de foco ou se você não possui hardware NVIDIA moderno de 16 GB a 24 GB de VRAM à disposição, investir tempo e recursos na contratação de máquinas em nuvem apenas para realizar testes pontuais pode não trazer o retorno esperado. Nesses cenários simplificados, é mais aconselhável consumir recursos prontos de APIs proprietárias.

Perguntas Frequentes (FAQ)

É possível fazer fine-tuning de modelos locais no Windows?

Sim. Embora o Linux seja o ambiente ideal e com drivers CUDA mais eficientes, você pode executar o fine-tuning no Windows utilizando o WSL2 (Windows Subsystem for Linux), que dá acesso direto à GPU física através do subsistema Linux.

Qual a diferença entre LoRA e QLoRA?

No LoRA (Low-Rank Adaptation), o modelo de linguagem base é carregado na precisão padrão de 16 bits (float16) ou 32 bits (float32). No QLoRA (Quantized LoRA), o modelo base é carregado em uma versão quantizada e compactada de 4 bits (NormalFloat4), reduzindo drasticamente o consumo de VRAM e permitindo treinar modelos maiores em placas de consumo comuns.

Quantas épocas de treinamento são recomendadas no ajuste fino?

Para fins de alinhamento de comportamento e estilo com datasets como o Alpaca, normalmente de 1 a 3 épocas (epochs) são perfeitamente suficientes para que o modelo aprenda o novo formato. Treinar além disso sem dados diversificados causa superajuste e perda de capacidades lógicas do modelo.

Como fundir (merge) os adaptadores LoRA ao modelo original?

Após salvar os adaptadores no disco, você deve usar a função `model.merge_and_unload()` da biblioteca PEFT do Hugging Face. Isso funde permanentemente as matrizes LoRA treinadas aos pesos originais de 16 bits do modelo, criando um arquivo de modelo único e otimizado pronto para distribuição.

Para receber as últimas notícias e conteúdos exclusivos, inscreva-se na newsletter.