Cycle de vie d’un sandbox - Weights & Biases Documentation

wandb.sandbox est obsolète et sera supprimé dans une prochaine version du SDK Python W&B. Utilisez plutôt le package cwsandbox, décrit dans la documentation des sandboxes CoreWeave.La migration implique deux changements :

L’import. Installez cwsandbox avec l’extra W&B (pip install "cwsandbox[wandb]") et importez depuis cwsandbox au lieu de wandb.sandbox.
L’identifiant d’authentification. Par défaut, cwsandbox s’authentifie avec un CoreWeave API access token défini dans CWSANDBOX_API_KEY ; passez donc auth=AuthStrategy.WANDB pour continuer à utiliser votre clé API W&B. Voir Choose a credential.

Les exemples de cette page utilisent encore wandb.sandbox. Pour le code cwsandbox équivalent, voir Migrer vers cwsandbox.

Serverless Sandboxes est en préversion publique. L’accès est activé pour chaque organisation. Pour demander l’accès pour votre organisation, contactez l’assistance.

Cette page décrit le cycle de vie d’un Serverless Sandbox afin de vous aider à choisir la bonne méthode pour attendre les changements d’état, arrêter un sandbox et structurer votre code en fonction de sa durée de vie. Comprendre ce cycle de vie vous aide à éviter les conditions de concurrence, à distinguer les échecs au démarrage des erreurs d’exécution et à nettoyer les ressources de manière prévisible. Un Serverless Sandbox W&B passe par plusieurs états au cours de son cycle de vie. L’état du sandbox détermine les opérations disponibles. En général, un sandbox démarre dans l’état PENDING, passe à CREATING pendant l’approvisionnement du conteneur, puis entre dans l’état RUNNING lorsqu’il est prêt à être utilisé. Si vous démarrez un sandbox avec une commande principale, cette commande devient le processus principal du sandbox. Lorsque le processus principal se termine, le sandbox entre dans un état terminal tel que COMPLETED (code de sortie 0) ou FAILED (erreur au démarrage ou pendant l’exécution). Un sandbox peut également entrer dans l’état TERMINATED s’il est arrêté de l’extérieur ou dépasse sa durée de vie maximale.

PENDING -> CREATING -> RUNNING -> COMPLETED
                               -> FAILED
                               -> TERMINATED

Les sections suivantes décrivent les états des sandboxes, comment attendre qu’un sandbox soit prêt ou qu’il se termine, et comment arrêter un sandbox. Pour en savoir plus sur la création de sandboxes et l’exécution de commandes, voir Créer des sandboxes et Exécuter des commandes.

États du sandbox

Le tableau suivant récapitule les états d’un sandbox :

État	Description
`PENDING`	La requête de création du sandbox a été acceptée et attend d’être planifiée.
`CREATING`	Le conteneur est en cours de provisionnement.
`RUNNING`	Le sandbox est prêt pour les opérations.
`COMPLETED`	Le processus principal s’est terminé normalement avec le code `0`.
`FAILED`	Le sandbox ou son processus principal a rencontré une erreur au démarrage ou pendant l’exécution.
`TERMINATED`	Un processus externe a arrêté le sandbox, ou celui-ci s’est terminé parce qu’il a dépassé sa durée de vie maximale.

La plupart des opérations exigent que le sandbox soit à l’état RUNNING. Cependant, de nombreuses opérations attendent que le sandbox soit prêt avant de continuer. Une fois qu’un sandbox entre dans un état terminal, il n’est plus disponible pour des opérations supplémentaires.

Attendre que le sandbox soit prêt ou terminé

Les sections suivantes décrivent les deux méthodes permettant d’attendre les changements d’état du sandbox et précisent quand utiliser chacune d’elles. Utilisez différentes méthodes d’attente en fonction de vos besoins :

Utilisez Sandbox.wait() pour attendre que le sandbox soit prêt à l’emploi.
Utilisez Sandbox.wait_until_complete() pour attendre la fin du processus principal du sandbox.

