Accelerate documentation

Suiveurs d'expérimentations

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Suiveurs d'expérimentations

De nombreuses API de suivi d’expériences sont disponibles, mais il peut souvent être complexe de les faire toutes fonctionner dans un environnement multi-processus. Accelerate fournit une API de suivi générale qui permet d’enregistrer des éléments utiles pendant l’exécution de votre script via Accelerator.log()

Traceurs intégrés

Actuellement, Accelerate prend en charge huit traceurs nativement :

  • TensorBoard
  • WandB
  • Trackio
  • CometML
  • Objectif
  • MLFlow
  • ClearML
  • DVCLive

Pour utiliser l’un d’entre eux, passez le ou les types sélectionnés au paramètre log_with dans Accelerate :

from accelerate import Accelerator
from accelerate.utils import LoggerType

accelerator = Accelerator(log_with="all")  # For all available trackers in the environment
accelerator = Accelerator(log_with="wandb")
accelerator = Accelerator(log_with=["wandb", LoggerType.TENSORBOARD])

Au début de votre expérience, Accelerator.init_trackers() doit être utilisé pour configurer votre projet et, le cas échéant, ajouter les hyperparamètres de l'expérience à consigner :

hps = {"num_iterations": 5, "learning_rate": 1e-2}
accelerator.init_trackers("my_project", config=hps)

Lorsque vous êtes prêt à journaliser des données, utilisez Accelerator.log(). Un step peut également être transmis pour corréler les données à une étape particulière de la boucle d’entraînement.

accelerator.log({"train_loss": 1.12, "valid_loss": 0.8}, step=1)

Une fois l’entraînement terminé, assurez-vous d’exécuter Accelerator.end_training() afin que tous les traceurs puissent exécuter leurs fonctionnalités de fin, s’ils en disposent.

accelerator.end_training()

Un exemple complet est présenté ci-dessous :

from accelerate import Accelerator

accelerator = Accelerator(log_with="all")
config = {
    "num_iterations": 5,
    "learning_rate": 1e-2,
    "loss_function": str(my_loss_function),
}

accelerator.init_trackers("example_project", config=config)

my_model, my_optimizer, my_training_dataloader = accelerator.prepare(my_model, my_optimizer, my_training_dataloader)
device = accelerator.device
my_model.to(device)

for iteration in range(config["num_iterations"]):
    for step, batch in enumerate(my_training_dataloader):
        my_optimizer.zero_grad()
        inputs, targets = batch
        inputs = inputs.to(device)
        targets = targets.to(device)
        outputs = my_model(inputs)
        loss = my_loss_function(outputs, targets)
        accelerator.backward(loss)
        my_optimizer.step()
        accelerator.log({"training_loss": loss}, step=step)
accelerator.end_training()

