# Lancement des scripts Accelerate

Dans le tutoriel précédent, vous avez appris comment modifier votre script d'entraînement actuel pour utiliser Accelerate. La version finale de ce code est présentée ci-dessous :

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

Mais comment exécuter ce code afin qu’il utilise le matériel spécial mis à sa disposition ?

Premièrement, vous devez réécrire le code ci-dessus sous forme de fonction et le rendre exécutable en tant que script. Par exemple :

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

Ensuite, vous devez le lancer avec `accelerate launch`.

  Il est recommandé d'exécuter `accelerate config` avant d'utiliser `accelerate launch` afin de configurer votre environnement selon vos préférences. Sinon, Accelerate utilisera des valeurs par défaut très basiques en fonction de la configuration de votre système.

## Utiliser accelerate launch

Accelerate dispose d’une commande CLI spéciale pour vous aider à lancer votre code sur votre système via `accelerate launch`. Cette commande encapsule l’ensemble des commandes différentes nécessaires pour lancer votre script sur diverses plateformes, sans que vous ayez à vous souvenir de chacune d’entre elles.

  Si vous êtes habitué à lancer vous-même des scripts dans PyTorch, par exemple avec `torchrun`, vous pouvez continuer à le faire. Il n’est pas obligatoire d’utiliser `accelerate launch`.

Vous pouvez lancer votre script rapidement en utilisant :

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

Il suffit de placer `accelerate launch` au début de votre commande, puis de passer les arguments et paramètres supplémentaires à votre script comme d'habitude !

Puisque cela exécute les différentes méthodes de spawn de torch, toutes les variables d’environnement attendues peuvent également être modifiées ici. Par exemple, voici comment utiliser `accelerate launch` avec un seul 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 ...
```

Vous pouvez également utiliser `accelerate launch` sans avoir préalablement exécuté `accelerate config`, mais vous devrez peut-être transmettre manuellement les paramètres de configuration appropriés. Dans ce cas, Accelerate prendra certaines décisions concernant les hyperparamètres à votre place, par exemple, si des GPU sont disponibles, il les utilisera tous par défaut, sans précision mixte. Voici comment utiliser tous les GPU et entraîner avec la précision mixte désactivée :

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

Ou en spécifiant le nombre de GPU à utiliser :

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

Pour plus de précision, vous devez passer vous-même les paramètres nécessaires. Par exemple, voici comment lancer le même script sur deux GPU en utilisant la précision mixte tout en évitant tous les avertissements :

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

Pour obtenir la liste complète des paramètres que vous pouvez passer, exécutez :

```bash
accelerate launch -h
```

  Même si vous n'utilisez pas Accelerate dans votre code, vous pouvez tout de même utiliser le lanceur pour démarrer vos scripts !

Pour visualiser cette différence, le `accelerate launch` multi-GPU mentionné plus tôt ressemblerait à ceci avec `torchrun` :

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

Vous pouvez également lancer votre script en utilisant le CLI de lancement en tant que module Python, ce qui permet de passer d’autres comportements de lancement spécifiques à Python. Pour ce faire, utilisez `accelerate.commands.launch` au lieu de `accelerate launch` :

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

Si vous souhaitez exécuter le script avec d'autres drapeaux python, vous pouvez également les passer, de la même manière que `-m`, comme dans l'exemple ci-dessous qui active la sortie standard et l'erreur standard non tamponnées :

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

  Vous pouvez également exécuter votre code sur CPU ! C'est utile à des fins de débogage et de test sur des modèles et des jeux de données de démonstration.

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

## Pourquoi vous devriez toujours utiliser `accelerate config`

Pourquoi est-il utile au point que vous devriez **toujours** exécuter `accelerate config` ?

N’oubliez pas l’appel à `accelerate launch` ainsi qu’à `torchrun` effectué plus tôt ? Une fois la configuration terminée, pour exécuter ce script avec les éléments nécessaires, il vous suffit d’utiliser `accelerate launch` tel quel, sans rien d’autre à passer en argument :

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

## Configurations personnalisées

Comme brièvement mentionné plus tôt, `accelerate launch` doit être utilisé principalement en combinant des configurations définies à l’aide de la commande `accelerate config`. Ces configurations sont enregistrées dans un fichier `default_config.yaml` situé dans votre dossier de cache pour Accelerate. Ce dossier de cache se trouve à (par ordre de priorité décroissant) :

- Le contenu de votre variable d'environnement `HF_HOME` suivi de `accelerate`.
- S'il n'existe pas, le contenu de votre variable d'environnement `XDG_CACHE_HOME` suivi de `huggingface/accelerate`.
- S'il n'existe pas non plus, le dossier `~/.cache/huggingface/accelerate`.

Pour disposer de plusieurs configurations, le drapeau `--config_file` peut être transmis à la commande `accelerate launch` accompagné de l’emplacement du fichier yaml personnalisé.

Un exemple de fichier yaml peut ressembler à ce qui suit pour deux GPU sur une seule machine en utilisant `fp16` pour la précision mixte :
```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
```

Lancer un script à partir de l'emplacement de ce fichier yaml personnalisé ressemble à ce qui suit :
```bash
accelerate launch --config_file {path/to/config/my_config_file.yaml} {script_name.py} {--arg1} {--arg2} ...
```

## Entraînement multi-nœuds
L’entraînement multi-nœuds avec Accelerate est similaire à [l’entraînement multi-nœuds avec torchrun](https://pytorch.org/tutorials/intermediate/ddp_series_multinode.html). La manière la plus simple de lancer une session d’entraînement multi-nœuds est de procéder comme suit :

- Copiez votre base de code et vos données sur tous les nœuds. (ou placez-les sur un système de fichiers partagé)
- Configurez vos paquets Python sur tous les nœuds.
- Exécutez `accelerate config` d’abord sur le nœud principal unique. Après avoir spécifié le nombre de nœuds, on vous demandera de préciser le rang de chaque nœud (ce sera 0 pour le nœud principal/master), ainsi que l’adresse IP et le port du processus principal. Cela est nécessaire pour que les nœuds de travail communiquent avec le processus principal. Ensuite, vous pouvez copier ou envoyer ce fichier de configuration sur l’ensemble de vos nœuds, en modifiant `machine_rank` en 1, 2, 3, etc., afin d’éviter d’avoir à exécuter la commande (ou simplement suivre leurs instructions directement pour le lancement avec `torchrun` également).

Une fois cela fait, vous pouvez démarrer votre exécution d’entraînement multi-nœuds en lançant `accelerate launch` (ou `torchrun`) sur tous les nœuds.

    Il est impératif d’exécuter la commande sur tous les nœuds pour que tout démarre, et non uniquement depuis le nœud principal. Vous pouvez utiliser un outil tel que SLURM ou un autre exécuteur de processus pour encapsuler cette exigence et lancer l’ensemble depuis une seule commande.

 Il est recommandé d'utiliser l'IP intranet de votre nœud principal plutôt que l'IP publique pour une meilleure latence. Il s'agit de l'adresse `192.168.x.x` ou `172.x.x.x` que vous voyez lorsque vous exécutez `hostname -I` sur le nœud principal.

Pour mieux comprendre l'entraînement multi-nœuds, consultez notre exemple d'[entraînement multi-nœuds avec FSDP](https://huggingface.co/blog/ram-efficient-pytorch-fsdp).

