> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-locadex-parallel-t9n-main-cs60c8p4o6ik99tylxgp3.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 décrit différentes approches pour intégrer W\&B dans une bibliothèque, un framework ou un SDK Python. Il couvre la gestion des dépendances, l’authentification, la journalisation facultative, l’initialisation des runs, les artefacts, l’optimisation des hyperparamètres et l’exécution distribuée.

Utilisez ce guide lorsque votre intégration porte sur du code de bibliothèque réutilisable plutôt que sur un seul script d’entraînement ou notebook. Pour une introduction à W\&B, consultez [Suivi des expériences](/fr/models/track).

<div id="design-the-integration">
  ## Concevoir l’intégration
</div>

Avant d’ajouter W\&B à votre bibliothèque, déterminez :

* Si wandb est une dépendance requise ou facultative.
* Si les utilisateurs peuvent exécuter votre bibliothèque sans enregistrer ni téléverser de données W\&B.
* Quelles valeurs de configuration, métriques et quels artefacts votre bibliothèque journalise.
* S’il faut prendre en charge l’optimisation des hyperparamètres avec les balayages W\&B.
* S’il faut partager des artefacts, tels que des modèles et des jeux de données, via le Registry W\&B de votre organisation.
* Comment votre bibliothèque gère l’entraînement distribué et plusieurs processus.

Ces choix déterminent la façon dont votre bibliothèque importe W\&B, gère le cycle de vie des runs et se comporte lorsque W\&B n’est pas disponible.

<div id="decide-how-to-install-wb">
  ## Choisissez comment installer W\&B
</div>

Choisissez d’installer automatiquement W\&B avec votre bibliothèque ou de l’exposer comme fonctionnalité facultative.

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

Si W\&B est au cœur de votre bibliothèque, ajoutez `wandb` à ses dépendances.

Pour un fichier `requirements.txt` :

```txt title="requirements.txt" type="text" theme={null}
torch
wandb
```

Pour un fichier `pyproject.toml` :

```toml title="pyproject.toml" type="toml" theme={null}
[project]
name = "my_awesome_lib"
version = "0.1.0"
dependencies = [
    "torch",
    "wandb",
]
```

Envisagez de spécifier une plage de versions compatible en fonction des fonctionnalités W\&B utilisées par votre intégration.

<div id="make-wb-an-optional-dependency">
  ### Faites de W\&B une dépendance facultative
</div>

Si W\&B est une fonctionnalité facultative, permettez l'installation de votre bibliothèque sans `wandb`.

Déclarez W\&B en tant que dépendance facultative dans `pyproject.toml` :

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

[project.optional-dependencies]
wandb = [
    "wandb",
]
```

Installez ensuite l’intégration avec :

```bash theme={null}
pip install "my_awesome_lib[wandb]"
```

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

W\&B utilise des clés API pour authentifier les utilisateurs et les machines. Avant de pouvoir enregistrer des runs depuis votre bibliothèque, vous devez générer une clé API et la rendre disponible pour le client `wandb`.

W\&B prend en charge l’authentification via le CLI, les variables d’environnement et `wandb.login()`.

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

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

<div id="authenticate-from-the-command-line">
  ### S’authentifier depuis la ligne de commande
</div>

Dans votre terminal, exécutez :

```bash theme={null}
wandb login
```

W\&B vous invite à saisir une clé API.

Vous pouvez également définir la variable d’environnement `WANDB_API_KEY` :

```bash theme={null}
export WANDB_API_KEY="<api_key>"
```

Pour plus d'informations, voir [Variables d'environnement](/fr/models/track/environment-variables).

<div id="authenticate-from-python">
  ### S’authentifier depuis Python
</div>

Dans un environnement Python interactif ou un notebook, appelez :

```python theme={null}
import wandb

