> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-codex-link-agent-evals-docs.mintlify.site/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 W&B à votre bibliothèque Python pour le suivi des expériences, la surveillance système et Model Management.

Ce guide explique comment intégrer W\&B à une bibliothèque Python afin que vos utilisateurs puissent suivre les expériences, surveiller les métriques système et gérer des modèles lorsqu’ils utilisent votre code. Il s’adresse aux auteurs et mainteneurs de bibliothèques qui souhaitent exposer les fonctionnalités de W\&B via leur propre framework, SDK ou code d’entraînement réutilisable.

Suivez ces recommandations si vous intégrez W\&B dans une base de code complexe (comme un framework d’entraînement, un SDK ou une bibliothèque réutilisable), c’est-à-dire lorsque cette base de code va au-delà d’un simple script d’entraînement Python ou d’un notebook Jupyter.

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

Les sections suivantes présentent, dans l’ordre, les principales décisions d’intégration : comment installer W\&B, comment vous authentifier, comment démarrer et configurer des exécutions, comment consigner des métriques et des artefacts, et comment prendre en charge l’entraînement distribué et les Sweeps d’hyperparamètres.

<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. Ce choix a une incidence sur la façon dont vous importez le SDK Python W\&B (`wandb`), documentez l'installation et gérez les environnements dans lesquels `wandb` n'est pas présent.

<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 `wandb` à vos dépendances afin qu'il soit installé automatiquement avec votre bibliothèque :

```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é, afin que les utilisateurs qui n’ont pas besoin du suivi des expériences puissent quand même utiliser votre code.

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. Avant que les utilisateurs puissent enregistrer des runs depuis votre bibliothèque, ils doivent générer une clé API et la rendre disponible pour le client `wandb`.

<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. Générez une clé API depuis votre profil utilisateur afin de pouvoir l’utiliser pour les étapes de connexion qui suivent.

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

Une fois que vous avez une clé API, installez la bibliothèque `wandb` localement et connectez-vous afin que les runs suivants puissent s’authentifier auprès de W\&B. Choisissez l’onglet correspondant à votre environnement.

<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. Remplacez les valeurs entre `<>` par les vôtres :

       ```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. W\&B vous invitera à 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. W\&B vous invitera à saisir votre clé API.

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

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

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

Après avoir configuré l’authentification, l’étape suivante consiste à lancer un run W\&B afin que votre bibliothèque ait un emplacement où consigner des métriques, des configurations et des artéfacts.

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". Remplacez les valeurs entre `<>` par les vôtres :

```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. La fermeture du run garantit que toutes les métriques, configurations et artefacts sont téléversés avant que le processus ne se termine.

<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 à l'exécution, afin que les utilisateurs puissent exécuter votre bibliothèque sans produire de runs W\&B, utilisez l'une des approches suivantes :

* Définir une option `wandb`.
* Définir `wandb` sur `disabled` dans `wandb.init()`.
* Définir `wandb` en mode hors ligne. `wandb` s'exécute toujours, mais ne communique pas avec W\&B via Internet.

Définissez une option `wandb`, par exemple :

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    trainer = my_trainer(..., use_wandb=True)
    ```
  </Tab>

  <Tab title="Bash">
    ```bash theme={null}
    python train.py ... --use-wandb
    ```
  </Tab>
</Tabs>