Si un traceur nécessite un répertoire pour y enregistrer les données, comme TensorBoard, passez le chemin du répertoire à project_dir. Le paramètre project_dir est utile lorsqu'il existe d'autres configurations à combiner dans la classe de données ProjectConfiguration. Par exemple, vous pouvez enregistrer les données de TensorBoard dans project_dir et tout le reste peut être journalisé dans le paramètre logging_dir de [~utils.ProjectConfiguration:

accelerator = Accelerator(log_with="tensorboard", project_dir=".")

# use with ProjectConfiguration
config = ProjectConfiguration(project_dir=".", logging_dir="another/directory")
accelerator = Accelerator(log_with="tensorboard", project_config=config)

Mise en œuvre de traceurs personnalisés

Pour implémenter un nouveau traceur à utiliser dans Accelerator, il est possible d’en créer un en implémentant la classe GeneralTracker. Chaque traceur doit implémenter trois fonctions et posséder trois propriétés :

  • __init__:

    • Doit stocker un run_name et initialiser l'API de suivi de la bibliothèque intégrée.
    • Si un tracker stocke ses données localement (comme TensorBoard), un paramètre logging_dir peut être ajouté.
  • store_init_configuration:

    • Doit prendre un dictionnaire values et les stocker en tant que configuration d'expérience à usage unique
  • log:

    • Doit prendre un dictionnaire values et un step, et doit les consigner dans l'exécution
  • name (str):

    • Un nom de chaîne de caractères unique pour le tracker, tel que "wandb" pour le tracker wandb.
    • Cela sera utilisé pour interagir avec ce traceur en particulier
  • requires_logging_directory (bool):

    • Si un logging_dir est nécessaire pour ce traceur en particulier et s'il en utilise un.
  • tracker:

    • Cela devrait être implémenté comme une fonction @property
    • Doit retourner le mécanisme de suivi interne utilisé par la bibliothèque, tel que l'objet run pour wandb.

Chaque méthode doit également utiliser la classe state.PartialState si, par exemple, le logger ne doit être exécuté que sur le processus principal.

Un exemple succinct est présenté ci-dessous, avec une intégration à Weights and Biases, ne contenant que les informations pertinentes et n’effectuant la journalisation que sur le processus principal :

from accelerate.tracking import GeneralTracker, on_main_process
from typing import Optional

import wandb


class MyCustomTracker(GeneralTracker):
    name = "wandb"
    requires_logging_directory = False

    @on_main_process
    def __init__(self, run_name: str):
        self.run_name = run_name
        run = wandb.init(self.run_name)

    @property
    def tracker(self):
        return self.run.run

    @on_main_process
    def store_init_configuration(self, values: dict):
        wandb.config(values)

    @on_main_process
    def log(self, values: dict, step: Optional[int] = None):
        wandb.log(values, step=step)

Lorsque vous êtes prêt à créer votre objet Accelerator, passez une instance de votre traceur à Accelerator.log_with pour qu’il soit automatiquement utilisé avec l’API :

tracker = MyCustomTracker("some_run_name")
accelerator = Accelerator(log_with=tracker)

Ils peuvent également être combinés avec des traceurs existants, y compris avec "all" :

tracker = MyCustomTracker("some_run_name")
accelerator = Accelerator(log_with=[tracker, "all"])

Enregistrement d'un traceur personnalisé par nom

Au lieu de passer une instance, vous pouvez enregistrer une classe de tracker personnalisée afin qu’elle puisse être sélectionnée par son name, tout comme les trackers intégrés. C’est pratique lorsque les trackers à utiliser sont lus depuis un fichier de configuration ou la ligne de commande :

from accelerate import Accelerator
from accelerate.tracking import GeneralTracker, register_tracker_class


class MyCustomTracker(GeneralTracker):
    name = "my_tracker"
    requires_logging_directory = False
    # ... implement the rest of the `GeneralTracker` interface


register_tracker_class(MyCustomTracker)
accelerator = Accelerator(log_with="my_tracker")

Accéder au traceur interne

Si vous souhaitez effectuer directement certaines interactions personnalisées avec un tracker, vous pouvez y accéder rapidement à l’aide de la méthode Accelerator.get_tracker(). Il suffit de passer la chaîne de caractères correspondant à l’attribut .name d’un tracker, et celui-ci sera retourné sur le processus principal.

Cet exemple montre comment faire avec wandb :

wandb_tracker = accelerator.get_tracker("wandb")

À partir de là, vous pouvez interagir avec l’objet run de wandb comme d’habitude :

wandb_tracker.log_artifact(some_artifact_to_log)
Trackers built in Accelerate will automatically execute on the correct process, so if a tracker is only meant to be ran on the main process it will do so automatically.

Si vous souhaitez supprimer complètement l’encapsulation d’Accelerate, vous pouvez obtenir le même résultat avec :

wandb_tracker = accelerator.get_tracker("wandb", unwrap=True)
if accelerator.is_main_process:
    wandb_tracker.log_artifact(some_artifact_to_log)

Lorsqu'un wrapper ne peut pas fonctionner

Si une bibliothèque possède une API qui ne suit pas un strict .log avec un dictionnaire global, comme Neptune.AI, la journalisation peut être effectuée manuellement sous une déclaration if accelerator.is_main_process :

  from accelerate import Accelerator
+ import neptune

  accelerator = Accelerator()
+ run = neptune.init_run(...)

  my_model, my_optimizer, my_training_dataloader = accelerate.prepare(my_model, my_optimizer, my_training_dataloader)
  device = accelerator.device
  my_model.to(device)

  for iteration in config["num_iterations"]:
      for batch in my_training_dataloader:
          my_optimizer.zero_grad()
          inputs, targets = batch
          inputs = inputs.to(device)
          targets = targets.to(device)
          outputs = my_model(inputs)
          loss = my_loss_function(outputs, targets)
          total_loss += loss
          accelerator.backward(loss)
          my_optimizer.step()
+         if accelerator.is_main_process:
+             run["logs/training/batch/loss"].log(loss)
Update on GitHub