wandb.login()
```

Évitez d’appeler automatiquement [`wandb.login()`](/fr/models/ref/python/functions/login) dans du code de bibliothèque réutilisable, car cela peut interrompre les flux de travail non interactifs.

<div id="make-wb-logging-optional">
  ## Rendre la journalisation W\&B facultative
</div>

Choisissez si W\&B enregistre ou téléverse les données de run.

| Mode       | Comportement                                                                                                                                                    |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `disabled` | Désactive la journalisation W\&B. W\&B n’enregistre ni ne téléverse les données de run. Les appels aux méthodes W\&B n’ont aucun effet.                         |
| `offline`  | Enregistre les données de run localement sans les téléverser. Vous pourrez téléverser le run ultérieurement avec [`wandb sync`](/fr/models/ref/cli/wandb-sync). |

Utilisez `disabled` si vous ne souhaitez pas enregistrer les données de run. Utilisez `offline` si vous souhaitez enregistrer les données localement pour les téléverser ultérieurement.

<div id="use-disabled-mode">
  ### Utiliser le mode `disabled`
</div>

Transmettez `mode="disabled"` à `wandb.init()` :

```python theme={null}
with wandb.init(mode="disabled") as run:
    # Logique d'entraînement.
```

Ou définissez `WANDB_MODE` dans l’environnement :

```bash theme={null}
export WANDB_MODE=disabled
```

Vous pouvez également définir le mode avec la CLI W\&B :

```bash theme={null}
wandb disabled
```

<div id="use-offline-mode">
  ### Utiliser le mode `offline`
</div>

Transmettez `mode="offline"` à `wandb.init()` :

```python theme={null}
with wandb.init(mode="offline") as run:
    # Logique d'entraînement.
```

Ou définissez `WANDB_MODE` dans l’environnement :

```bash theme={null}
export WANDB_MODE=offline
```

En Python, définissez la variable d’environnement avant d’appeler `wandb.init()` :

```python theme={null}
import os

os.environ["WANDB_MODE"] = "offline"
```

Vous pouvez également définir le mode à l’aide de la CLI W\&B :

```bash theme={null}
wandb offline
```

Téléversez ultérieurement un run hors ligne avec :

```bash theme={null}
wandb sync <run_directory>
```

<div id="initialize-a-run">
  ## Initialiser un run
</div>

Après vous être authentifié, initialisez un [run](/fr/models/runs) pour consigner des métriques, des valeurs de [configuration](/fr/models/track/config) et des [artefacts](/fr/models/artifacts) à partir de votre bibliothèque.

Appelez [`wandb.init()`](/fr/models/ref/python/functions/init) et spécifiez le projet et l’entité d’équipe. Si vous omettez le projet, W\&B stocke le run dans le projet `"uncategorized"` par défaut.

Utilisez `wandb.init()` comme gestionnaire de contexte autour de la boucle d’entraînement. À la sortie du bloc, W\&B finalise le run et traite les données en attente avant la fin du processus.

Par exemple, supposons que votre bibliothèque contienne la boucle d’entraînement suivante :

```python icon="python" title="Python" theme={null}
import random # Pour simuler des données

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# Simuler les poids et le bruit
weights = random.random() # Initialiser des poids aléatoires
noise = random.random() / 5  # Faible bruit aléatoire pour simuler du bruit

for epoch in range(epochs):
    xb = weights + noise  # Données d'entraînement d'entrée simulées
    yb = weights + noise * 2  # Sortie cible simulée (le double du bruit d'entrée)
    
    y_pred = model(xb)  # Prédiction du modèle
    loss = (yb - y_pred) ** 2  # Perte d'erreur quadratique moyenne

    print(f"epoch={epoch}, loss={loss}")
```

Pour intégrer W\&B, initialisez un run à l’aide d’un gestionnaire de contexte, transmettez les valeurs de configuration à `wandb.init()` et consignez les métriques avec `wandb.Run.log()` :

```python icon="python" title="Python" highlight={2,13-16,19,30-33} theme={null}
import random # Pour simuler des données
import wandb

def model(training_data: int) -> int:
    """Model simulation for demonstration purposes."""
    return training_data * 2 + random.randint(-1, 1)  

