> ## 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.

# Treinamento Distribuído

> Treinamento multi-GPU e multi-nó com DDP e DeepSpeed

# Treinamento Distribuído

O AITraining suporta treinamento multi-GPU através do Accelerate, com otimização opcional DeepSpeed Zero-3 para modelos grandes.

## Requisitos

| Componente     | Obrigatório    | Instalar                |
| -------------- | -------------- | ----------------------- |
| Accelerate     | Sim (incluído) | Incluído com AITraining |
| DeepSpeed      | Opcional       | `pip install deepspeed` |
| Múltiplas GPUs | Sim            | GPUs NVIDIA CUDA        |

## Backends de Distribuição

| Backend   | Valor           | Descrição                                    |
| --------- | --------------- | -------------------------------------------- |
| DDP       | `ddp` ou `None` | PyTorch Distributed Data Parallel (padrão)   |
| DeepSpeed | `deepspeed`     | DeepSpeed Zero-3 com fragmentação automática |

## Início Rápido

### DDP (Padrão)

Com múltiplas GPUs, DDP é usado automaticamente:

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./data \
  --project-name my-model \
  --trainer sft \
  --peft
```

### DeepSpeed

Para modelos grandes, use DeepSpeed Zero-3:

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-3B \
  --data-path ./data \
  --project-name my-model \
  --trainer sft \
  --distributed-backend deepspeed \
  --peft
```

## Python API

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

params = LLMTrainingParams(
    model="meta-llama/Llama-3.2-3B",
    data_path="./data",
    project_name="distributed-model",

    trainer="sft",

    # Distribution
    distributed_backend="deepspeed",  # or None for DDP

    # Training
    epochs=3,
    batch_size=2,
    gradient_accumulation=4,
    mixed_precision="bf16",

    peft=True,
    lora_r=16,
)

project = AutoTrainProject(params=params, backend="local", process=True)
project.create()
```

## Configuração YAML

```yaml theme={null}
task: llm-sft
backend: local
base_model: meta-llama/Llama-3.2-3B
project_name: distributed-model

data:
  path: ./data
  train_split: train
  valid_split: null
  chat_template: tokenizer
  column_mapping:
    text_column: text

log: wandb

params:
  distributed_backend: deepspeed  # or null for DDP
  epochs: 3
  batch_size: 2
  gradient_accumulation: 4
  mixed_precision: bf16
  peft: true
  lora_r: 16
```

## Como Funciona

### Launch Accelerate

O treinamento é iniciado através do Accelerate:

1. AITraining detecta GPUs disponíveis
2. Inicia treinamento via `accelerate launch`
3. Para DeepSpeed, adiciona flags `--use_deepspeed` e Zero-3
4. Registra `accelerate env` para depuração

### Configurações DDP

Ao usar DDP:

* `ddp_find_unused_parameters=False` é definido para performance
* Cada GPU processa uma porção do batch
* Gradientes são sincronizados entre GPUs

### DeepSpeed Zero-3

Ao usar DeepSpeed:

* Parâmetros do modelo são fragmentados entre GPUs
* Usa `--deepspeed_multinode_launcher standard` para multi-nó
* Configuração Zero-3 é aplicada automaticamente
* Salvamento de modelo usa `accelerator.get_state_dict()` com unwrapping

## Treinamento Multi-Nó

Para treinamento DeepSpeed multi-nó:

```bash theme={null}
# Em cada nó
aitraining llm --train \
  --model meta-llama/Llama-3.2-3B \
  --data-path ./data \
  --project-name my-model \
  --distributed-backend deepspeed \
  --peft
```

A flag `--deepspeed_multinode_launcher standard` é passada automaticamente.

## Comportamento Específico por Tarefa

### Treinamento LLM

* Padrão: DDP quando múltiplas GPUs detectadas
* DeepSpeed: Definir explicitamente `--distributed-backend deepspeed`

### Seq2Seq e VLM

* Seleciona automaticamente DeepSpeed para casos de muitas GPUs
* Usa DDP multi-GPU para combinações PEFT + quantização + bf16

## Checkpointing com DeepSpeed

<Warning>
  Ao usar DeepSpeed, o salvamento de adaptador PEFT é tratado de forma diferente. O `SavePeftModelCallback` não é usado; em vez disso, o salvamento usa `accelerator.get_state_dict(trainer.deepspeed)` e desenrola o modelo.
</Warning>

## Seleção de GPU

Controle quais GPUs usar:

```bash theme={null}
# Usar GPUs específicas
CUDA_VISIBLE_DEVICES=0,1 aitraining llm --train ...

# Usar todas as GPUs disponíveis (padrão)
aitraining llm --train ...
```

## Solução de Problemas

### Verificar Ambiente Accelerate

```bash theme={null}
accelerate env
```

### Problemas Comuns

| Problema                 | Solução                                                  |
| ------------------------ | -------------------------------------------------------- |
| DeepSpeed não encontrado | `pip install deepspeed`                                  |
| Erros NCCL               | Verifique conectividade GPU e versão CUDA                |
| Erros OOM                | Reduza tamanho do batch ou use DeepSpeed                 |
| Treinamento lento        | Certifique-se de que GPUs estão no mesmo barramento PCIe |

## Próximos Passos

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

  <Card title="Quantization" href="/advanced/quantization">
    Reduzir uso de memória
  </Card>
</CardGroup>