> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quantização

> Reduza memória com treinamento quantizado

# Quantização

A quantização reduz o uso de memória usando precisão menor para pesos do modelo.

## Início Rápido

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-8B \
  --data-path ./data.jsonl \
  --project-name quantized-model \
  --peft \
  --quantization int4
```

## Python API

```python theme={null}
from autotrain.trainers.clm.params import LLMTrainingParams

params = LLMTrainingParams(
    model="meta-llama/Llama-3.2-8B",
    data_path="./data.jsonl",
    project_name="quantized-model",

    peft=True,
    quantization="int4",  # or "int8"
    lora_r=16,
)
```

## Opções de Quantização

| Opção | Redução de Memória | Qualidade |
| ----- | ------------------ | --------- |
| None  | 0%                 | Melhor    |
| int8  | \~50%              | Muito Boa |
| int4  | \~75%              | Boa       |

## Tarefas Suportadas

A quantização está disponível para:

| Tarefa  | Classe Params       | Notas            |
| ------- | ------------------- | ---------------- |
| LLM     | `LLMTrainingParams` | Suporte completo |
| VLM     | `VLMTrainingParams` | Suporte completo |
| Seq2Seq | `Seq2SeqParams`     | Suporte completo |

### 4-bit (QLoRA)

Máxima economia de memória:

```python theme={null}
params = LLMTrainingParams(
    ...
    quantization="int4",
)
```

### 8-bit

Melhor qualidade, menos economia:

```python theme={null}
params = LLMTrainingParams(
    ...
    quantization="int8",
)
```

## Requisitos de Memória

### Llama 3.2 8B

| Config            | VRAM Necessário |
| ----------------- | --------------- |
| Precisão completa | \~64 GB         |
| LoRA (fp16)       | \~18 GB         |
| LoRA + 8bit       | \~12 GB         |
| LoRA + 4bit       | \~8 GB          |

### Gemma 2 27B

| Config            | VRAM Necessário |
| ----------------- | --------------- |
| Precisão completa | \~108 GB        |
| LoRA + 4bit       | \~20 GB         |

## Melhores Práticas

### Use com LoRA

A quantização **requer** que PEFT/LoRA esteja habilitado:

```python theme={null}
params = LLMTrainingParams(
    ...
    peft=True,  # Required for quantized training
    quantization="int4",
)
```

<Warning>
  A quantização só funciona quando `peft=True`. Sem PEFT habilitado, a configuração de quantização será ignorada.
</Warning>

### Ajuste a Taxa de Aprendizado

O treinamento quantizado geralmente se beneficia de uma taxa de aprendizado maior que o padrão (`3e-5`):

```python theme={null}
params = LLMTrainingParams(
    ...
    peft=True,
    quantization="int4",
    lr=2e-4,  # Higher LR works well with QLoRA
)
```

### Use Flash Attention

Combine com [Flash Attention](/advanced/flash-attention) para velocidade:

```python theme={null}
params = LLMTrainingParams(
    ...
    quantization="int4",
    use_flash_attention_2=True,  # Requires Linux + CUDA + flash-attn package
)
```

## Inferência com Modelos Quantizados

Carregue modelos quantizados para inferência:

```python theme={null}
import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

# 4-bit config (matches AITraining defaults)
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_use_double_quant=False,
)

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-8B",
    quantization_config=bnb_config,
)
```

## Requisitos de Plataforma

<Warning>
  **A quantização só funciona no Linux.** A biblioteca `bitsandbytes` necessária para quantização int4/int8 está disponível apenas em sistemas Linux.
</Warning>

## Nota sobre Apple Silicon (MPS)

A quantização **não é compatível com Apple Silicon MPS**. Quando você usa quantização em um Mac com M1/M2/M3:

* O treinamento automaticamente volta para CPU
* Você verá uma mensagem de aviso explicando isso
* Para treinamento mais rápido no Mac, pule a quantização e use apenas LoRA

```bash theme={null}
# No Apple Silicon - use LoRA sem quantização para aceleração MPS
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data.jsonl \
  --project-name mac-training \
  --peft \
  --lora-r 16
```

Variáveis de ambiente para controle manual:

* `AUTOTRAIN_DISABLE_MPS=1` - Forçar treinamento em CPU
* `AUTOTRAIN_ENABLE_MPS=1` - Forçar MPS mesmo com quantização (pode travar)

## Considerações de Qualidade

A quantização reduz ligeiramente a qualidade. Para aplicações críticas:

1. Teste em sua tarefa específica
2. Compare com baseline de precisão completa
3. Considere 8-bit se qualidade importar mais

## Próximos Passos

<CardGroup cols={2}>
  <Card title="LoRA/PEFT" href="/advanced/lora-peft">
    Fine-tuning eficiente
  </Card>

  <Card title="Flash Attention" href="/advanced/flash-attention">
    Otimizações de velocidade
  </Card>
</CardGroup>