> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ajouter W&B à une bibliothèque Python

> Bonnes pratiques pour intégrer Weights & Biases dans votre bibliothèque Python afin d’assurer le suivi des expériences, la surveillance du système et la gestion des modèles.

Ce guide explique comment intégrer Weights & Biases (W\&B) à une bibliothèque Python.

Suivez ces recommandations si vous intégrez W\&B à une base de code complexe, comme un framework d'entraînement, un SDK ou une bibliothèque réutilisable.

<Tip>
  Si vous débutez avec W\&B, consultez les guides essentiels (par exemple, [Suivi des expériences](/fr/models/track/)) avant de continuer.
</Tip>

Vous trouverez ci-dessous des conseils et bonnes pratiques pour les cas où la base de code sur laquelle vous travaillez est plus complexe qu'un simple script d'entraînement Python ou qu'un notebook Jupyter.

<div id="decide-how-users-install-wb">
  ## Déterminez comment les utilisateurs installent W\&B
</div>

Avant de commencer, déterminez si W\&B doit être une dépendance obligatoire ou une fonctionnalité facultative de votre bibliothèque.

<div id="require-wb-as-a-dependency">
  ### Exiger W\&B comme dépendance
</div>

Si W\&B est au cœur des fonctionnalités de votre bibliothèque, ajoutez le SDK Python de W\&B (`wandb`) à vos dépendances :

```txt theme={null}
torch==1.8.0 
...
wandb==0.13.*
```

<div id="make-wb-optional-on-installation">
  ### Rendre W\&B facultatif à l’installation
</div>

Si W\&B est une fonctionnalité facultative, permettez à votre bibliothèque de fonctionner sans que W\&B soit installé.

Vous pouvez soit importer `wandb` conditionnellement en Python, soit le déclarer comme dépendance facultative dans `pyproject.toml`.

<Tabs>
  <Tab title="Python">
    Détectez si `wandb` est disponible et renvoyez une erreur claire si un utilisateur active des fonctionnalités W\&B sans l’avoir installé :

    ```python theme={null}
    try:
        import wandb
        _WANDB_AVAILABLE = True
    except ImportError:
        _WANDB_AVAILABLE = False
    ```
  </Tab>

  <Tab title="pyproject.toml">
    Déclarez `wandb` comme dépendance facultative dans votre fichier `pyproject.toml` :

    ```toml theme={null}
    [project]
    name = "my_awesome_lib"
    version = "0.1.0"
    dependencies = [
        "torch",
        "sklearn"
    ]

    [project.optional-dependencies]
    dev = [
        "wandb"
    ]
    ```
  </Tab>
</Tabs>

<div id="authenticate-users">
  ## Authentifiez les utilisateurs
</div>

W\&B utilise des clés API pour authentifier les utilisateurs et les machines.

<div id="create-an-api-key">
  ### Créer une clé API
</div>

Une clé API permet d’authentifier un client ou une machine auprès de W\&B. Vous pouvez générer une clé API depuis votre profil utilisateur.

