Gérer les entrées des jobs

Gérez et configurez par programmation les entrées des jobs, comme les hyperparamètres et les configurations basées sur des fichiers, pour les jobs W&B Launch.

L’expérience centrale de Launch consiste à tester différentes entrées du job, comme des hyperparamètres et des jeux de données, puis à acheminer ces jobs vers le matériel approprié. Après avoir créé un job, des utilisateurs autres que l’auteur original peuvent ajuster ces entrées via l’interface utilisateur W&B ou le CLI. Pour savoir comment définir les entrées d’un job lors du lancement depuis le CLI ou l’interface utilisateur, voir le guide Mettre des jobs en file d’attente.

Ce guide explique comment contrôler par programmation quelles entrées vous pouvez ajuster pour un job, afin de n’exposer que les paramètres que vous souhaitez permettre aux utilisateurs finaux de modifier. Par défaut, les jobs W&B capturent l’intégralité de Run.config comme entrées du job, mais le SDK Launch fournit une fonction pour contrôler certaines clés de la configuration du run ou pour spécifier des fichiers JSON ou YAML comme entrées.

Les fonctions du SDK Launch nécessitent wandb-core. Pour plus d’informations, voir le fichier wandb-core README.

​

Reconfigurer l’objet Run

Par défaut, vous pouvez reconfigurer l’objet Run renvoyé par wandb.init() dans un job. Utilisez le SDK Launch pour personnaliser les parties de l’objet Run.config que vous pouvez reconfigurer au lancement du job, afin de masquer les paramètres internes tout en exposant les paramètres importants pour les utilisateurs finaux.

import wandb
from wandb.sdk import launch

# Requis pour l'utilisation du SDK Launch.
wandb.require("core")

config = {
    "trainer": {
        "learning_rate": 0.01,
        "batch_size": 32,
        "model": "resnet",
        "dataset": "cifar10",
        "private": {
            "key": "value",
        },
    },
    "seed": 42,
}


with wandb.init(config=config):
    launch.manage_wandb_config(
        include=["trainer"], 
        exclude=["trainer.private"],
    )
    # Etc.

La fonction launch.manage_wandb_config() configure le job pour qu’il accepte des valeurs d’entrée pour l’objet Run.config. Les options facultatives include et exclude prennent des préfixes de chemin au sein de l’objet de configuration imbriqué. C’est utile si, par exemple, un job utilise une bibliothèque dont vous ne souhaitez pas exposer les options aux utilisateurs finaux.

Si vous fournissez des préfixes include, seuls les chemins de la configuration qui correspondent à un préfixe include acceptent des valeurs d’entrée. Si vous fournissez des préfixes exclude, les chemins correspondant à la liste exclude sont exclus des valeurs d’entrée. Si un chemin correspond à la fois à un préfixe include et à un préfixe exclude, le préfixe exclude est prioritaire.

Dans l’exemple précédent, le chemin ["trainer.private"] exclut la clé private de l’objet trainer, et le chemin ["trainer"] exclut toutes les clés qui ne se trouvent pas sous l’objet trainer.

Utilisez un . précédé d’un caractère d’échappement \ pour exclure les clés dont le nom contient un ..

Par exemple, r"trainer\.private" exclut la clé trainer.private plutôt que la clé private sous l’objet trainer.

Le préfixe r dans l’exemple précédent désigne une chaîne brute.

Si vous empaquetez et exécutez le code précédent comme un job, les types d’entrée du job sont :

{
    "trainer": {
        "learning_rate": "float",
        "batch_size": "int",
        "model": "str",
        "dataset": "str",
    },
}

Lors du lancement du job depuis le CLI ou l’interface utilisateur W&B, vous ne pouvez modifier que les quatre paramètres trainer.

​

Accéder aux entrées de configuration du run

Les jobs lancés avec des entrées de configuration du run peuvent accéder à leurs valeurs via Run.config. Le Run renvoyé par wandb.init() dans le code du job a automatiquement les valeurs des entrées définies. Pour charger les valeurs d’entrée de la configuration du run à n’importe quel endroit dans le code du job, utilisez launch.load_wandb_config() :

from wandb.sdk import launch

run_config_overrides = launch.load_wandb_config()

​

Reconfigurer un fichier

Le SDK Launch peut également gérer les valeurs d’entrée stockées dans des fichiers de configuration au sein du code du job. Il s’agit d’une pratique courante dans de nombreux cas d’usage en deep learning et avec les grands modèles de langage, comme dans cet exemple torchtune ou cette configuration Axolotl.

Sweeps on Launch ne prend pas en charge l’utilisation d’entrées du fichier de configuration comme paramètres de balayage. Les paramètres de balayage doivent être contrôlés via l’objet Run.config.

Utilisez la fonction launch.manage_config_file() pour ajouter un fichier de configuration comme entrée du job Launch, ce qui vous permet de modifier les valeurs qu’il contient au moment de lancer le job.

Par défaut, aucune entrée de configuration du run n’est capturée si vous utilisez launch.manage_config_file(). L’appel à launch.manage_wandb_config() remplace ce comportement.

Prenez l’exemple suivant :

import yaml
import wandb
from wandb.sdk import launch

# Requis pour l'utilisation du SDK Launch.
wandb.require("core")