# Simuler les poids et le bruit
weights = random.random() # Initialiser des poids aléatoires
noise = random.random() / 5  # Faible bruit aléatoire pour simuler du bruit

# Hyperparamètres et configuration
config = {
    "epochs": 10,  # Nombre d'époques d'entraînement
    "learning_rate": 0.01,  # Taux d'apprentissage de l'optimiseur
}

# Utiliser un gestionnaire de contexte pour initialiser et clôturer les runs W&B
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:    
    # Simuler la boucle d'entraînement
    for epoch in range(config["epochs"]):
        xb = weights + noise  # Données d'entraînement d'entrée simulées
        yb = weights + noise * 2  # Sortie cible simulée (le double du bruit d'entrée)
        
        y_pred = model(xb)  # Prédiction du modèle
        loss = (yb - y_pred) ** 2  # Perte : erreur quadratique moyenne

        print(f"epoch={epoch}, loss={loss}")
        # Journaliser l'époque et la perte dans W&B
        run.log({
            "epoch": epoch,
            "loss": loss,
        })
```

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

  Appelez `wandb.init()` avant le code que vous souhaitez surveiller avec W\&B. Utilisez-le comme gestionnaire de contexte autour de toute la boucle d’entraînement afin que le run capture les sorties standard et d’erreur, ainsi que les messages d’erreur pertinents pour le débogage.
</Tip>

La [section suivante](#log-configuration-and-metrics) explique en détail comment journaliser les valeurs de configuration et les métriques depuis votre bibliothèque.

<div id="log-configuration-and-metrics">
  ## Enregistrez la configuration et les métriques
</div>

Enregistrez les valeurs de configuration et les métriques dans W\&B afin de pouvoir, avec les membres de votre équipe, [comparer](/fr/models/runs/compare-runs), [filtrer](/fr/models/runs/filter-runs#example-filter-run-configuration-values-with-contains), [regrouper](/fr/models/runs/grouping) et [reproduire](/fr/models/track/reproduce_experiments) des expériences.

<div id="log-configuration-values">
  ### Enregistrer les valeurs de configuration
</div>

Transmettez un dictionnaire de [configuration](/fr/models/track/config) à `wandb.init()` pour enregistrer les hyperparamètres et d'autres métadonnées.

Utilisez des clés explicites et des valeurs sérialisables au format JSON :

```python theme={null}
config = {
    "batch_size": 32,
    "learning_rate": 0.001,
    "optimizer": "adam",
    "model": {
        "type": "resnet",
        "depth": 50,
    },
    "dataset": {
        "name": "CIFAR-10",
        "num_classes": 10,
    },
}
```

Transmettez le dictionnaire à `wandb.init()` :

```python theme={null}
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # Logique d'entraînement.
```

Certaines valeurs peuvent ne pas être disponibles au démarrage du run. Ajoutez-les ultérieurement avec `wandb.Run.config.update()` :

```python theme={null}
run.config.update(
    {
        "model_parameters": 3500,
    }
)
```

Pour plus d'informations, voir [Configurer les expériences](/fr/models/track/config).

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

Consignez des métriques, telles que la perte ou la précision, pendant l’entraînement. Créez un dictionnaire où chaque clé correspond au nom d’une métrique et chaque valeur à sa valeur. Transmettez ce dictionnaire à [`wandb.Run.log()`](/fr/models/ref/python/experiments/run#method-run-log).

L’extrait de code suivant consigne les métriques d’entraînement et de validation dans W\&B :

```python icon="python" title="Python" theme={null}
import wandb

with wandb.init(entity="your-entity", project="your-project-name") as run:
    metrics = {
        "train/loss": 0.4,
        "train/learning_rate": 0.4,
        "val/loss": 0.5, 
        "val/accuracy": 0.7
    }
    run.log(metrics)
