Journaliser des médias et des objets

Journalisez des médias avec le SDK Python Weights & Biases pour inspecter les entrées et les sorties de vos modèles, et comparer les résultats entre vos runs, vos modèles et vos datasets. Les types pris en charge comprennent les images, l’audio, les vidéos, les histogrammes, les nuages de points 3D, les molécules et le HTML. Pour plus de détails sur l’API, consultez la référence des Types de données. Pour des exemples, consultez le rapport sur les prédictions de modèles ou regardez le guide pas à pas en vidéo.

Prérequis

Certains types de médias nécessitent des dépendances supplémentaires. Pour installer le SDK Weights & Biases avec les dépendances liées aux médias, exécutez :

pip install wandb[media]

Images

Utilisez wandb.Image pour journaliser des images à partir de tableaux NumPy, d’images PIL ou de fichiers locaux. La journalisation d’images vous permet d’inspecter les entrées, les sorties, les poids des filtres et les activations.

CoreWeave recommande de journaliser moins de 50 images par étape afin de limiter l’impact sur les performances d’entraînement et sur les temps de chargement des images.

Les onglets suivants montrent comment journaliser des images à partir de différents types d’entrée.

Tableaux
Images PIL
Fichiers image

Fournissez directement des tableaux lorsque vous construisez des images manuellement, par exemple avec make_grid de torchvision.

Weights & Biases convertit les tableaux en images PNG à l’aide de Pillow.

import wandb
import numpy as np

with wandb.init(project="image-log-example") as run:
    images = wandb.Image(image_array, caption="Top: Output, Bottom: Input")
    run.log({"examples": images})

Pour les tableaux NumPy, utilisez la forme (height, width, channels). Weights & Biases déduit le format (niveaux de gris, RGB ou RGBA) du nombre de canaux : 1, 3 ou 4, respectivement. Par défaut, les images sont enregistrées au format PNG.Les valeurs des pixels sont normalisées dans la plage 0–255 si elles sortent de cette plage ou si elles sont toutes comprises entre 0 et 1. Pour désactiver la normalisation, passez normalize=False. Pour mieux contrôler la conversion des tableaux, créez une image PIL comme indiqué dans l’onglet Images PIL.

Créez une PIL.Image et passez-la à wandb.Image.

from PIL import Image

image_array = np.random.randint(0, 256, (128, 128, 3), dtype=np.uint8)

with wandb.init(project="pil-image-example") as run:
    # Créer une image PIL à partir d’un tableau NumPy
    image = Image.fromarray(image_array)

    # Facultatif : convertir en RGB si nécessaire
    if image.mode != "RGB":
        image = image.convert("RGB")

    # Journaliser l’image
    run.log({"example": wandb.Image(image, caption="My Image")})

Pour journaliser un fichier image existant, passez son chemin à wandb.Image.

with wandb.init(project="media-log-example") as run:
    run.log({"example": wandb.Image("myimage.jpg")})

Pour comparer des images d’une étape d’entraînement à l’autre, développez le panneau d’images dans l’interface de l’application Weights & Biases et utilisez le curseur de sélection des étapes. Sélectionnez une image pour l’ouvrir en plein écran : vous pouvez alors zoomer et vous déplacer avec la souris ou les raccourcis clavier. Pour comparer dans une même vue des images ou des vidéos issues de différents runs, étapes ou indices, utilisez le mode de comparaison.

Superpositions d’images

Journalisez des masques de segmentation sémantique pour ajuster leur opacité et examiner leur évolution d’une étape à l’autre dans l’interface de l’application Weights & Biases.

Masques de segmentation
Boîtes englobantes

Journalisez des images avec des masques de segmentation ou des boîtes englobantes pour examiner les prédictions du modèle et la vérité terrain dans l’interface de l’application Weights & Biases.

Passez un dictionnaire à l’argument masks de wandb.Image. Chaque clé correspond au nom d’un masque, par exemple predictions ou ground_truth. Chaque valeur est un dictionnaire contenant les champs suivants :

Champ	Description
`mask_data`	Un tableau NumPy 2D contenant une étiquette de classe entière pour chaque pixel. Fournissez soit `mask_data`, soit `path`.
`path`	Le chemin d’une image de masque enregistrée. Fournissez soit `path`, soit `mask_data`.
`class_labels`	Dictionnaire facultatif qui associe les étiquettes de classe entières à des noms lisibles.

