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

# Entrenamiento Distribuido

> Entrenamiento multi-GPU y multi-nodo con DDP y DeepSpeed

# Entrenamiento Distribuido

AITraining soporta entrenamiento multi-GPU a través de Accelerate, con optimización opcional DeepSpeed Zero-3 para modelos grandes.

## Requisitos

| Componente     | Requerido     | Instalar                |
| -------------- | ------------- | ----------------------- |
| Accelerate     | Sí (incluido) | Incluido con AITraining |
| DeepSpeed      | Opcional      | `pip install deepspeed` |
| Múltiples GPUs | Sí            | GPUs NVIDIA CUDA        |

## Backends de Distribución

| Backend   | Valor          | Descripción                                     |
| --------- | -------------- | ----------------------------------------------- |
| DDP       | `ddp` o `None` | PyTorch Distributed Data Parallel (por defecto) |
| DeepSpeed | `deepspeed`    | DeepSpeed Zero-3 con fragmentación automática   |

## Inicio Rápido

### DDP (Por Defecto)

Con múltiples GPUs, DDP se usa automáticamente:

```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, usa 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()
```

## Configuración 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
```

## Cómo Funciona

### Launch Accelerate

El entrenamiento se inicia a través de Accelerate:

1. AITraining detecta GPUs disponibles
2. Inicia entrenamiento vía `accelerate launch`
3. Para DeepSpeed, añade flags `--use_deepspeed` y Zero-3
4. Registra `accelerate env` para depuración

### Configuraciones DDP

Al usar DDP:

* `ddp_find_unused_parameters=False` se establece para rendimiento
* Cada GPU procesa una porción del batch
* Los gradientes se sincronizan entre GPUs

### DeepSpeed Zero-3

Al usar DeepSpeed:

* Los parámetros del modelo se fragmentan entre GPUs
* Usa `--deepspeed_multinode_launcher standard` para multi-nodo
* La configuración Zero-3 se aplica automáticamente
* El guardado de modelo usa `accelerator.get_state_dict()` con unwrapping

## Entrenamiento Multi-Nodo

Para entrenamiento DeepSpeed multi-nodo:

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

La flag `--deepspeed_multinode_launcher standard` se pasa automáticamente.

## Comportamiento Específico por Tarea

### Entrenamiento LLM

* Por defecto: DDP cuando se detectan múltiples GPUs
* DeepSpeed: Establecer explícitamente `--distributed-backend deepspeed`

### Seq2Seq y VLM

* Selecciona automáticamente DeepSpeed para casos de muchas GPUs
* Usa DDP multi-GPU para combinaciones PEFT + cuantización + bf16

## Checkpointing con DeepSpeed

<Warning>
  Al usar DeepSpeed, el guardado de adaptador PEFT se maneja de forma diferente. El `SavePeftModelCallback` no se usa; en su lugar, el guardado usa `accelerator.get_state_dict(trainer.deepspeed)` y desenvuelve el modelo.
</Warning>

## Selección de GPU

Controla qué GPUs usar:

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

# Usar todas las GPUs disponibles (por defecto)
aitraining llm --train ...
```

## Solución de Problemas

### Verificar Entorno Accelerate

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

### Problemas Comunes

| Problema                | Solución                                             |
| ----------------------- | ---------------------------------------------------- |
| DeepSpeed no encontrado | `pip install deepspeed`                              |
| Errores NCCL            | Verifica conectividad GPU y versión CUDA             |
| Errores OOM             | Reduce tamaño de batch o usa DeepSpeed               |
| Entrenamiento lento     | Asegúrate de que las GPUs están en el mismo bus PCIe |

## Próximos Pasos

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

  <Card title="Quantization" href="/advanced/quantization">
    Reducir uso de memoria
  </Card>
</CardGroup>