```

Utilisez des préfixes tels que `train/` et `val/` pour regrouper les métriques associées.

Pour en savoir plus sur la journalisation des types de données pris en charge, des données suivies automatiquement et les bonnes pratiques, voir [Consigner des métriques et des données](/fr/models/track/log).

Pour suivre les modèles et les jeux de données, voir la section [Suivre les modèles et les jeux de données avec des artefacts](#track-models-and-datasets-with-artifacts).

<div id="define-a-custom-log-axis">
  ### Définir un axe personnalisé pour le journal
</div>

Par défaut, W\&B représente les métriques enregistrées en fonction d’une étape incrémentée automatiquement. Chaque appel à `wandb.Run.log()` incrémente l’étape.

Utilisez `wandb.Run.define_metric()` pour représenter une métrique en fonction d’une autre valeur, telle qu’une époque ou une étape globale.

L’exemple suivant définit `x_axis_squared` comme axe X pour `validation_loss`. À chaque itération de la boucle, `x_axis_squared` correspond au carré de l’index `i` et `validation_loss` à une valeur générée aléatoirement :

```python title="Python" icon="python" theme={null}
import wandb
import random

with wandb.init() as run:
    run.define_metric(step_metric = "x_axis_squared", name = "validation_loss")

    for i in range(10):
        log_dict = {
            "x_axis_squared": i**2,
            "validation_loss": random.random(),
        }
        run.log(log_dict)
```

Pour plus d'informations, voir [Définir un axe de journalisation personnalisé](/fr/models/track/log/customize-logging-axes).

<div id="track-models-and-datasets-with-artifacts">
  ## Suivre les modèles et les jeux de données avec des artefacts
</div>

En plus des métriques, vous pouvez conserver les modèles et les jeux de données que votre bibliothèque produit ou consomme afin que vous et les membres de votre équipe puissiez reproduire et comparer les runs.

Utilisez [W\&B Artifacts](/fr/models/artifacts) pour gérer les versions des modèles, des jeux de données et des autres fichiers que votre bibliothèque produit ou consomme.

Avant d'ajouter la prise en charge des artefacts, déterminez :

* Quels fichiers journaliser.
* Si la journalisation des artefacts est facultative.
* À quelle fréquence journaliser les points de contrôle.
* Comment nommer les artefacts et les alias.
* Quels artefacts représentent les entrées et les sorties des runs.

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

Journalisez les points de contrôle du modèle sous forme d’artefacts afin de pouvoir récupérer, versionner et partager les poids entraînés. Incluez l’ID du run dans le nom de l’artefact afin d’associer chaque point de contrôle à son run d’origine.

L’exemple suivant journalise un point de contrôle toutes les 10 époques. Il crée un artefact dont le nom inclut l’ID du run, y ajoute les poids du modèle depuis un répertoire local et journalise l’artefact avec un [alias personnalisé](/fr/models/artifacts/create-a-custom-alias).

```python title="Python" icon="python" theme={null}
import wandb
with wandb.init(entity="your-entity", project="your-project-name") as run:

    # Données d'entraînement et logique d'entraînement du modèle ici

    if epoch % 10 == 0: # Journalise un point de contrôle du modèle toutes les 10 époques

        metadata = {"eval/accuracy": 0.8, "train/steps": 800} 

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

        run.log_artifact(artifact, aliases=f"epoch_{epoch}")
```

<div id="track-run-inputs">
  ### Suivre les entrées d’un run
</div>

Utilisez [`wandb.Run.use_artifact()`](/fr/models/ref/python/experiments/run#method-run-use_artifact) lorsqu’un run utilise un artefact, tel qu’un jeu de données ou un point de contrôle de modèle. W\&B enregistre l’artefact comme entrée du run.

Indiquez le nom de l’artefact et, éventuellement, un alias pour faire référence à une version spécifique de cet artefact. Le nom de l’artefact utilise le format `artifact_name:version` ou `artifact_name:alias`.

```python title="Python" icon="python" theme={null}
import wandb