Pour journaliser plusieurs masques pour une même image, fournissez un dictionnaire distinct pour chaque masque :

mask_data = np.array([[1, 2, 2, ..., 2, 2, 1], ...])

class_labels = {1: "tree", 2: "car", 3: "road"}

mask_img = wandb.Image(
    image,
    masks={
        "predictions": {"mask_data": mask_data, "class_labels": class_labels},
        "ground_truth": {
            # ...
        },
        # ...
    },
)

Les masques de segmentation de chaque clé sont définis à chaque step (chaque appel à wandb.Run.log()).

Si plusieurs steps fournissent des valeurs différentes pour la même clé de masque, seule la valeur la plus récente de cette clé est appliquée à l’image.
Si plusieurs steps fournissent des clés de masque différentes, les commandes de visibilité affichent toutes les clés, mais seuls les masques définis au step sélectionné sont appliqués à l’image. Activer ou désactiver un masque qui n’est pas défini à ce step n’a aucun effet sur l’image.

Pour un exemple complet, consultez le rapport sur les masques de segmentation et le notebook d’exemple.

Journalisez des images avec des boîtes englobantes, puis utilisez les filtres et les contrôles de visibilité pour examiner des groupes de boîtes dans l’interface de l’application Weights & Biases.

Passez un dictionnaire à l’argument boxes de wandb.Image. Chaque clé correspond au nom d’un groupe, par exemple predictions ou ground_truth. Chaque valeur contient les champs suivants :

Champ	Description
`box_data`	Une liste de dictionnaires, un par boîte englobante.
`class_labels`	Dictionnaire facultatif qui associe les ID de classe à des noms lisibles. S’il est omis, Weights & Biases génère des noms tels que `class_0` et `class_1`.

Chaque dictionnaire de box_data décrit une boîte :

Champ	Description
`position`	La position et la taille de la boîte. Utilisez soit `minX`, `maxX`, `minY` et `maxY`, soit `middle`, `width` et `height`. Pour `middle`, fournissez des coordonnées `[x, y]`. Chaque boîte peut utiliser un format différent.
`class_id`	Un ID de classe entier correspondant à une entrée de `class_labels`.
`scores`	Un dictionnaire qui associe des noms de score à des valeurs numériques. Utilisez ces scores pour filtrer les boîtes dans l’interface de l’application Weights & Biases.
`domain`	Unité des coordonnées. Définissez la valeur `"pixel"` pour utiliser des coordonnées en pixels. Par défaut, les coordonnées sont exprimées en fractions des dimensions de l’image, de 0 à 1.
`box_caption`	Texte facultatif à afficher sur la boîte.

Cet exemple journalise une boîte avec des coordonnées relatives et une autre avec des coordonnées en pixels :

import wandb

class_id_to_label = {
    1: "car",
    2: "road",
    3: "building"
}

img = wandb.Image(
    image,
    boxes={
        "predictions": {
            "box_data": [
                {
                    # une boîte exprimée dans le domaine relatif/fractionnaire par défaut
                    "position": {"minX": 0.1, "maxX": 0.2, "minY": 0.3, "maxY": 0.4},
                    "class_id": 2,
                    "box_caption": class_id_to_label[2],
                    "scores": {"acc": 0.1, "loss": 1.2},
                    # une autre boîte exprimée en pixels
                    # (à titre d’illustration uniquement : en pratique, toutes les boîtes
                    # utiliseront probablement le même domaine/format)
                    "position": {"middle": [150, 20], "width": 68, "height": 112},
                    "domain": "pixel",
                    "class_id": 3,
                    "box_caption": "a building",
                    "scores": {"acc": 0.5, "loss": 0.7},
                    # ...
                    # Journalisez autant de boîtes que nécessaire
                }
            ],
            "class_labels": class_id_to_label,
        },
        # Journalisez chaque groupe de boîtes pertinent sous un nom de clé unique
        "ground_truth": {
            # ...
        },
    },
)

with wandb.init(project="my_project") as run:
    run.log({"driving_scene": img})

Pour un exemple interactif, consultez le rapport sur les boîtes englobantes.

Superpositions sur les images dans les Tables

Pour afficher des superpositions sur les images dans une Table Weights & Biases, ajoutez à chaque ligne un objet wandb.Image contenant des masques ou des boîtes englobantes.

Masques de segmentation
Boîtes englobantes

Masques de segmentation interactifs dans les Tables

Cet exemple journalise une image avec des masques de segmentation pour chaque ligne du tableau :

