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

# Ajouter W&B à une bibliothèque Python

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

Ce guide présente des 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 artifacts, 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 simple script d’entraînement ou un notebook. Pour une introduction à W\&B, consultez [Suivi des expériences](/fr/products/wandb/track).

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

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

* Si wandb est une dépendance obligatoire 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, quelles métriques et quels artifacts votre bibliothèque journalise.
* Si vous souhaitez prendre en charge l’optimisation des hyperparamètres avec W\&B Sweeps.
* Si vous souhaitez partager des artifacts, tels que des modèles et des jeux de données, via le registre de votre organisation.
* Comment votre bibliothèque gère l’entraînement distribué et les processus multiples.

Ces choix déterminent la manière 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.

<h2 id="decide-how-to-install-wb">
  Choisir le mode d’installation de W\&B
</h2>

Choisissez entre installer W\&B automatiquement avec votre bibliothèque ou le proposer comme fonctionnalité facultative.

<h3 id="require-wb-as-a-dependency">
  Déclarer W\&B comme dépendance obligatoire
</h3>

Si W\&B joue un rôle central dans votre bibliothèque, ajoutez `wandb` à ses dépendances.

Pour un fichier `requirements.txt` :

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

Pour un fichier `pyproject.toml` :

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

Envisagez de spécifier une plage de versions compatibles en fonction des fonctionnalités de W\&B qu’utilise votre intégration.

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

Si W\&B est une fonctionnalité facultative, faites en sorte que votre bibliothèque puisse être installée sans `wandb`.

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

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

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

Installez ensuite l’intégration avec la commande suivante :

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

<h2 id="authenticate-users">
  Authentifier les utilisateurs
</h2>

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

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

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

<Note>
  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.
</Note>

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

Dans votre terminal, exécutez :

```bash theme={"system"}
wandb login
```

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

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

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

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

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

Dans un environnement Python interactif ou un notebook, appelez :

```python theme={"system"}
import wandb

wandb.login()
```

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

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

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

| Mode | Comportement |
| - | - |
| `disabled` | Désactive la journalisation W\&B. W\&B n’enregistre ni ne téléverse les données du run. Les appels aux méthodes W\&B sont sans effet. |
| `offline` | Enregistre les données du run en local sans les téléverser. Vous pourrez téléverser le run plus tard avec [`wandb sync`](/fr/products/wandb/ref/cli/wandb-sync). |

Utilisez `disabled` si vous ne souhaitez pas enregistrer les données du run. Utilisez `offline` si vous souhaitez enregistrer les données en local pour les téléverser plus tard.

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

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

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

Vous pouvez aussi définir `WANDB_MODE` dans l’environnement :

```bash theme={"system"}
export WANDB_MODE=disabled
```

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

```bash theme={"system"}
wandb disabled
```

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

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

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

Vous pouvez aussi définir `WANDB_MODE` dans l’environnement :

```bash theme={"system"}
export WANDB_MODE=offline
```

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

```python theme={"system"}
import os

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

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

```bash theme={"system"}
wandb offline
```

Pour téléverser ultérieurement un run hors ligne, utilisez :

```bash theme={"system"}
wandb sync <run_directory>
```

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

Une fois authentifié, initialisez un [run](/fr/products/wandb/runs) pour consigner des métriques, des valeurs de [configuration](/fr/products/wandb/track/config) et des [artifacts](/fr/products/wandb/artifacts) depuis votre bibliothèque.

Appelez [`wandb.init()`](/fr/products/wandb/ref/python/functions/init) en indiquant le projet et l’entity d’équipe. Si vous omettez le projet, W\&B enregistre le run dans le projet par défaut `"uncategorized"`.

Utilisez `wandb.init()` comme gestionnaire de contexte autour de la boucle d’entraînement. À la sortie du bloc, W\&B termine 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={"system"}
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  # Léger 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 (double du bruit d’entrée)
    
    y_pred = model(xb)  # Prédiction du modèle
    loss = (yb - y_pred) ** 2  # Perte : erreur quadratique moyenne (MSE)

    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 des métriques avec `wandb.Run.log()` :

```python icon="python" title="Python" highlight={2,13-16,19,30-33} theme={"system"}
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 fermer 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 simulées (entrée)
        yb = weights + noise * 2  # Sortie cible simulée (bruit d’entrée doublé)
        
        y_pred = model(xb)  # Prédiction du modèle
        loss = (yb - y_pred) ** 2  # Perte par erreur quadratique moyenne (MSE)

        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 faire surveiller par W\&B. Utilisez-le comme gestionnaire de contexte englobant toute la boucle d’entraînement, afin que le run capture la sortie standard, l’erreur standard et les messages d’erreur utiles au débogage.
</Tip>

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

<h2 id="log-configuration-and-metrics">
  Journaliser la configuration et les métriques
</h2>