# Initialiser un run
with wandb.init(entity="your-entity", project="your-project") as run:
  # Récupérer l'artefact et le marquer comme dépendance
  artifact = run.use_artifact(artifact_or_name="artifact_name:alias_or_version")
```

<div id="track-run-outputs">
  ### Suivre les sorties d’une exécution
</div>

Utilisez [`wandb.Run.log_artifact()`](/fr/models/ref/python/experiments/run#method-run-log_artifact) pour consigner un artefact en tant que sortie d’une exécution.

1. Créez un artefact avec `wandb.Artifact()`.
2. Ajoutez un ou plusieurs fichiers à l’artefact.
3. Consignez l’artefact avec `wandb.Run.log_artifact()`.

```python theme={null}
import wandb

# Initialiser un run
with wandb.init(entity="your-entity", project="project-name") as run:
  
  # Créer un artefact
  artifact = wandb.Artifact(name = "artifact-name", type = "artifact-type")
  artifact.add_file(local_path = "path/to/file", name="optional-filename") # Ajouter un fichier à l'artefact

  # Journaliser l'artefact en tant que sortie du run
  run.log_artifact(artifact_or_path = artifact)
```

Pour en savoir plus sur la création, la gestion et l'utilisation des artefacts, consultez [Artifacts](/fr/models/artifacts).

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

Utilisez l’[API publique W\&B](/fr/models/ref/python/public-api) pour télécharger un artefact sans créer de run ni enregistrer de relation entre un run et une entrée.

```python theme={null}
import wandb

api = wandb.Api()

artifact = api.artifact(
    "<entity>/<project>/<artifact_name>:<alias_or_version>"
)

local_path = artifact.download()
```

Pour plus d’informations, consultez [Télécharger et utiliser des artefacts](/fr/models/registry/download_use_artifact).

<div id="link-artifacts-to-the-wb-registry">
  ## Lier des artefacts au W\&B Registry
</div>

Utilisez le [W\&B Registry](/fr/models/registry) pour partager et gérer des versions d’artefacts entre équipes.

Avant de lier une version d’artefact, déterminez :

* Quelles versions d’artefacts partager.
* Auxquelles des [collections](/fr/models/registry/create_collection) les lier.
* Dans quel [registre](/fr/models/registry) les publier.

<Note>
  Le registre de destination doit déjà exister.
</Note>

L’exemple suivant journalise un artefact et le lie à une collection dans un registre :

```python theme={null}
import wandb
import random

# Indiquez le nom de la collection et du registry
# dans lesquels publier l'artefact
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

# Initialisez un W&B Run pour suivre l'artefact
with wandb.init(project="project-name") as run:
    # Créez un fichier de modèle simulé afin de pouvoir l'enregistrer
    with open("my_model.txt", "w") as f:
        f.write("Model: " + str(random.random()))

    # Enregistrez l'artefact dans W&B
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # Spécifie le type d'artefact
    )

    # Liez l'artefact au registry
    run.link_artifact(
        artifact=logged_artifact, 
        target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}"
    )
```

Pour plus d'informations, voir [Associer une version d'artefact à une collection](/fr/models/registry/link_version).

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

Si votre bibliothèque prend en charge l'optimisation des hyperparamètres, intégrez les [balayages W\&B](/fr/models/sweeps) pour effectuer des recherches par grille, aléatoires ou bayésiennes.

<Tip>
  W\&B recommande de séparer la configuration de balayage de la logique d'entraînement sous-jacente. La fonction d'entraînement doit lire ses paramètres dans `wandb.Run.config` plutôt que de dépendre directement d'une logique propre au balayage.
</Tip>

Pour plus d'informations, voir [Sweeps](/fr/models/sweeps).

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

Si votre bibliothèque prend en charge plusieurs processus ou machines, définissez quels processus doivent créer des runs et consigner des données.

Les approches courantes comprennent :

* Journalisez uniquement depuis le processus principal. Cette approche évite les doublons de métriques et d’artefacts.
* Créez un run pour chaque processus et regroupez les runs à l’aide d’une valeur `group` partagée.

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