table = wandb.Table(columns=["ID", "Image"])

for id, img, label in zip(ids, images, labels):
    mask_img = wandb.Image(
        img,
        masks={
            "prediction": {
                "mask_data": label,
                "class_labels": class_labels
                }
            # ...
        },
    )

    table.add_data(id, mask_img)

with wandb.init(project="my_project") as run:
    run.log({"Table": table})

Boîtes englobantes interactives dans les Tables

Cet exemple journalise une image avec des boîtes englobantes pour chaque ligne du tableau :

table = wandb.Table(columns=["ID", "Image"])

for id, img, boxes in zip(ids, images, boxes_set):
    box_img = wandb.Image(
        img,
        boxes={
            "prediction": {
                "box_data": [
                    {
                        "position": {
                            "minX": box["minX"],
                            "minY": box["minY"],
                            "maxX": box["maxX"],
                            "maxY": box["maxY"],
                        },
                        "class_id": box["class_id"],
                        "box_caption": box["caption"],
                        "domain": "pixel",
                    }
                    for box in boxes
                ],
                "class_labels": class_labels,
            }
        },
    )

Histogrammes

Utilisez wandb.Histogram pour journaliser des distributions numériques, comme les gradients d’un modèle. Dans l’interface de l’application Weights & Biases, l’axe X représente les étapes d’entraînement, l’axe Y les valeurs de métrique, et la couleur indique le nombre d’occurrences dans chaque classe.

Journalisation de base d’histogrammes
Journalisation flexible d’histogrammes

Passez une séquence de nombres, comme une liste, un tableau ou un tenseur, à wandb.Histogram. Weights & Biases aplatit les tableaux et les tenseurs, puis utilise numpy.histogram() pour calculer l’histogramme.Par défaut, les histogrammes comportent 64 classes. Pour personnaliser le nombre de classes, attribuez à num_bins une valeur pouvant aller jusqu’à 512.

with wandb.init() as run:
    run.log({"gradients": wandb.Histogram(grads)})

Pour contrôler le calcul de l’histogramme, appelez np.histogram() et passez le tuple renvoyé à np_histogram :

import numpy as np

np_hist_grads = np.histogram(grads, density=True, range=(0.0, 1.0))

with wandb.init() as run:
    run.log({"gradients": wandb.Histogram(np_hist_grads)})

Vous pouvez également définir density=True pour exprimer les valeurs des classes sous forme de densité de probabilité plutôt que d’effectifs.

Visualisations 3D

Utilisez wandb.Object3D pour journaliser des nuages de points 3D et des scènes lidar avec des boîtes englobantes. Fournissez un tableau NumPy contenant les coordonnées des points et, éventuellement, leurs couleurs ou leurs étiquettes de catégorie. Les nuages de points sont interactifs dans l’interface de l’application Weights & Biases. Faites glisser la souris pour faire pivoter la vue, zoomez pour examiner les détails ou maintenez la touche Control enfoncée tout en utilisant la souris pour vous déplacer dans la scène. Le rapport suivant présente des scènes du dataset Lyft avec des boîtes englobantes 3D :

L’interface de l’application Weights & Biases affiche jusqu’à 300 000 points par nuage de points.

Formats de tableaux NumPy

Utilisez l’un des formats de tableaux suivants, où n correspond au nombre de points :

Forme	Format de point	Description
`(n, 3)`	`[x, y, z]`	Coordonnées du point.
`(n, 4)`	`[x, y, z, category]`	Coordonnées et catégorie comprise entre 1 et 14, par exemple une classe de segmentation.
`(n, 6)`	`[x, y, z, r, g, b]`	Coordonnées et valeurs de rouge, de vert et de bleu comprises entre 0 et 255.

Objet Python

Utilisez wandb.Object3D.from_point_cloud() pour créer une scène contenant des points, des boîtes englobantes et des vecteurs.

import wandb
import numpy as np

points = np.array([
    [0.2, 0.3, 0.4, 255, 0, 0],
    [0.5, 0.6, 0.7, 0, 255, 0],
    [0.8, 0.9, 0.2, 0, 0, 255],
])

