# Iniciando scripts do Accelerate

No tutorial anterior, você foi apresentado a como modificar seu script de treinamento atual para usar o Accelerate. A versão final desse código é mostrada abaixo:

```python
from accelerate import Accelerator

accelerator = Accelerator()

model, optimizer, training_dataloader, scheduler = accelerator.prepare(
    model, optimizer, training_dataloader, scheduler
)

for batch in training_dataloader:
    optimizer.zero_grad()
    inputs, targets = batch
    outputs = model(inputs)
    loss = loss_function(outputs, targets)
    accelerator.backward(loss)
    optimizer.step()
    scheduler.step()
```

Mas como você executa esse código e faz com que ele utilize o hardware especial disponível?

Primeiro, você deve reescrever o código acima em uma função e torná-lo chamável como um script. Por exemplo:

```diff
  from accelerate import Accelerator
  
+ def main():
      accelerator = Accelerator()

      model, optimizer, training_dataloader, scheduler = accelerator.prepare(
          model, optimizer, training_dataloader, scheduler
      )

      for batch in training_dataloader:
          optimizer.zero_grad()
          inputs, targets = batch
          outputs = model(inputs)
          loss = loss_function(outputs, targets)
          accelerator.backward(loss)
          optimizer.step()
          scheduler.step()

+ if __name__ == "__main__":
+     main()
```

Em seguida, você precisa executá-lo com `accelerate launch`.

  É recomendável executar `accelerate config` antes de usar `accelerate launch` para configurar seu ambiente conforme sua preferência. Caso contrário, o Accelerate usará padrões muito básicos, dependendo da configuração do seu sistema.

## Usando accelerate launch

O Accelerate possui um comando de CLI especial para ajudar você a executar seu código no seu sistema por meio de `accelerate launch`. Esse comando encapsula todos os diferentes comandos necessários para iniciar seu script em várias plataformas, sem que você precise lembrar qual é cada um deles.

  Se você está familiarizado com a execução de scripts no PyTorch por conta própria, como com `torchrun`, você ainda pode fazer isso. Não é obrigatório usar `accelerate launch`.

Você pode executar seu script rapidamente usando:

```bash
accelerate launch {script_name.py} --arg1 --arg2 ...
```

Basta colocar `accelerate launch` no início do seu comando e passar os argumentos e parâmetros adicionais para o seu script em seguida, como de costume!

Como isso executa os vários métodos de spawn do torch, todas as variáveis de ambiente esperadas também podem ser modificadas aqui. Por exemplo, aqui está como usar `accelerate launch` com uma única GPU:

```bash
# for cuda device:
CUDA_VISIBLE_DEVICES="0" accelerate launch {script_name.py} --arg1 --arg2 ...
# for xpu device:
ZE_AFFINITY_MASK="0" accelerate launch {script_name.py} --arg1 --arg2 ...
```

Você também pode usar `accelerate launch` sem executar `accelerate config` primeiro, mas pode ser necessário passar manualmente os parâmetros de configuração corretos. Nesse caso, o Accelerate tomará algumas decisões de hiperparâmetros por você, por exemplo, se houver GPUs disponíveis, ele usará todas por padrão, sem a precisão mista. Veja como usar todas as GPUs e treinar com a precisão mista desativada:

```bash
accelerate launch --multi_gpu {script_name.py} {--arg1} {--arg2} ...
```

Ou especificando o número de GPUs a serem usadas:

```bash
accelerate launch --num_processes=2 {script_name.py} {--arg1} {--arg2} ...
```

Para ser mais específico, você deve passar os parâmetros necessários por conta própria. Por exemplo, veja como você também lançaria o mesmo script em duas GPUs usando precisão mista, evitando todos os avisos:

```bash
accelerate launch --multi_gpu --mixed_precision=fp16 --num_processes=2 {script_name.py} {--arg1} {--arg2} ...
```

Para uma lista completa dos parâmetros que você pode passar, execute:

```bash
accelerate launch -h
```

  Mesmo que você não esteja usando o Accelerate no seu código, ainda é possível usar o launcher para iniciar seus scripts!

Para uma visualização dessa diferença, aquele `accelerate launch` anterior em multi-gpu se pareceria com o seguinte usando `torchrun`:

```bash
MIXED_PRECISION="fp16" torchrun --nproc_per_node=2 --nnodes=1 {script_name.py} {--arg1} {--arg2} ...
```