Attendre qu’un sandbox démarre

Utilisez Sandbox.wait() pour attendre explicitement que le sandbox atteigne l’état RUNNING. Cette méthode est utile pour diagnostiquer les problèmes de démarrage ou lorsque vous souhaitez distinguer les échecs de démarrage des erreurs survenant dans des commandes ultérieures. Par exemple, le code suivant crée un sandbox, attend qu’il soit prêt, puis exécute une commande :

import wandb
from wandb.sandbox import Sandbox

with Sandbox.run() as sandbox:
    sandbox.wait()  # bloquer jusqu'à ce que le sandbox soit en cours d'exécution
    result = sandbox.exec(["python", "-c", "print('hello from sandbox')"]).result()
    print(result.stdout)

Attendre la fin d’un sandbox

Utilisez Sandbox.wait_until_complete() lorsque le processus principal du sandbox représente l’intégralité de la charge de travail et que vous souhaitez attendre la fin de cette tâche.

from wandb.sandbox import Sandbox

sandbox = Sandbox.run("python", "train.py")
sandbox.wait_until_complete(timeout=3600.0).result()  # bloque jusqu'à ce que le processus principal se termine ou que le délai expire
print(f"Exit code: {sandbox.returncode}")

Ce schéma est utile lorsque vous démarrez un sandbox avec une commande principale telle que Sandbox.run("python", "train.py") et souhaitez que le cycle de vie du sandbox corresponde à l’exécution de cette commande. Lorsque le processus principal se termine, le sandbox passe à un état terminal. Une exécution réussie se termine généralement par COMPLETED. Si le processus échoue, le sandbox peut passer à FAILED. Si vous devez plutôt exécuter des commandes de manière interactive, utilisez un gestionnaire de contexte avec Sandbox.exec() :

from wandb.sandbox import Sandbox

with Sandbox.run() as sandbox:
    result = sandbox.exec(["python", "train.py"]).result()
    print(result.stdout)
# sandbox arrêté automatiquement à la sortie

Contrôle explicite du cycle de vie

Utilisez des méthodes telles que Sandbox.wait() et Sandbox.stop() lorsque vous avez besoin de contrôler explicitement le cycle de vie du sandbox. En général, vous n’avez pas besoin d’appeler ces méthodes directement. Des opérations telles que Sandbox.exec(), Sandbox.read_file() et Sandbox.write_file() attendent que le sandbox soit prêt, et le gestionnaire de contexte (with Sandbox.run() as sandbox:) arrête le sandbox à la fin du bloc.

Arrêter le sandbox

Utilisez Sandbox.stop() lorsque vous n’avez plus besoin du sandbox, pour mettre fin à un processus de longue durée ou pour libérer des ressources avant que le sandbox n’atteigne sa durée de vie maximale.

from wandb.sandbox import Sandbox

sandbox = Sandbox.run("sleep", "infinity")

# ... utiliser le sandbox ...

sandbox.stop().result()

Vous pouvez également contrôler le comportement lors de l’arrêt avec des options supplémentaires :

from wandb.sandbox import Sandbox

with Sandbox.run("sleep", "infinity") as sandbox:
    sandbox.stop(
        graceful_shutdown_seconds=30.0,  # Attendre avant de forcer l'arrêt du sandbox.
        missing_ok=True,                 # Ne pas lever d'erreur si le sandbox est déjà arrêté.
    ).result()

​États du sandbox

​Attendre que le sandbox soit prêt ou terminé

​Attendre qu’un sandbox démarre

​Attendre la fin d’un sandbox

​Contrôle explicite du cycle de vie

​Arrêter le sandbox

États du sandbox

Attendre que le sandbox soit prêt ou terminé

Attendre qu’un sandbox démarre

Attendre la fin d’un sandbox

Contrôle explicite du cycle de vie

Arrêter le sandbox