> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PyTorch Lightning
> Utilisez Weights & Biases avec le WandbLogger de PyTorch Lightning pour le suivi des expériences et la sauvegarde des points de contrôle du modèle.
export const ColabLink = ({url}) =>
Try in Colab
;
PyTorch Lightning fournit un wrapper léger qui permet d’organiser votre code PyTorch et d’ajouter des fonctionnalités avancées comme l’entraînement distribué et la précision 16 bits. Weights & Biases fournit un wrapper léger pour journaliser vos expériences de ML. Inutile de combiner les deux vous-même : la bibliothèque PyTorch Lightning intègre directement Weights & Biases via le [`WandbLogger`](https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html#module-lightning.pytorch.loggers.wandb).
Cette page explique comment utiliser `WandbLogger` pour suivre des métriques, journaliser des hyperparamètres, enregistrer des points de contrôle de modèle sous forme d’artifacts, journaliser des médias et lancer un entraînement multi-GPU avec PyTorch Lightning et Weights & Biases.
Intégrer avec Lightning
Les sections suivantes expliquent comment vous authentifier auprès de Weights & Biases, installer la bibliothèque `wandb` et joindre un `WandbLogger` à votre `Trainer` Lightning ou à votre instance `Fabric`.
```python theme={"system"}
from lightning.pytorch.loggers import WandbLogger
from lightning.pytorch import Trainer
wandb_logger = WandbLogger(log_model="all")
trainer = Trainer(logger=wandb_logger)
```
**Utilisation de `wandb.log()` :** le `WandbLogger` journalise dans Weights & Biases à partir du `global_step` du Trainer. Si vous appelez également `wandb.log()` directement dans votre code, n’utilisez pas l’argument `step` de `wandb.log()`.
Journalisez plutôt le `global_step` du Trainer comme n’importe quelle autre métrique :
```python theme={"system"}
wandb.log({"accuracy":0.99, "trainer/global_step": step})
```
```python theme={"system"}
import lightning as L
from wandb.integration.lightning.fabric import WandbLogger
wandb_logger = WandbLogger(log_model="all")
fabric = L.Fabric(loggers=[wandb_logger])
fabric.launch()
fabric.log_dict({"important_metric": important_metric})
```
S’inscrire et créer une clé API
Une clé API authentifie votre machine auprès de Weights & Biases. Vous pouvez générer une clé API depuis votre profil utilisateur.
Pour plus de simplicité, accédez aux [Paramètres utilisateur](https://forge.coreweave.com/settings) et créez une clé API. Copiez immédiatement la clé API et enregistrez-la dans un emplacement sécurisé, par exemple un gestionnaire de mots de passe.
Pour générer une clé API depuis votre profil utilisateur :
1. Cliquez sur l’icône de votre profil utilisateur dans le coin supérieur droit.
2. Sélectionnez **Paramètres utilisateur**, puis faites défiler la page jusqu’à la section **API Keys**.
Installer la bibliothèque `wandb` et se connecter
Pour installer la bibliothèque `wandb` en local et vous connecter :
1. Définissez la [variable d’environnement](/fr/products/wandb/track/environment-variables) `WANDB_API_KEY` sur votre clé API. Remplacez les valeurs entre `<>` par les vôtres :
```bash theme={"system"}
export WANDB_API_KEY=
```
2. Installez la bibliothèque `wandb` et connectez-vous.
```shell theme={"system"}
pip install wandb
wandb login
```
```bash theme={"system"}
pip install wandb
```
```python theme={"system"}
import wandb
wandb.login()
```
```notebook theme={"system"}
!pip install wandb
import wandb
wandb.login()
```
Utiliser le `WandbLogger` de PyTorch Lightning
PyTorch Lightning propose plusieurs classes `WandbLogger` pour consigner les métriques, les poids du modèle et les médias. Choisissez la classe qui correspond à votre configuration d’entraînement :
* [`PyTorch`](https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html#module-lightning.pytorch.loggers.wandb)
* [`Fabric`](https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html#module-lightning.pytorch.loggers.wandb)
Pour l’intégration avec Lightning, instanciez le `WandbLogger` et transmettez-le au `Trainer` ou à `Fabric` de Lightning.
```python theme={"system"}
trainer = Trainer(logger=wandb_logger)
```
```python theme={"system"}
fabric = L.Fabric(loggers=[wandb_logger])
fabric.launch()
fabric.log_dict({
"important_metric": important_metric
})
```
Arguments courants du logger
Le tableau suivant répertorie les paramètres courants de `WandbLogger`. Pour plus de détails sur l’ensemble des arguments du logger, consultez la documentation de PyTorch Lightning.
* [`PyTorch`](https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html#module-lightning.pytorch.loggers.wandb)
* [`Fabric`](https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.loggers.wandb.html#module-lightning.pytorch.loggers.wandb)
| Paramètre | Description |
| - | - |
| `project` | Définit le projet Weights & Biases dans lequel journaliser les données |
| `name` | Nomme votre run W\&B |
| `log_model` | Journalise tous les modèles si `log_model="all"`, ou à la fin de l’entraînement si `log_model=True` |
| `save_dir` | Chemin d’enregistrement des données |
Journaliser vos hyperparamètres
Journaliser vos hyperparamètres avec Weights & Biases vous permet de comparer des runs et de reproduire des résultats. Utilisez la méthode adaptée à votre logger :
```python theme={"system"}
class LitModule(LightningModule):
def __init__(self, *args, **kwarg):
self.save_hyperparameters()
```
```python theme={"system"}
wandb_logger.log_hyperparams(
{
"hyperparameter_1": hyperparameter_1,
"hyperparameter_2": hyperparameter_2,
}
)
```
Journaliser des paramètres de configuration supplémentaires
Pour capturer des valeurs de configuration additionnelles parallèlement à vos hyperparamètres, mettez directement à jour la configuration de run :
```python theme={"system"}
# ajouter un paramètre
wandb_logger.experiment.config["key"] = value
# ajouter plusieurs paramètres
wandb_logger.experiment.config.update({key1: val1, key2: val2})
# utiliser directement le module wandb
wandb.config["key"] = value
wandb.config.update()
```
Journaliser les gradients, l’histogramme des paramètres et la topologie du modèle
Transmettez l’objet de votre modèle à `wandb_logger.watch()` pour surveiller ses gradients et ses paramètres pendant l’entraînement. Voir la documentation de `WandbLogger` de PyTorch Lightning.
Consigner des métriques
Pour consigner vos métriques dans Weights & Biases avec le `WandbLogger`, appelez `self.log('my_metric_name', metric_value)` dans votre `LightningModule`, par exemple dans vos méthodes `training_step` ou `validation_step`.
L’extrait de code suivant montre comment définir votre `LightningModule` pour consigner vos métriques ainsi que ses hyperparamètres. Cet exemple utilise la bibliothèque [`torchmetrics`](https://github.com/Lightning-AI/torchmetrics) pour calculer vos métriques.
```python theme={"system"}
import torch
from torch.nn import Linear, CrossEntropyLoss, functional as F
from torch.optim import Adam
from torchmetrics.functional import accuracy
from lightning.pytorch import LightningModule
class My_LitModule(LightningModule):
def __init__(self, n_classes=10, n_layer_1=128, n_layer_2=256, lr=1e-3):
"""méthode utilisée pour définir les paramètres du modèle"""
super().__init__()
# les images mnist sont de forme (1, 28, 28) (canaux, largeur, hauteur)
self.layer_1 = Linear(28 * 28, n_layer_1)
self.layer_2 = Linear(n_layer_1, n_layer_2)
self.layer_3 = Linear(n_layer_2, n_classes)
self.loss = CrossEntropyLoss()
self.lr = lr
# enregistrer les hyperparamètres dans self.hparams (journalisés automatiquement par W&B)
self.save_hyperparameters()
def forward(self, x):
"""méthode utilisée pour l’inférence entrée -> sortie"""
# (b, 1, 28, 28) -> (b, 1*28*28)
batch_size, channels, width, height = x.size()
x = x.view(batch_size, -1)
# appliquer 3 x (linéaire + relu)
x = F.relu(self.layer_1(x))
x = F.relu(self.layer_2(x))
x = self.layer_3(x)
return x
def training_step(self, batch, batch_idx):
"""doit renvoyer une perte à partir d’un seul lot"""
_, loss, acc = self._get_preds_loss_accuracy(batch)
# Journaliser la perte et la métrique
self.log("train_loss", loss)
self.log("train_accuracy", acc)
return loss
def validation_step(self, batch, batch_idx):
"""utilisée pour consigner des métriques"""
preds, loss, acc = self._get_preds_loss_accuracy(batch)
# Journaliser la perte et la métrique
self.log("val_loss", loss)
self.log("val_accuracy", acc)
return preds
def configure_optimizers(self):
"""définit l’optimiseur du modèle"""
return Adam(self.parameters(), lr=self.lr)
def _get_preds_loss_accuracy(self, batch):
"""fonction utilitaire, car les étapes train/valid/test sont similaires"""
x, y = batch
logits = self(x)
preds = torch.argmax(logits, dim=1)
loss = self.loss(logits, y)
acc = accuracy(preds, y)
return preds, loss, acc
```
```python theme={"system"}
import lightning as L
import torch
import torchvision as tv
from wandb.integration.lightning.fabric import WandbLogger
import wandb
fabric = L.Fabric(loggers=[wandb_logger])
fabric.launch()
model = tv.models.resnet18()
optimizer = torch.optim.SGD(model.parameters(), lr=lr)
model, optimizer = fabric.setup(model, optimizer)
train_dataloader = fabric.setup_dataloaders(
torch.utils.data.DataLoader(train_dataset, batch_size=batch_size)
)
model.train()
for epoch in range(num_epochs):
for batch in train_dataloader:
optimizer.zero_grad()
loss = model(batch)
loss.backward()
optimizer.step()
fabric.log_dict({"loss": loss})
```
Journaliser le min/max d'une métrique
La fonction [`define_metric`](/fr/products/wandb/ref/python/experiments/run#define_metric) de Weights & Biases vous permet de choisir si votre métrique de synthèse Weights & Biases affiche la valeur minimale, maximale, moyenne ou la meilleure valeur de cette métrique. Si vous n'utilisez pas `define_metric`, c'est la dernière valeur journalisée qui apparaît dans vos métriques de synthèse. Pour plus d'informations, voir le [guide de personnalisation des axes de journalisation](/fr/products/wandb/track/log/customize-logging-axes).
Pour suivre la précision de validation maximale dans la métrique de synthèse Weights & Biases, appelez `wandb.define_metric()` une seule fois, au début de l'entraînement :
```python theme={"system"}
class My_LitModule(LightningModule):
...
def validation_step(self, batch, batch_idx):
if trainer.global_step == 0:
wandb.define_metric("val_accuracy", summary="max")
preds, loss, acc = self._get_preds_loss_accuracy(batch)
# Journaliser la perte et la métrique
self.log("val_loss", loss)
self.log("val_accuracy", acc)
return preds
```
```python theme={"system"}
wandb.define_metric("val_accuracy", summary="max")
fabric = L.Fabric(loggers=[wandb_logger])
fabric.launch()
fabric.log_dict({"val_accuracy": val_accuracy})
```
Créer des points de contrôle d’un modèle
En enregistrant les points de contrôle sous forme d’artifacts W\&B, vous obtenez des fichiers de modèle versionnés que vous pouvez récupérer ultérieurement par run, par alias ou par version.
Pour enregistrer les points de contrôle du modèle en tant qu’[artifacts](/fr/products/wandb/artifacts) W\&B,
utilisez le callback Lightning [`ModelCheckpoint`](https://lightning.ai/docs/pytorch/stable/api/lightning.pytorch.callbacks.ModelCheckpoint.html) et définissez l’argument `log_model` dans le `WandbLogger`.
```python theme={"system"}
trainer = Trainer(logger=wandb_logger, callbacks=[checkpoint_callback])
```
```python theme={"system"}
fabric = L.Fabric(loggers=[wandb_logger], callbacks=[checkpoint_callback])
```
Les alias `latest` et `best` sont définis automatiquement pour faciliter la récupération d’un point de contrôle de modèle à partir d’un artifact W\&B :
```python theme={"system"}
# la référence est disponible dans le panneau des artifacts
# peut être une version (par exemple, « v2 ») ou un alias (« latest » ou « best »)
checkpoint_reference = "//:"
```
```python theme={"system"}
# télécharger le point de contrôle localement (s'il n'est pas déjà en cache)
wandb_logger.download_artifact(checkpoint_reference, artifact_type="model")
```
```python theme={"system"}
# télécharger le point de contrôle localement (s'il n'est pas déjà en cache)
run = wandb.init(project="MNIST")
artifact = run.use_artifact(checkpoint_reference, type="model")
artifact_dir = artifact.download()
```
```python theme={"system"}
# charger le point de contrôle
model = LitModule.load_from_checkpoint(Path(artifact_dir) / "model.ckpt")
```
```python theme={"system"}
# Récupérer le point de contrôle brut
full_checkpoint = fabric.load(Path(artifact_dir) / "model.ckpt")
model.load_state_dict(full_checkpoint["model"])
optimizer.load_state_dict(full_checkpoint["optimizer"])
```
Les points de contrôle de modèle que vous journalisez sont consultables dans l’interface utilisateur de [W\&B Artifacts](/fr/products/wandb/artifacts) et incluent la traçabilité complète du modèle (voir un [exemple de point de contrôle de modèle dans l’interface utilisateur](https://forge.coreweave.com/wandb/wandb/arttest/artifacts/model/iv3_trained/5334ab69740f9dda4fed/lineage?_gl=1*yyql5q*_ga*MTQxOTYyNzExOS4xNjg0NDYyNzk1*_ga_JH1SJHJQXJ*MTY5MjMwNzI2Mi4yNjkuMS4xNjkyMzA5NjM2LjM3LjAuMA..)).
Pour mettre en favoris vos meilleurs points de contrôle de modèle et les centraliser à l’échelle de votre équipe, liez-les au [registre](/fr/products/registry).
Dans le registre, vous pouvez organiser vos meilleurs modèles par tâche, gérer leur cycle de vie, assurer leur suivi et leur audit tout au long du cycle de vie ML, et [automatiser](/fr/products/wandb/automations) des actions en aval à l’aide de webhooks ou de jobs.
Journaliser des images, du texte et plus encore
Le `WandbLogger` dispose des méthodes `log_image`, `log_text` et `log_table` pour journaliser des médias.
Vous pouvez également appeler directement `wandb.log()` ou `trainer.logger.experiment.log()` pour journaliser d’autres types de médias, comme l’audio, les molécules, les nuages de points et les objets 3D.
```python theme={"system"}
# avec des tenseurs, des tableaux numpy ou des images PIL
wandb_logger.log_image(key="samples", images=[img1, img2])
# ajout de légendes
wandb_logger.log_image(key="samples", images=[img1, img2], caption=["tree", "person"])
# avec des chemins de fichiers
wandb_logger.log_image(key="samples", images=["img_1.jpg", "img_2.jpg"])
# avec .log dans le trainer
trainer.logger.experiment.log(
{"samples": [wandb.Image(img, caption=caption) for (img, caption) in my_images]},
step=current_trainer_global_step,
)
```
```python theme={"system"}
# les données doivent être une liste de listes
columns = ["input", "label", "prediction"]
my_data = [["cheese", "english", "english"], ["fromage", "french", "spanish"]]
# avec des colonnes et des données
wandb_logger.log_text(key="my_samples", columns=columns, data=my_data)
# avec un DataFrame pandas
wandb_logger.log_text(key="my_samples", dataframe=my_dataframe)
```
```python theme={"system"}
# journaliser une W&B Table contenant une légende textuelle, une image et de l’audio
columns = ["caption", "image", "sound"]
# les données doivent être une liste de listes
my_data = [
["cheese", wandb.Image(img_1), wandb.Audio(snd_1)],
["wine", wandb.Image(img_2), wandb.Audio(snd_2)],
]
# journaliser la Table
wandb_logger.log_table(key="my_samples", columns=columns, data=my_data)
```
Utilisez le système de Callbacks de Lightning pour déterminer à quel moment journaliser dans Weights & Biases via le `WandbLogger`. L’exemple suivant journalise un échantillon d’images de validation et de prédictions :
```python theme={"system"}
import torch
import wandb
import lightning.pytorch as pl
from lightning.pytorch.loggers import WandbLogger
# ou
# from wandb.integration.lightning.fabric import WandbLogger
class LogPredictionSamplesCallback(Callback):
def on_validation_batch_end(
self, trainer, pl_module, outputs, batch, batch_idx, dataloader_idx
):
"""Called when the validation batch ends."""
# `outputs` provient de `LightningModule.validation_step`
# et correspond ici aux prédictions de notre modèle
# Journaliser 20 exemples de prédictions d’images issus du premier lot
if batch_idx == 0:
n = 20
x, y = batch
images = [img for img in x[:n]]
captions = [
f"Ground Truth: {y_i} - Prediction: {y_pred}"
for y_i, y_pred in zip(y[:n], outputs[:n])
]
# Option 1 : journaliser les images avec `WandbLogger.log_image`
wandb_logger.log_image(key="sample_images", images=images, caption=captions)
# Option 2 : journaliser les images et les prédictions dans une W&B Table
columns = ["image", "ground truth", "prediction"]
data = [
[wandb.Image(x_i), y_i, y_pred] or x_i,
y_i,
y_pred in list(zip(x[:n], y[:n], outputs[:n])),
]
wandb_logger.log_table(key="sample_table", columns=columns, data=data)
trainer = pl.Trainer(callbacks=[LogPredictionSamplesCallback()])
```
Utiliser plusieurs GPU avec Lightning et Weights & Biases
Lors d’un entraînement distribué, la manière dont vous référencez `wandb.run` d’un rank à l’autre peut déterminer si l’entraînement se poursuit ou aboutit à un interblocage. Cette section présente les exigences à respecter et propose un modèle recommandé.
PyTorch Lightning prend en charge le multi-GPU via son interface DDP. Toutefois, la conception de PyTorch Lightning vous oblige à être attentif à la manière dont vous instanciez vos GPU.
Lightning exige que chaque GPU (ou rank) de votre boucle d’entraînement soit instancié exactement de la même manière, avec les mêmes conditions initiales. Or, seul le processus de rank 0 a accès à l’objet `wandb.run`. Pour les processus de rank non nul, `wandb.run = None`, ce qui peut provoquer leur échec. Vous risquez alors un interblocage : le processus de rank 0 attend que les processus de rank non nul le rejoignent, alors que ceux-ci ont déjà planté.
C’est pourquoi vous devez être attentif à la manière dont vous configurez votre code d’entraînement. L’approche recommandée consiste à rendre votre code indépendant de l’objet `wandb.run`.
```python theme={"system"}
class MNISTClassifier(pl.LightningModule):
def __init__(self):
super(MNISTClassifier, self).__init__()
self.model = nn.Sequential(
nn.Flatten(),
nn.Linear(28 * 28, 128),
nn.ReLU(),
nn.Linear(128, 10),
)
self.loss = nn.CrossEntropyLoss()
def forward(self, x):
return self.model(x)
def training_step(self, batch, batch_idx):
x, y = batch
y_hat = self.forward(x)
loss = self.loss(y_hat, y)
self.log("train/loss", loss)
return {"train_loss": loss}
def validation_step(self, batch, batch_idx):
x, y = batch
y_hat = self.forward(x)
loss = self.loss(y_hat, y)
self.log("val/loss", loss)
return {"val_loss": loss}
def configure_optimizers(self):
return torch.optim.Adam(self.parameters(), lr=0.001)
def main():
# Initialiser toutes les graines aléatoires avec la même valeur.
# C’est important dans un contexte d’entraînement distribué.
# Chaque rank reçoit son propre ensemble de poids initiaux.
# S’ils ne correspondent pas, les gradients ne correspondront pas non plus,
# et l’entraînement risque de ne pas converger.
pl.seed_everything(1)
train_loader = DataLoader(train_dataset, batch_size=64, shuffle=True, num_workers=4)
val_loader = DataLoader(val_dataset, batch_size=64, shuffle=False, num_workers=4)
model = MNISTClassifier()
wandb_logger = WandbLogger(project="")
callbacks = [
ModelCheckpoint(
dirpath="checkpoints",
every_n_train_steps=100,
),
]
trainer = pl.Trainer(
max_epochs=3, gpus=2, logger=wandb_logger, strategy="ddp", callbacks=callbacks
)
trainer.fit(model, train_loader, val_loader)
```
Exemples
Pour un guide pas à pas complet, suivez ce [tutoriel vidéo accompagné d’un notebook Colab](https://wandb.me/lit-colab).
Questions fréquentes
Comment Weights & Biases s’intègre-t-il à Lightning ?
L’intégration principale est basée sur l’[API `loggers` de Lightning](https://lightning.ai/docs/pytorch/stable/extensions/logging.html), qui vous permet d’écrire une grande partie de votre code de journalisation indépendamment du framework utilisé. Les instances de `Logger` sont transmises au [`Trainer` de Lightning](https://lightning.ai/docs/pytorch/stable/common/trainer.html) et sont déclenchées par le riche [système de hooks et de callbacks](https://lightning.ai/docs/pytorch/stable/extensions/callbacks.html) de cette API. Votre code de recherche reste ainsi bien séparé du code d’ingénierie et de journalisation.
Que journalise l’intégration sans code supplémentaire ?
Weights & Biases enregistre les points de contrôle de votre modèle, que vous pouvez consulter ou télécharger pour les réutiliser dans de futurs runs. Weights & Biases capture également des [métriques système](/fr/products/wandb/ref/python/experiments/system-metrics), comme l’utilisation du GPU et les E/S réseau, ainsi que des informations sur l’environnement, comme le matériel et le système d’exploitation. Il capture l’[état du code](/fr/products/wandb/app/features/panels/code), notamment le commit Git et le patch de diff, le contenu du notebook et l’historique de session. Enfin, il capture tout ce qui est affiché sur la sortie standard.
Que faire si je dois utiliser `wandb.run` dans ma configuration d’entraînement ?
Vous devez étendre vous-même la portée de la variable à laquelle vous souhaitez accéder. Autrement dit, assurez-vous que les conditions initiales sont identiques dans tous les processus.
```python theme={"system"}
if os.environ.get("LOCAL_RANK", None) is None:
os.environ["WANDB_DIR"] = wandb.run.dir
```
Si c’est le cas, vous pouvez utiliser `os.environ["WANDB_DIR"]` pour configurer le répertoire des points de contrôle du modèle. Ainsi, tout processus dont le rank est non nul peut accéder à `wandb.run.dir`.