Você também pode executar seu script utilizando o CLI de lançamento como um módulo Python, o que permite passar outros comportamentos de lançamento específicos do Python. Para isso, use `accelerate.commands.launch` em vez de `accelerate launch`:

```bash
python -m accelerate.commands.launch --num_processes=2 {script_name.py} {--arg1} {--arg2}
```

Se você deseja executar o script com outras flags do python, você pode passá-las da mesma forma que `-m`, como no exemplo abaixo que habilita stdout e stderr sem buffer:

```bash
python -u -m accelerate.commands.launch --num_processes=2 {script_name.py} {--arg1} {--arg2}
```

  Você também pode executar seu código na CPU! Isso é útil para fins de depuração e testes em modelos e conjuntos de dados pequenos.

```bash
accelerate launch --cpu {script_name.py} {--arg1} {--arg2}
```  

## Por que você deve sempre usar `accelerate config`

Por que é tão útil que você deve **sempre** executar `accelerate config`?

Lembre-se da chamada anterior para `accelerate launch` e também para `torchrun`? Após a configuração, para executar esse script com as partes necessárias, basta usar `accelerate launch` diretamente, sem passar nada mais:

```bash
accelerate launch {script_name.py} {--arg1} {--arg2} ...
```

## Configurações Personalizadas

Como brevemente mencionado anteriormente, o `accelerate launch` deve ser usado principalmente combinando configurações definidas com o comando `accelerate config`. Essas configurações são salvas em um arquivo `default_config.yaml` na sua pasta de cache para o Accelerate. Essa pasta de cache está localizada em (em ordem decrescente de prioridade):

- O conteúdo da sua variável de ambiente `HF_HOME` com o sufixo `accelerate`.
- Se não existir, o conteúdo da sua variável de ambiente `XDG_CACHE_HOME` com o sufixo `huggingface/accelerate`.
- Se isso também não existir, a pasta `~/.cache/huggingface/accelerate`.

Para ter múltiplas configurações, a flag `--config_file` pode ser passada ao comando `accelerate launch` em conjunto com a localização do yaml personalizado.

Um exemplo de yaml pode ser parecido com o seguinte para duas GPUs em uma única máquina usando `fp16` para precisão mista:
```yaml
compute_environment: LOCAL_MACHINE
deepspeed_config: {}
distributed_type: MULTI_GPU
fsdp_config: {}
machine_rank: 0
main_process_ip: null
main_process_port: null
main_training_function: main
mixed_precision: fp16
num_machines: 1
num_processes: 2
use_cpu: false
```

A execução de um script a partir da localização desse arquivo yaml personalizado é feita da seguinte forma:
```bash
accelerate launch --config_file {path/to/config/my_config_file.yaml} {script_name.py} {--arg1} {--arg2} ...
```

## Treinamento multi-nó
O treinamento multi-nó com Accelerate é semelhante ao [treinamento multi-nó com torchrun](https://pytorch.org/tutorials/intermediate/ddp_series_multinode.html). A maneira mais simples de iniciar uma execução de treinamento multi-nó é fazer o seguinte:

- Copie sua base de código e seus dados para todos os nós. (ou coloque-os em um sistema de arquivos compartilhado)
- Configure seus pacotes Python em todos os nós.
- Execute `accelerate config` primeiro no nó principal. Após especificar o número de nós, você será solicitado a especificar o rank de cada nó (isso será 0 para o nó principal/master), juntamente com o endereço IP e a porta para o processo principal. Isso é necessário para que os nós de trabalho se comuniquem com o processo principal. Em seguida, você pode copiar ou enviar esse arquivo de configuração para todos os seus nós, alterando o `machine_rank` para 1, 2, 3, etc., para evitar ter que executar o comando (ou simplesmente seguir as instruções diretamente para iniciar com `torchrun` também).

Depois de fazer isso, você pode iniciar sua execução de treinamento multi-nó executando `accelerate launch` (ou `torchrun`) em todos os nós.

    É necessário que o comando seja executado em todos os nós para que tudo seja iniciado, e não apenas a partir do nó principal. Você pode usar algo como SLURM ou um executor de processos diferente para encapsular esse requisito e chamar tudo a partir de um único comando.

 É recomendável usar o IP da intranet do seu nó principal em vez do IP público para obter melhor latência. Este é o endereço `192.168.x.x` ou `172.x.x.x` que você vê ao executar `hostname -I` no nó principal.

Para ter uma melhor ideia sobre treinamento multi-nó, confira nosso exemplo de [treinamento multi-nó com FSDP](https://huggingface.co/blog/ram-efficient-pytorch-fsdp).

