Gérer les entrées des jobs

Launch repose avant tout sur l’expérimentation avec différentes entrées de jobs, telles que les hyperparamètres et les datasets, et sur l’acheminement de ces jobs vers le matériel approprié. Une fois un job créé, d’autres utilisateurs que son auteur d’origine peuvent ajuster ces entrées via l’interface W&B ou la CLI. Pour savoir comment définir les entrées d’un job lors d’un lancement depuis la CLI ou l’interface, consultez le guide Mettre des jobs en file d’attente. Ce guide explique comment contrôler par programmation les entrées modifiables d’un job, afin de n’exposer que les paramètres que vous souhaitez rendre modifiables par les utilisateurs finaux. 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 permettant de contrôler certaines clés de la configuration de run ou de définir des fichiers JSON ou YAML comme entrées.

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

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 choisir les parties de l’objet Run.config qui peuvent être reconfigurées au lancement du job. Vous pouvez ainsi masquer les paramètres internes et n’exposer que ceux qui sont utiles aux utilisateurs finaux.

import wandb
from wandb.sdk import launch

# Requis pour utiliser le 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 acceptent 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 qui correspondent à 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 situées en dehors de l’objet trainer.

Pour exclure des clés dont le nom contient un ., échappez ce . avec \.Par exemple, r"trainer\.private" exclut la clé trainer.private, et non la clé private de l’objet trainer.Dans l’exemple précédent, le préfixe r désigne une chaîne brute.

Si vous empaquetez et exécutez le code précédent en tant que job, les types d’entrée du job sont les suivants :

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

Lorsque vous lancez le job depuis la CLI ou l’interface utilisateur de W&B, seuls les quatre paramètres trainer peuvent être redéfinis.

Accéder aux entrées de configuration de run

Les jobs lancés avec des entrées de configuration de run peuvent accéder aux valeurs d’entrée via Run.config. Le Run renvoyé par wandb.init() dans le code du job contient automatiquement les valeurs d’entrée. Pour charger les valeurs d’entrée de la configuration de run n’importe où 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’un schéma courant dans de nombreux cas d’usage d’apprentissage profond et de grands modèles de langage, comme cet exemple torchtune ou cette configuration Axolotl.

Sweeps on Launch ne permet pas d’utiliser les entrées du fichier de configuration comme paramètres de sweep. Les paramètres de sweep 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. Vous pourrez ainsi modifier les valeurs de ce fichier de configuration au lancement du job. Par défaut, aucune entrée de la configuration de run n’est capturée si vous utilisez launch.manage_config_file(). Appeler launch.manage_wandb_config() redéfinit ce comportement. Prenons l’exemple suivant :

import yaml
import wandb
from wandb.sdk import launch

# Requis pour utiliser le 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

Supposons 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 permet de le reconfigurer lors d’un lancement depuis la CLI ou l’interface W&B. Utilisez les arguments nommés include et exclude pour filtrer les clés d’entrée acceptées dans le fichier de configuration, comme avec 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 patche le contenu du fichier de configuration avec les valeurs d’entrée. Le fichier de configuration ainsi patché est disponible dans l’environnement du job.

Appelez launch.manage_config_file() avant de lire le fichier de configuration dans le code du job, afin que les valeurs d’entrée soient bien prises en compte.

Personnaliser l’interface du volet latéral de lancement d’un job

En plus de filtrer les 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 de lancement personnalisée. Le volet latéral de lancement affiche alors des champs structurés, des indications de validation et des listes déroulantes au lieu d’une saisie 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 schéma JSON, soit une classe de modèle Pydantic.

Les schémas d’entrée des jobs ne valident pas les entrées. Ils définissent uniquement l’interface du volet latéral de lancement.

Schéma JSON
Modèle Pydantic

L’exemple suivant présente un schéma doté des propriétés suivantes :

seed, un entier.
trainer, un dictionnaire dont certaines clés sont spécifiées :
- trainer.learning_rate, un nombre à virgule flottante strictement supérieur à zéro.
- trainer.batch_size, un entier qui doit valoir 16, 64 ou 256.
- trainer.dataset, une chaîne qui doit valoir cifar10 ou 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 de schéma JSON suivants sont pris en charge :

Attribut	Requis	Remarques
`type`	Oui	Doit être `number`, `integer`, `string` ou `object`
`title`	Non	Remplace le nom d’affichage de la propriété
`description`	Non	Fournit un texte d’aide pour la propriété
`enum`	Non	Crée une liste déroulante au lieu d’une saisie 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

L’exemple suivant présente un schéma doté des propriétés suivantes :

seed, un entier.
trainer, un schéma dont certains sous-attributs sont spécifiés :
- trainer.learning_rate, un nombre à virgule flottante strictement supérieur à zéro.
- trainer.batch_size, un entier compris entre 1 et 256 inclus.
- trainer.dataset, une chaîne qui doit valoir cifar10 ou 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 à un job génère un formulaire structuré dans le volet latéral de lancement, à l’intention des utilisateurs qui lancent le job.

​Reconfigurer l’objet Run

​Accéder aux entrées de configuration de run

​Reconfigurer un fichier

​Accéder aux entrées du fichier de configuration

​Personnaliser l’interface du volet latéral de lancement d’un job

Reconfigurer l’objet `Run`

Accéder aux entrées de configuration de run

Reconfigurer un fichier

Accéder aux entrées du fichier de configuration

Personnaliser l’interface du volet latéral de lancement d’un job