<Note>
  Pour une méthode plus directe, accédez aux [Paramètres utilisateur](https://wandb.ai/settings) et créez une clé API. Copiez immédiatement la clé API et conservez-la dans un endroit sûr, par exemple dans un gestionnaire de mots de passe.
</Note>

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

<div id="install-and-log-in-to-wb">
  ### Installez W\&B et connectez-vous
</div>

Pour installer la bibliothèque `wandb` localement et vous connecter :

<Tabs>
  <Tab title="Ligne de commande">
    1. Définissez la [variable d'environnement](/fr/models/track/environment-variables/) `WANDB_API_KEY` avec votre clé API :

       ```bash theme={null}
       export WANDB_API_KEY=<your_api_key>
       ```

    2. Installez la bibliothèque `wandb`, puis connectez-vous :

       ```bash theme={null}
       pip install wandb

       wandb login
       ```
  </Tab>

  <Tab title="Python">
    1. Ouvrez votre terminal et installez le SDK Python.
       ```bash theme={null}
       pip install wandb
       ```

    2. Connectez-vous à W\&B depuis votre script ou notebook Python. Vous serez invité à saisir
       votre clé API.
       ```python theme={null}
       import wandb
       wandb.login()
       ```
  </Tab>

  <Tab title="Python notebook">
    Copiez-collez l'extrait de code suivant dans une cellule de votre notebook Jupyter, puis exécutez-le. Vous serez invité à saisir votre clé API.

    ```notebook theme={null}
    !pip install wandb

    import wandb
    wandb.login()
    ```
  </Tab>
</Tabs>

<div id="start-a-run">
  ## Lancer un run
</div>

Un *run* représente une seule unité de calcul, comme une expérience d’entraînement. La plupart des bibliothèques créent un run par tâche d'entraînement. Pour en savoir plus sur les runs, voir [W\&B Runs](/fr/models/runs/).

Initialisez un run avec [`wandb.init()`](/fr/models/ref/python/functions/init) et indiquez le nom de votre projet et de votre entité d’équipe (nom de l’équipe). Si vous ne spécifiez pas de projet, W\&B stocke votre run dans un projet par défaut appelé "uncategorized".:

```python theme={null}
with wandb.init(project="<project_name>", entity="<entity>") as run:
    ...
```

W\&B recommande d’utiliser un gestionnaire de contexte pour s’assurer que votre run est correctement fermé, même en cas d’erreur. Si vous n’utilisez pas de gestionnaire de contexte, vous devez appeler `run.finish()` pour fermer le run et journaliser toutes les données dans W\&B.

<Tip>
  **Quand appeler `wandb.init()`**

  Appelez `wandb.init()` le plus tôt possible. W\&B capture stdout, stderr et les messages d’erreur, ce qui facilite le débogage.

  Placez l’ensemble de votre boucle d’entraînement dans un gestionnaire de contexte `wandb.init()` afin de vous assurer que toutes les informations pertinentes sont bien capturées dans le run. Cela inclut les messages d’erreur, qui peuvent être essentiels pour le débogage.
</Tip>

<div id="set-wandb-as-an-optional-dependency">
  ### Définir `wandb` comme dépendance facultative
</div>

Si vous souhaitez rendre `wandb` facultatif pour les utilisateurs de votre bibliothèque, vous pouvez soit :

* Définir une option `wandb`, par exemple :

<Tabs>
  <Tab title="Python">`python trainer = my_trainer(..., use_wandb=True) `</Tab>
  <Tab title="Bash">`bash python train.py ... --use-wandb `</Tab>
</Tabs>

* Ou définir `wandb` sur `disabled` dans `wandb.init()` :

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    wandb.init(mode="disabled")
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    export WANDB_MODE=disabled
    ```

    ou

    ```bash theme={null}
    wandb disabled
    ```
  </Tab>
</Tabs>

* Ou définir `wandb` en mode hors ligne - notez que `wandb` s'exécutera quand même, mais n'essaiera simplement pas de communiquer avec W\&B via Internet :

<Tabs>
  <Tab title="Variable d'environnement">
    ```bash theme={null}
    export WANDB_MODE=offline
    ```

    ou

    ```python theme={null}
    os.environ['WANDB_MODE'] = 'offline'
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    wandb offline
    ```
  </Tab>
</Tabs>

<div id="define-a-run-config">
  ## Définir une configuration de run
</div>

Fournissez un dictionnaire de configuration lorsque vous initialisez votre run afin d’enregistrer les hyperparamètres et d’autres métadonnées dans W\&B.

Utilisez l’application W\&B pour comparer les runs en fonction de leurs paramètres de configuration et les filtrer dans le tableau Runs. Vous pouvez également utiliser ces paramètres pour regrouper des runs dans l’application W\&B.

Par exemple, dans l’image suivante, la taille de lot (bathch\_size) a été définie comme paramètre de configuration et est visible (voir la première colonne) dans le tableau Runs. Cela permet aux utilisateurs de filtrer et de comparer les runs en fonction de leur taille de lot :

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_runs_page.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=a059dd2d4101adf87649438ea957b35c" alt="tableau Runs de W&B" width="1820" height="768" data-path="images/integrations/integrations_add_any_lib_runs_page.png" />
</Frame>

Les valeurs typiques des paramètres de configuration incluent :

* Le nom du modèle, sa version, les paramètres d’architecture et les hyperparamètres.
* Le nom du jeu de données, sa version, le nombre d’exemples d’entraînement ou de validation.
* Les paramètres d’entraînement tels que le taux d’apprentissage, la taille de lot et l’optimiseur.

L’extrait de code suivant montre comment enregistrer une configuration :

```python theme={null}
config = {"batch_size": 32, ...}
with wandb.init(..., config=config) as run:
    ...
```

<div id="update-the-run-config">
  ### Mettre à jour la configuration de run
</div>

Si certaines valeurs ne sont pas disponibles au moment de l’initialisation, mettez à jour la configuration plus tard avec `wandb.Run.config.update`. Par exemple, il se peut que vous souhaitiez ajouter les paramètres d’un modèle après son instanciation :

```python theme={null}
with wandb.init(...) as run:
    model = MyModel(...)
    run.config.update({"model_parameters": 3500})
```

Pour plus de détails, voir [Configurer Experiments](/fr/models/track/config/).

<div id="log-metrics-and-data">
  ## Journaliser les métriques et les données
</div>

<div id="log-metrics">
  ### Journaliser des métriques
</div>

Créez un dictionnaire dans lequel la clé correspond au nom de la métrique. Passez ce dictionnaire à [`wandb.Run.log()`](/fr/models/ref/python/experiments/run#method-run-log) pour le journaliser dans W\&B :

```python theme={null}
NUM_EPOCHS = 10

for epoch in range(NUM_EPOCHS):
    for input, ground_truth in data: 
        prediction = model(input) 
        loss = loss_fn(prediction, ground_truth) 
        metrics = { "loss": loss } 
        run.log(metrics)
```

Utilisez des préfixes de noms de métriques pour regrouper les métriques associées dans l’application W\&B. Les préfixes courants incluent `train/` et `val/` pour les métriques d'entraînement et de validation, respectivement, mais vous pouvez utiliser n'importe quel préfixe adapté à votre cas d'usage.

Cela créera des sections distinctes dans l’espace de travail de votre projet pour vos métriques d'entraînement et de validation, ou pour d'autres types de métriques que vous souhaitez séparer :

```python theme={null}
with wandb.init(...) as run:
    metrics = {
        "train/loss": 0.4,
        "train/learning_rate": 0.4,
        "val/loss": 0.5, 
        "val/accuracy": 0.7
    }
    run.log(metrics)
```

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_log.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=da8be42cd29aef0849aa301423982676" alt="W&B Workspace" width="1236" height="738" data-path="images/integrations/integrations_add_any_lib_log.png" />
</Frame>

Voir [`wandb.Run.log()`](/fr/models/ref/python/experiments/run#method-run-log) pour en savoir plus.

<div id="control-the-x-axis">
  ### Contrôler l’axe x
</div>

Si vous effectuez plusieurs appels à `wandb.Run.log()` pour la même étape d’entraînement, le SDK wandb incrémente un compteur interne à chaque appel à `wandb.Run.log()`. Ce compteur peut ne pas correspondre à l’étape d’entraînement de votre boucle d’entraînement.

Pour éviter cette situation, définissez explicitement l’étape de l’axe x avec `wandb.Run.define_metric()`, une seule fois, immédiatement après avoir appelé `wandb.init()` :

```python theme={null}
with wandb.init(...) as run:
    run.define_metric("*", step_metric="global_step")
```

Le motif glob `*` signifie que chaque métrique utilisera `global_step` sur l’axe des x de vos graphiques. Si vous souhaitez que seules certaines métriques soient journalisées en fonction de `global_step`, vous pouvez les spécifier à la place :

```python theme={null}
run.define_metric("train/loss", step_metric="global_step")
```

À présent, journalisez vos métriques, votre métrique `step` et votre `global_step` chaque fois que vous appelez `wandb.Run.log()` :

```python theme={null}
for step, (input, ground_truth) in enumerate(data):
    ...
    run.log({"global_step": step, "train/loss": 0.1})
    run.log({"global_step": step, "eval/loss": 0.2})
```

Si vous n’avez pas accès à la variable d’étape indépendante, par exemple si "global\_step" n’est pas disponible pendant votre boucle de validation, la valeur précédemment journalisée pour "global\_step" est automatiquement utilisée par wandb. Dans ce cas, assurez-vous de journaliser une valeur initiale pour la métrique afin qu’elle soit définie au moment voulu.

<div id="log-media-and-structured-data">
  ### Journaliser des médias et des données structurées
</div>

Outre les scalaires, vous pouvez consigner des images, des tableaux, du texte, de l’audio, de la vidéo, etc.

Voici quelques points à prendre en compte lorsque vous enregistrez des données :

* À quelle fréquence la métrique doit-elle être enregistrée ? Doit-elle être facultative ?
* Quel type de données peut être utile pour la visualisation ?
  * Pour les images, vous pouvez enregistrer des exemples de prédictions, des masques de segmentation, etc., afin d’observer leur évolution au fil du temps.
  * Pour le texte, vous pouvez enregistrer des tableaux d’exemples de prédictions pour les explorer plus tard.

Voir [Journaliser des objets et des médias](/fr/models/track/log) pour des exemples.

<div id="support-distributed-training">
  ## Prise en charge de l’entraînement distribué
</div>

Pour les frameworks compatibles avec les environnements distribués, vous pouvez adapter l’un des flux de travail suivants :

* Journalisez uniquement depuis le processus principal (recommandé).
* Journalisez depuis chaque processus et regroupez les runs à l’aide d’un nom `group` partagé.

Voir [Journaliser des Experiments d’entraînement distribué](/fr/models/track/log/distributed-training/) pour plus de détails.

<div id="track-models-and-datasets-with-artifacts">
  ## Suivre les modèles et les Datasets avec Artifacts
</div>

Utilisez [W\&B Artifacts](/fr/models/artifacts/) pour suivre les modèles et les Datasets et en assurer la gestion des versions. Artifacts fournissent le stockage et la gestion des versions des ressources de machine learning, et assurent automatiquement la traçabilité afin de montrer comment les données et les modèles sont liés.

<Frame>
  <img src="https://mintcdn.com/wb-21fd5541/mVjDwbx0mC8gYx-b/images/integrations/integrations_add_any_lib_dag.png?fit=max&auto=format&n=mVjDwbx0mC8gYx-b&q=85&s=e3d7cd8e279f640b8f1a442dc83e1a8c" alt="Datasets stockés et points de contrôle du modèle dans W&B" width="1622" height="324" data-path="images/integrations/integrations_add_any_lib_dag.png" />
</Frame>

Tenez compte des points suivants lorsque vous intégrez Artifacts à votre bibliothèque :

* Déterminez s'il faut journaliser les points de contrôle du modèle ou les Datasets en tant qu'Artifacts (si vous souhaitez rendre cela facultatif).
* Références d'entrée d'Artifacts (par exemple, `entity/project/artifact`).
* Fréquence de journalisation des points de contrôle du modèle ou des Datasets. Par exemple, à chaque époque, toutes les 500 étapes, etc.

<div id="log-model-checkpoints">
  ### Journaliser les points de contrôle du modèle
</div>

Journalisez les points de contrôle du modèle dans W\&B. Une approche courante consiste à journaliser les points de contrôle comme des artifacts, en utilisant le run ID unique généré par W\&B dans le nom de l'artifact.

```python theme={null}
metadata = {"eval/accuracy": 0.8, "train/steps": 800}

artifact = wandb.Artifact(
                name=f"model-{run.id}",
                metadata=metadata,
                type="model"
                )
artifact.add_dir("output_model") # répertoire local où les poids du modèle sont stockés

aliases = ["best", "epoch_10"]
run.log_artifact(artifact, aliases=aliases)
```

L’extrait de code précédent montre comment journaliser un point de contrôle du modèle en tant qu’artifact et ajouter des métadonnées telles que la précision de l’évaluation et les étapes d’entraînement. L’artifact se voit attribuer un nom qui inclut le run ID unique, et il est étiqueté avec des [alias personnalisés](/fr/models/artifacts/create-a-custom-alias/) pour s’y référer facilement.

<div id="log-input-artifacts">
  ### Journaliser les artifacts en entrée
</div>

Journalisez les Datasets ou les modèles préentraînés utilisés en entrée :

```python theme={null}
dataset = wandb.Artifact(name="flowers", type="dataset")
dataset.add_file("flowers.npy")
run.use_artifact(dataset)
```

L’extrait de code précédent crée un artifact pour un jeu de données nommé "flowers" et y ajoute un fichier. L’artifact est ensuite associé au run en cours à l’aide de `run.use_artifact()`, ce qui permet à W\&B de suivre la traçabilité du jeu de données utilisé dans le run.

<div id="download-artifacts">
  ### Télécharger des Artifacts
</div>

Téléchargez des Artifacts déjà enregistrés dans W\&B afin de les utiliser dans votre code d’entraînement ou d’inférence.

Si vous disposez d’un contexte de run, utilisez [`wandb.Run.use_artifact()`](/fr/models/ref/python/experiments/run) pour faire référence à un artifact dans W\&B, puis appelez [`wandb.Artifact.download()`](/fr/models/ref/python/experiments/artifact) pour le télécharger dans un répertoire local.

```python theme={null}
with wandb.init(...) as run:
    artifact = run.use_artifact("user/project/artifact:latest")
    local_path = artifact.download()
```

Utilisez l’[API publique W\&B](/fr/models/ref/python/public-api/) pour référencer et télécharger un artifact sans initialiser un run. C’est utile dans des scénarios tels que les environnements distribués ou les workflows d’inférence, lorsque vous ne souhaitez pas créer de nouveau run.

```python theme={null}
import wandb
artifact = wandb.Api().artifact("user/project/artifact:latest")
local_path = artifact.download()
```

Voir [Télécharger et utiliser des Artifacts](/fr/models/artifacts/download-and-use-an-artifact/) pour en savoir plus.

<div id="tune-hyper-parameters">
  ## Ajuster les hyperparamètres
</div>

Si votre bibliothèque prend en charge l’ajustement des hyperparamètres, vous pouvez intégrer [W\&B Sweeps](/fr/models/sweeps/) pour gérer et visualiser les expériences.