Journalisez les valeurs de configuration et les métriques dans W\&B afin que vous et les membres de votre équipe puissiez [comparer](/fr/products/wandb/runs/compare-runs), [filtrer](/fr/products/wandb/runs/filter-runs#example-filter-run-configuration-values-with-contains), [regrouper](/fr/products/wandb/runs/grouping) et [reproduire](/fr/products/wandb/track/reproduce_experiments) vos expériences.

<h3 id="log-configuration-values">
  Journaliser les valeurs de configuration
</h3>

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

Utilisez des clés descriptives et des valeurs sérialisables en JSON :

```python theme={"system"}
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={"system"}
with wandb.init(entity="your-entity", project="your-project-name", config=config) as run:
    # Logique d’entraînement.
```

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

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

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

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

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

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

```python icon="python" title="Python" theme={"system"}
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 obtenir des conseils sur la journalisation des types de données pris en charge, les données suivies automatiquement et les bonnes pratiques, consultez [Consigner des métriques et des données](/fr/products/wandb/track/log).

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

<h3 id="define-a-custom-log-axis">
  Définir un axe de journalisation personnalisé
</h3>

Par défaut, W\&B trace les métriques journalisées en fonction d’un step incrémenté automatiquement. Chaque appel à `wandb.Run.log()` incrémente le step.

Utilisez `wandb.Run.define_metric()` pour tracer une métrique en fonction d’une autre valeur, comme une époque ou un step global.

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

```python title="Python" icon="python" theme={"system"}
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/products/wandb/track/log/customize-logging-axes).

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

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 des runs.

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

Avant d’ajouter la prise en charge des artifacts, déterminez :

* les fichiers à journaliser ;
* si la journalisation des artifacts doit être facultative ;
* la fréquence de journalisation des points de contrôle ;
* la manière de nommer les artifacts et les alias ;
* les artifacts qui représentent les entrées et les sorties des runs.

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

Journalisez les points de contrôle du modèle sous forme d’artifacts afin de pouvoir récupérer, versionner et partager les poids entraînés. Incluez l’ID du run dans le nom de l’artifact pour 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 artifact dont le nom inclut l’ID du run, y ajoute les poids du modèle à partir d’un répertoire local, puis journalise l’artifact avec un [alias personnalisé](/fr/products/wandb/artifacts/create-a-custom-alias).

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

    # Placez ici les données d'entraînement et la logique d'entraînement du modèle

    if epoch % 10 == 0: # Journaliser 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 contenant les poids du modèle

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

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

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

Indiquez le nom de l’artifact et, si vous le souhaitez, un alias pour cibler une version précise de cet artifact. Le nom de l’artifact se présente au format `artifact_name:version` ou `artifact_name:alias`.

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

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

<h3 id="track-run-outputs">
  Suivre les sorties d’un run
</h3>

Utilisez [`wandb.Run.log_artifact()`](/fr/products/wandb/ref/python/experiments/run#method-run-log_artifact) pour journaliser un artifact comme sortie d’un run.

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

```python theme={"system"}
import wandb

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

  # Journaliser l’artifact comme sortie du run
  run.log_artifact(artifact_or_path = artifact)
```

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

<h3 id="download-artifacts">
  Télécharger des artifacts
</h3>

Utilisez l’[API publique W\&B](/fr/products/wandb/ref/python/public-api) pour télécharger un artifact sans créer de run ni l’enregistrer comme entrée d’un run.

```python theme={"system"}
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 artifacts](/fr/products/registry/download_use_artifact).

<h2 id="link-artifacts-to-the-registry">
  Lier des artifacts au registre
</h2>

Utilisez [Registry](/fr/products/registry) pour partager et gérer des versions d'artifact entre équipes.

Avant de lier une version d'artifact, déterminez :

* les versions d'artifact à partager ;
* les [collections](/fr/products/registry/create_collection) auxquelles les lier ;
* le [registre](/fr/products/registry) dans lequel les publier.

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

L'exemple suivant journalise un artifact et le lie à une collection d'un registre :

```python theme={"system"}
import wandb
import random

# Indiquer le nom de la collection et du registre
# dans lesquels vous souhaitez publier l’artifact
COLLECTION_NAME = "collection-name"
REGISTRY_NAME = "registry-name"

# Initialiser un run W&B pour suivre l’artifact
with wandb.init(project="project-name") as run:
    # Créer un fichier de modèle simulé afin de pouvoir le journaliser
    with open("my_model.txt", "w") as f:
        f.write("Model: " + str(random.random()))

    # Journaliser l’artifact dans W&B
    logged_artifact = run.log_artifact(
        artifact_or_path="./my_model.txt", 
        name="artifact-name",
        type="artifact-type" # Indique le type d’artifact
    )

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

Pour plus d'informations, voir [Lier une version d’artifact à une collection](/fr/products/registry/link_version).

<h2 id="tune-hyperparameters">
  Optimiser les hyperparamètres
</h2>

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

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

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

<h2 id="support-distributed-training">
  Prendre en charge l'entraînement distribué
</h2>

Si votre bibliothèque prend en charge plusieurs processus ou machines, déterminez quels processus créent des runs et journalisent des données.

Voici les approches courantes :

* Journaliser uniquement depuis le processus principal. Cette approche évite de dupliquer les métriques et les artifacts.
* Créer un run par processus et regrouper les runs à l'aide d'une valeur `group` commune.

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