boxes = [{
    "corners": [
        [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
        [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1],
    ],
    "color": [0, 0, 255],
    "label": "example region",
    "score": 0.6,
}]

scene = wandb.Object3D.from_point_cloud(
    points=points,
    boxes=boxes,
    vectors=[{"start": [0, 0, 0], "end": [0.1, 0.2, 0.5], "color": [255, 0, 0]}],
    point_cloud_type="lidar/beta",
)

with wandb.init() as run:
    run.log({"my_first_point_cloud": scene})

Pour vous déplacer dans un nuage de points depuis l’interface de l’application Weights & Biases, maintenez la touche Control enfoncée tout en déplaçant la souris.

Fichiers de nuages de points

Utilisez wandb.Object3D.from_file() pour charger des données de nuage de points depuis un fichier JSON :

run.log({"my_cloud_from_file": wandb.Object3D.from_file(
     "./my_point_cloud.pts.json"
)})

L’exemple JSON suivant illustre le format des données de nuage de points :

{
  "points": [
    [0.2, 0.3, 0.4, 255, 0, 0],
    [0.5, 0.6, 0.7, 0, 255, 0],
    [0.8, 0.9, 0.2, 0, 0, 255]
  ],
  "boxes": [
    {
      "corners": [
        [0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0],
        [0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]
      ],
      "color": [0, 0, 255],
      "label": "example region",
      "score": 0.6
    }
  ],
  "type": "lidar/beta"
}

Tableaux NumPy

Utilisez wandb.Object3D.from_numpy() avec l’un des formats de tableaux pris en charge :

# Coordonnées uniquement.
xyz_points = np.array([[0.4, 1, 1.3], [1, 1, 1], [1.2, 1, 1.2]])

# Coordonnées et étiquettes de catégorie.
category_points = np.array([[0.4, 1, 1.3, 1], [1, 1, 1, 1], [1.2, 1, 1.2, 12]])

# Coordonnées et couleurs RGB.
rgb_points = np.array([
    [0.4, 1, 1.3, 255, 0, 0],
    [1, 1, 1, 0, 255, 0],
    [1.2, 1, 1.2, 0, 0, 255],
])

with wandb.init() as run:
    run.log({
        "xyz_point_cloud": wandb.Object3D.from_numpy(xyz_points),
        "category_point_cloud": wandb.Object3D.from_numpy(category_points),
        "rgb_point_cloud": wandb.Object3D.from_numpy(rgb_points),
    })

Molécules

Utilisez wandb.Molecule pour journaliser des données moléculaires et examiner des structures 3D dans l’interface de l’application Weights & Biases.

run.log({"protein": wandb.Molecule("6lu7.pdb")})

Les types de fichiers pris en charge sont pdb, pqr, mmcif, mcif, cif, sdf, sd, gro, mol2 et mmtf. Vous pouvez également journaliser des chaînes SMILES, des fichiers mol RDKit et des objets rdkit.Chem.rdchem.Mol. Ces exemples nécessitent RDKit.

from rdkit import Chem

resveratrol = rdkit.Chem.MolFromSmiles("Oc1ccc(cc1)C=Cc1cc(O)cc(c1)O")

with wandb.init() as run:
    run.log(
        {
            "resveratrol": wandb.Molecule.from_rdkit(resveratrol),
            "green fluorescent protein": wandb.Molecule.from_rdkit("2b3p.mol"),
            "acetaminophen": wandb.Molecule.from_smiles("CC(=O)Nc1ccc(O)cc1"),
        }
    )

Pour un exemple interactif, consultez le workspace AlphaFold.

Vue 2D d’une molécule

Vous pouvez journaliser une vue 2D d’une molécule à l’aide du type de données wandb.Image et de rdkit :

from rdkit import Chem
from rdkit.Chem import AllChem, Draw

molecule = Chem.MolFromSmiles("CC(=O)O")
AllChem.Compute2DCoords(molecule)
pil_image = Draw.MolToImage(molecule, size=(300, 300))

with wandb.init() as run:
    run.log({"acetic_acid": wandb.Image(pil_image)})

Autres médias

Weights & Biases prend également en charge la journalisation de nombreux autres types de médias.

Audio

Utilisez wandb.Audio pour journaliser des données audio. Définissez sample_rate sur le taux d’échantillonnage de l’enregistrement, exprimé en hertz.

with wandb.init() as run:
    run.log({"whale songs": wandb.Audio(np_array, caption="OooOoo", sample_rate=32)})

Vous pouvez journaliser jusqu’à 100 clips audio par étape. Pour plus d’informations, voir audio-file.

Vidéo

Utilisez wandb.Video pour journaliser un fichier vidéo :

with wandb.init() as run:
    run.log({"video": wandb.Video("myvideo.mp4")})

Pour journaliser un tableau NumPy d’images vidéo, indiquez le format de sortie et la fréquence d’images :

with wandb.init() as run:
    run.log({"video": wandb.Video(video_array, fps=4, format="gif")})

Utilisez la forme (frames, channels, height, width) pour une seule vidéo ou (batch, frames, channels, height, width) pour un lot. L’encodage de tableaux NumPy nécessite FFmpeg et MoviePy. Les formats pris en charge sont "gif", "mp4", "webm" et "ogg". Si vous transmettez un tableau ou un flux en mémoire, spécifiez format. Pour l’encodage d’images brutes, la fréquence d’images par défaut est de 4 images par seconde. Si vous fournissez un chemin de fichier, Weights & Biases vérifie que le fichier existe et que son format est pris en charge. Si vous fournissez un objet BytesIO, Weights & Biases crée un fichier temporaire dont l’extension correspond au format spécifié. Pour afficher et lire des vidéos, ouvrez un volet multimédia dans le Workspace de votre projet, dans le workspace de votre run ou dans votre rapport. Utilisez le mode de comparaison pour comparer des vidéos entre plusieurs runs ou étapes.

Texte

Utilisez wandb.Table pour afficher du texte à côté de prédictions, d’étiquettes ou d’autres valeurs. Indiquez les noms des colonnes lors de la création du tableau. Par défaut, les en-têtes de colonne sont ["Input", "Output", "Expected"]. Pour garantir des performances optimales de l’interface utilisateur, le nombre maximum de lignes est fixé par défaut à 10 000. Vous pouvez toutefois redéfinir explicitement ce maximum avec wandb.Table.MAX_ROWS = {DESIRED_MAX}.

columns = ["Text", "Predicted Sentiment", "True Sentiment"]
data = [["I love my phone", "1", "1"], ["My phone is terrible", "0", "-1"]]

with wandb.init(project="my_project") as run:
    table = wandb.Table(data=data, columns=columns)
    run.log({"examples": table})

Vous pouvez également ajouter des lignes avec wandb.Table.add_data() :

table = wandb.Table(columns=columns)
table.add_data("I love my phone", "positive", "positive")
table.add_data("My phone stopped working", "negative", "negative")
run.log({"text_examples": table})

Pour créer un tableau à partir d’un DataFrame pandas, passez-le à dataframe :

table = wandb.Table(dataframe=my_dataframe)
with wandb.init() as run:
    run.log({"examples": table})

Pour en savoir plus sur l’utilisation, consultez string.

HTML

Utilisez wandb.Html pour afficher du HTML personnalisé dans un panneau de la page du run. Passez un fichier HTML ou une chaîne de caractères :

with wandb.init() as run:
    run.log({"custom_string": wandb.Html('<a href="https://mysite">Link</a>')})
    
    with open("some.html") as f:
        run.log({"custom_file": wandb.Html(f)})

Par défaut, Weights & Biases ajoute des styles au HTML. Pour désactiver ce comportement, passez inject=False. Pour désactiver ce comportement, passez inject=False :

with wandb.init() as run:
    with open("some.html") as html_file:
        run.log({"custom_file": wandb.Html(html_file, inject=False)})

Pour plus d’informations sur l’utilisation, consultez html-file.

Weights & Biases

Guides

Intégrations

Référence

Assistance

Journaliser des médias et des objets

Prérequis

Images

Superpositions d’images

Superpositions sur les images dans les Tables

Histogrammes

Visualisations 3D

Formats de tableaux NumPy

Objet Python

Fichiers de nuages de points

Tableaux NumPy

Molécules

Vue 2D d’une molécule

Autres médias

Audio

Vidéo

Texte

HTML

​Prérequis

​Images

​Superpositions d’images

​Superpositions sur les images dans les Tables

​Histogrammes

​Visualisations 3D

​Formats de tableaux NumPy

​Objet Python

​Fichiers de nuages de points

​Tableaux NumPy

​Molécules

​Vue 2D d’une molécule

​Autres médias

​Audio

​Vidéo

​Texte

​HTML

Prérequis

Images

Superpositions d’images

Superpositions sur les images dans les Tables

Histogrammes

Visualisations 3D

Formats de tableaux NumPy

Objet Python

Fichiers de nuages de points

Tableaux NumPy

Molécules

Vue 2D d’une molécule

Autres médias

Audio

Vidéo

Texte

HTML