📚 Módulo 5: Configuração Prática — Hiperparâmetros, target_modules e Ambiente

5.1 Configuração do Ambiente (Google Colab)

Para executar QLoRA no Google Colab (gratuito), siga estes passos:

# Instalar dependências
!pip install -q bitsandbytes transformers accelerate peft trl

# Verificar GPU
import torch
print(f"GPU disponível: {torch.cuda.is_available()}")
print(f"Nome da GPU: {torch.cuda.get_device_name(0)}")

Nota: No Colab, certifique-se de selecionar uma GPU T4 (Runtime → Change runtime type → GPU).

5.2 Carregar o Modelo com Quantização de 4 bits

from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
import torch

# Configuração de quantização
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

# Carregar modelo e tokenizer
model_name = "Qwen/Qwen2.5-0.5B-Instruct"

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",  # Distribui automaticamente as camadas entre GPU/CPU
    trust_remote_code=True  # Requerido para alguns modelos como Qwen
)

tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)

5.3 Configurar LoRA/QLoRA

from peft import LoraConfig

lora_config = LoraConfig(
    r=8,                         # Dimensão da matriz de baixo rank
    lora_alpha=16,               # Fator de escala (tipicamente 2x r)
    target_modules=["q_proj", "v_proj"],  # Módulos onde aplicar LoRA
    lora_dropout=0.05,           # Dropout de regularização
    bias="none",                 # Não treinar vieses
    task_type="CAUSAL_LM"        # Tipo de tarefa: modelagem de linguagem causal
)

# Aplicar PEFT ao modelo
from peft import get_peft_model

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

Saída esperada:
trainable params: 327,680 || all params: 510,550,016 || trainable%: 0.0642

Isso confirma que apenas 0,06% dos parâmetros são treinados — mais de 510 milhões congelados!

5.4 Escolher target_modules

target_modules são as camadas do modelo onde as matrizes LoRA são inseridas. A seleção correta é crucial para o desempenho.

Em arquiteturas padrão (Llama, Mistral, Qwen):

• Recomendado: ["q_proj", "v_proj"] — Projeções de Query e Value em camadas de atenção.
• Alternativa: ["q_proj", "k_proj", "v_proj", "o_proj"] — Todas as projeções de atenção (mais parâmetros, possível melhoria em tarefas complexas).
• Opcional: Adicionar camadas MLP densas: ["gate_proj", "up_proj", "down_proj"] (em Llama) ou ["fc1", "fc2"] (em outros).

Como descobrir nomes de módulos no seu modelo:

# Listar todos os módulos lineares no modelo
from peft.utils import TRANSFORMERS_MODELS_TO_LORA_TARGET_MODULES_MAPPING

# Ou inspecionar manualmente
for name, module in model.named_modules():
    if isinstance(module, torch.nn.Linear):
        print(name)

Dica: Comece com ["q_proj", "v_proj"]. Se o desempenho for insuficiente, experimente adicionando mais módulos.

5.5 Outros Hiperparâmetros-Chave

• r (rank): Comece com 8. Se o modelo não aprender bem, tente 16 ou 32. Se ocorrer overfitting, reduza para 4.
• lora_alpha: Geralmente definido como 2 * r. Se r=8, alpha=16. Controla a "força" das atualizações LoRA.
• lora_dropout: 0,05 ou 0,1 para conjuntos de dados pequenos. 0,0 para conjuntos de dados grandes.
• bias: "none" é mais comum. "all" ou "lora_only" raramente melhoram o desempenho.