Définissez `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>

Définissez `wandb` en mode hors ligne :

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

Après avoir initialisé un run, vous pouvez y joindre un dictionnaire de configuration qui enregistre les hyperparamètres et les autres métadonnées associés à ce run. La journalisation d’une configuration facilite la comparaison, le filtrage et la reproduction ultérieure des runs.

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 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 W\&B.

Par exemple, dans l’image suivante, la taille de lot (`batch_size`) est 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-codex-link-agent-evals-docs/dCnBB7xc0m6Fml3G/images/integrations/integrations_add_any_lib_runs_page.png?fit=max&auto=format&n=dCnBB7xc0m6Fml3G&q=85&s=7e079efcf2a92f0638100af4ad6c35e8" 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>

Certaines valeurs de configuration, comme le nombre de paramètres du modèle, peuvent ne pas être connues lorsque vous appelez `wandb.init()`. 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 d'informations, voir [Configurer les expériences](/fr/models/track/config/).

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

Une fois le run démarré et configuré, vous pouvez commencer à consigner des métriques et d’autres données afin que W\&B les enregistre pour ce run.

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

Pour journaliser des métriques scalaires telles que la perte ou la précision, créez un dictionnaire dans lequel chaque clé correspond au nom d’une 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 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ée 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-codex-link-agent-evals-docs/dCnBB7xc0m6Fml3G/images/integrations/integrations_add_any_lib_log.png?fit=max&auto=format&n=dCnBB7xc0m6Fml3G&q=85&s=1b4128bf9124a96e1cdb5fb3a0b27c79" alt="W&B Workspace" width="1236" height="738" data-path="images/integrations/integrations_add_any_lib_log.png" />
</Frame>

Pour plus d'informations, voir [`wandb.Run.log()`](/fr/models/ref/python/experiments/run#method-run-log).

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

Par défaut, le SDK Python de W\&B gère son propre compteur d’étapes, qui peut ne pas correspondre à la logique des étapes de votre boucle d’entraînement. 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 utilise `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, `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 W\&B. 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. La journalisation des médias avec les métriques aide les utilisateurs à examiner le comportement qualitatif du modèle au fil du temps.

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 et des masques de segmentation 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.

Pour plus d'informations, voir [Journaliser des objets et des médias](/fr/models/track/log).

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

Si votre bibliothèque peut exécuter l’entraînement sur plusieurs processus ou machines, décidez comment W\&B doit se comporter dans ce contexte afin que les journaux soient cohérents et non dupliqués. 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é.

Pour plus d'informations, voir [Journaliser des expériences d’entraînement distribué](/fr/models/track/log/distributed-training/).

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

En plus des métriques, vous pouvez conserver les modèles et les Datasets que votre bibliothèque produit ou consomme afin que les utilisateurs puissent reproduire et comparer les runs.

Utilisez [W\&B Artefacts](/fr/models/artifacts/) pour suivre les modèles et les Datasets et en assurer la gestion des versions. Les artefacts 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-codex-link-agent-evals-docs/dCnBB7xc0m6Fml3G/images/integrations/integrations_add_any_lib_dag.png?fit=max&auto=format&n=dCnBB7xc0m6Fml3G&q=85&s=80d9e232fcb4f8773b25f0f10e89d679" 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 les artefacts à votre bibliothèque :

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

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

La journalisation des points de contrôle du modèle en tant qu’artefacts permet aux utilisateurs de récupérer, de versionner et de partager les poids entraînés. Une approche courante consiste à journaliser les points de contrôle comme des artefacts, en utilisant le run ID unique généré par W\&B dans le nom de l'artefact.

```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 précédent journalise un point de contrôle du modèle en tant qu’artefact avec des métadonnées telles que la précision de l’évaluation et les étapes d’entraînement. Le nom de l’artefact 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 rapidement.

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

Pour capturer la traçabilité entre les données et les modèles, journalisez les datasets ou les modèles préentraînés qu’un run utilise 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 artefact pour un dataset nommé "flowers" et y ajoute un fichier. L’appel à `wandb.Run.use_artifact()` associe l’artefact au run en cours afin que W\&B puisse suivre la traçabilité du dataset utilisé dans le run.

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

Après avoir enregistré des artefacts, vous pouvez télécharger des artefacts précédemment enregistrés depuis W\&B afin de les utiliser dans votre code d’entraînement ou d’inférence. La bonne approche dépend du fait que vous disposiez déjà ou non d’un run actif.

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 artefact dans W\&B, puis appelez [`wandb.Artifact.download()`](/fr/models/ref/python/experiments/artifact) pour le télécharger dans un répertoire local. L’utilisation de `wandb.Run.use_artifact()` enregistre également l’artefact comme entrée du run actuel, ce qui préserve la traçabilité.

```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 artefact sans initialiser un run. C’est utile dans des scénarios tels que les environnements distribués ou lorsque vous effectuez de l’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()
```

Pour plus d'informations, voir [Télécharger et utiliser des artefacts](/fr/models/artifacts/download-and-use-an-artifact/).

<div id="tune-hyperparameters">
  ## 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. Les balayages coordonnent plusieurs runs dans un espace de recherche défini et affichent les résultats dans W\&B afin que les utilisateurs puissent comparer les configurations côte à côte.