# Ajuste fino de um modelo

Pesos quantizados não podem ser atualizados diretamente por gradientes, portanto, você faz o ajuste fino de um modelo quantizado treinando um pequeno adaptador sobre os pesos quantizados congelados. Treinar um adaptador [LoRA](https://huggingface.co/docs/peft/main/en/conceptual_guides/lora) em um modelo de 4 bits é conhecido como QLoRA, e permite fazer o ajuste fino de um modelo que não caberia na memória em bf16.

[Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer) verifica o modelo antes do treinamento para garantir que:

- O método de quantização suporta treinamento. Consulte a coluna Fine-tune em [Escolher um método](./selecting).
- O modelo possui um adaptador treinável acoplado. Os métodos que suportam treinamento com quantização são a exceção, abordados [abaixo](#quantization-aware-training).
- O modelo não foi compilado com `torch.compile`.

## Treinar um adaptador

Instale o [PEFT](https://huggingface.co/docs/peft/index).

```bash
pip install -U peft
```

Carregue o modelo com um método que suporte treinamento, anexe um adaptador LoRA com [add_adapter()](/docs/transformers/main/pt/main_classes/peft#transformers.integrations.PeftAdapterMixin.add_adapter) e passe o modelo para [Trainer](/docs/transformers/main/pt/main_classes/trainer#transformers.Trainer). O exemplo abaixo usa 4-bit [bitsandbytes](./bitsandbytes) e pressupõe que `train_dataset` seja um conjunto de dados tokenizado.

```py
import torch
from peft import LoraConfig
from transformers import AutoModelForCausalLM, BitsAndBytesConfig, Trainer, TrainingArguments

quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3-0.6B",
    quantization_config=quantization_config,
    device_map="auto",
)

lora_config = LoraConfig(r=16, lora_alpha=32, target_modules="all-linear", task_type="CAUSAL_LM")
model.add_adapter(lora_config)

trainer = Trainer(
    model=model,
    args=TrainingArguments(output_dir="qwen3-qlora", bf16=True),
    train_dataset=train_dataset,
)
trainer.train()
```

Apenas os pesos do adaptador são treinados. Os pesos base quantizados permanecem congelados.

## Salvar o adaptador

[save_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.save_pretrained) salva apenas os pesos do adaptador, que ocupam alguns megabytes. Isso funciona com todos os métodos, inclusive aqueles que não conseguem salvar seus pesos quantizados.

```py
model.save_pretrained("qwen3-qlora-adapter")
```

Para usar o adaptador, carregue o modelo base com a mesma configuração de quantização e carregue o adaptador sobre ele. Consulte [Carregando um adaptador](../peft#loading-an-adapter) para mais detalhes.

## Treinamento com quantização

[BitNet](./bitnet) e [compressed-tensors](./compressed_tensors) podem treinar o modelo completo sem um adaptador, desde que os pesos permaneçam em uma forma treinável.

- O BitNet precisa de `linear_class="autobitlinear"` e `quantization_mode="online"` em [BitNetQuantConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.BitNetQuantConfig).
- compressed-tensors requer um checkpoint que não esteja comprimido, ou `dequantize=True` em [CompressedTensorsConfig](/docs/transformers/main/pt/main_classes/quantization#transformers.CompressedTensorsConfig). Checkpoints que usam os kernels FP8 não podem treinar.

Veja [Conceitos de quantização](./concept_guide) para saber como o treinamento consciente de quantização difere da quantização pós-treinamento.