launch.manage_config_file("config.yaml")

with open("config.yaml", "r") as f:
    config = yaml.safe_load(f)

with wandb.init(config=config):
    # Etc.
    pass

Imaginez que vous exécutiez le code avec un fichier config.yaml situé dans le même répertoire :

learning_rate: 0.01
batch_size: 32
model: resnet
dataset: cifar10

L’appel à launch.manage_config_file() ajoute le fichier config.yaml comme entrée du job, ce qui le rend reconfigurable lors d’un lancement depuis la CLI ou l’interface utilisateur de W&B.

Utilisez les arguments nommés include et exclude pour filtrer les clés d’entrée acceptées du fichier de configuration, de la même manière que launch.manage_wandb_config().

​

Accéder aux entrées du fichier de configuration

Lorsque vous appelez launch.manage_config_file() dans un run créé par Launch, launch met à jour le contenu du fichier de configuration avec les valeurs d’entrée. Le fichier de configuration mis à jour est disponible dans l’environnement du job.

Appelez launch.manage_config_file() avant de lire le fichier de configuration dans le code du job pour vous assurer que les valeurs d’entrée sont utilisées.

​

Personnaliser l’interface du volet de lancement d’un job

Au-delà du filtrage des entrées que vous exposez, vous pouvez définir un schéma pour les entrées d’un job afin de créer une interface personnalisée pour lancer ce job. Cela affiche des champs structurés, des indications de validation et des listes déroulantes dans le volet de lancement au lieu d’un champ de texte libre. Pour définir le schéma d’un job, incluez-le dans l’appel à launch.manage_wandb_config() ou launch.manage_config_file(). Le schéma peut être soit un dict Python au format JSON Schema, soit une classe de modèle Pydantic.

Les schémas d’entrée du job ne valident pas les entrées. Ils définissent uniquement l’interface dans le volet de lancement.

Schéma JSON

L’exemple suivant montre un schéma avec les propriétés suivantes :

• seed, un entier.
• trainer, un dictionnaire avec certaines clés spécifiées :
  • trainer.learning_rate, un flottant qui doit être supérieur à zéro.
  • trainer.batch_size, un entier qui doit être égal à 16, 64 ou 256.
  • trainer.dataset, une chaîne qui doit être soit cifar10, soit cifar100.

schema = {
    "type": "object",
    "properties": {
        "seed": {
          "type": "integer"
        }
        "trainer": {
            "type": "object",
            "properties": {
                "learning_rate": {
                    "type": "number",
                    "description": "Learning rate of the model",
                    "exclusiveMinimum": 0,
                },
                "batch_size": {
                    "type": "integer",
                    "description": "Number of samples per batch",
                    "enum": [16, 64, 256]
                },
                "dataset": {
                    "type": "string",
                    "description": "Name of the dataset to use",
                    "enum": ["cifar10", "cifar100"]
                }
            }
        }
    }
}

launch.manage_wandb_config(
    include=["seed", "trainer"], 
    exclude=["trainer.private"],
    schema=schema,
)

De manière générale, les attributs JSON Schema suivants sont pris en charge :

Attribut	Requis	Notes
type	Oui	Doit être l’un de number, integer, string ou object
title	Non	Remplace le nom d’affichage de la propriété
description	Non	Fournit le texte d’aide de la propriété
enum	Non	Crée une liste déroulante au lieu d’un champ de texte libre
minimum	Non	Autorisé uniquement si type vaut number ou integer
maximum	Non	Autorisé uniquement si type vaut number ou integer
exclusiveMinimum	Non	Autorisé uniquement si type vaut number ou integer
exclusiveMaximum	Non	Autorisé uniquement si type vaut number ou integer
properties	Non	Si type vaut object, définit des configurations imbriquées

Modèle Pydantic

L’exemple suivant montre un schéma avec les propriétés suivantes :

• seed, un entier.
• trainer, un schéma avec certains sous-attributs spécifiés :
  • trainer.learning_rate, un flottant qui doit être supérieur à zéro.
  • trainer.batch_size, un entier qui doit être compris entre 1 et 256, bornes incluses.
  • trainer.dataset, une chaîne qui doit être soit cifar10, soit cifar100.

class DatasetEnum(str, Enum):
    cifar10 = "cifar10"
    cifar100 = "cifar100"

class Trainer(BaseModel):
    learning_rate: float = Field(gt=0, description="Learning rate of the model")
    batch_size: int = Field(ge=1, le=256, description="Number of samples per batch")
    dataset: DatasetEnum = Field(title="Dataset", description="Name of the dataset to use")

class Schema(BaseModel):
    seed: int
    trainer: Trainer

launch.manage_wandb_config(
    include=["seed", "trainer"],
    exclude=["trainer.private"],
    schema=Schema,
)

Vous pouvez également utiliser une instance de la classe :

t = Trainer(learning_rate=0.01, batch_size=32, dataset=DatasetEnum.cifar10)
s = Schema(seed=42, trainer=t)
launch.manage_wandb_config(
    include=["seed", "trainer"],
    exclude=["trainer.private"],
    input_schema=s,
)

L’ajout d’un schéma d’entrée du job crée un formulaire structuré dans le volet de lancement pour les utilisateurs qui lancent le job.