Sessions

Ce guide explique comment utiliser Session pour gérer plusieurs bacs à sable avec une configuration partagée. Il s’adresse aux développeurs côté client qui doivent coordonner des groupes de bacs à sable, appliquer des valeurs par défaut communes et garantir un nettoyage cohérent à l’échelle d’une charge de travail.

Choisir l’authentification

Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section indique CKS. Choisissez l’identifiant d’authentification du compte propriétaire de vos sandboxes. Pour obtenir une clé ou un jeton, consultez Choisir et obtenir des identifiants d’authentification. Exécutez les commandes d’installation dans un environnement virtuel Python actif. Enregistrez le code Python de l’onglet correspondant à votre identifiant d’authentification sous le nom sandbox_auth.py, dans le même répertoire que les scripts Python que vous exécutez à partir de cette page. Ce fichier enregistre le mode d’authentification choisi, et non votre identifiant d’authentification. Les exemples importent AUTH depuis ce fichier et le transmettent explicitement à chaque nouvelle sandbox ou session.

Clé API Forge
Jeton d’accès à l’API CoreWeave

Utilisez votre clé API Forge avec la stratégie d’authentification W&B du SDK :

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Utilisez le jeton de votre organisation CoreWeave :

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

Pour un placement sur CKS, choisissez le jeton CoreWeave, activez un exécuteur et définissez placement_mode="cks" lors de la création de la sandbox ou dans SandboxDefaults. Une session créée avec auth=AUTH authentifie également les sandboxes qui lui appartiennent. Utilisez le même identifiant d’authentification pour vous reconnecter à vos sandboxes, les lister ou les nettoyer.

Aperçu de la session

Une Session fournit :

Une configuration par défaut commune à tous les bacs à sable.
Un nettoyage automatique à la fermeture de la session.
Une portée pour le décorateur @session.function().

Utilisation de base

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

# Définir une configuration partagée
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("project-alpha",),
    resources={"cpu": "1", "memory": "1Gi"},
)

# Créer une session à l’aide d’un gestionnaire de contexte
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Créer des bacs à sable via la session
    sb1 = session.sandbox()
    sb2 = session.sandbox()

    # Utiliser les bacs à sable
    result1 = sb1.exec(["echo", "sandbox 1"]).result()
    result2 = sb2.exec(["echo", "sandbox 2"]).result()

# Tous les bacs à sable sont automatiquement arrêtés à la sortie du contexte

Créer des bacs à sable

Les sections suivantes expliquent comment créer des bacs à sable à partir d’une session et comment remplacer les valeurs par défaut de la session.

session.sandbox()

Crée une sandbox avec les valeurs par défaut de la session. La sandbox ne démarre qu’à sa première utilisation :

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # sandbox() renvoie une sandbox non démarrée
    sandbox = session.sandbox()

    # Toute opération démarre automatiquement la sandbox à la première utilisation
    result = sandbox.exec(["echo", "hello"]).result()

Pour contrôler explicitement le moment où le RPC de démarrage est déclenché :

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    sandbox = session.sandbox()
    sandbox.start().result()  # Démarrage explicite
    sandbox.wait()            # Attendre la fin du démarrage ou de l’exécution
    if sandbox.status != cwsandbox.SandboxStatus.RUNNING:
        raise RuntimeError(f"Sandbox is not running: {sandbox.status}")
    result = sandbox.exec(["echo", "hello"]).result()

Remplacer les valeurs par défaut

Transmettez des arguments supplémentaires pour remplacer les valeurs par défaut de la session. L’exemple sans serveur suivant configure une sandbox GPU à démarrage différé, dont les demandes de ressources en CPU et en mémoire sont égales à leurs limites respectives. Pour la démarrer, appelez gpu_sandbox.start().result() ou exécutez une commande avant de quitter la session.

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import ResourceOptions, SandboxDefaults

# Session avec la configuration de base
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project",),
    resources={"cpu": "1", "memory": "1Gi"},
)

with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Remplacer l’image et les ressources pour cette sandbox
    gpu_sandbox = session.sandbox(
        command="sleep",
        args=["infinity"],
        container_image="pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime",
        resources=ResourceOptions(
            requests={"cpu": "4", "memory": "16Gi"},
            limits={"cpu": "4", "memory": "16Gi"},
            gpu={"count": 1},
        ),
        tags=["gpu-workload"],  # Fusionnés avec les tags de la session
    )

Consultez le guide de configuration du bac à sable pour connaître toutes les options disponibles.

Gestion de sandboxes multiples

Les sessions se prêtent bien à la gestion de pools de sandboxes :

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Créer un pool de bacs à sable
    sandboxes = [
        session.sandbox()
        for _ in range(5)
    ]

    # Répartir le travail entre les sandboxes du pool
    processes = [
        sb.exec(["python", "-c", f"print({i})"])
        for i, sb in enumerate(sandboxes)
    ]

    # Collecter les résultats
    results = [p.result() for p in processes]

# Les 5 bacs à sable sont nettoyés automatiquement

Pour préparer des bacs à sable avant l’arrivée des requêtes, voir Implement a warm pool. La recette maintient une réserve de bacs à sable prêts, attribue à chaque charge de travail un sandbox distinct et réalimente la réserve à mesure que les charges de travail les prennent.

Cycle de vie de la session

Les sections suivantes expliquent comment fermer une session, ce que fait close() et comment gérer les erreurs.

Fermeture manuelle

Si vous n’utilisez pas de gestionnaire de contexte, fermez explicitement la session :

from sandbox_auth import AUTH
session = cwsandbox.Session(defaults=defaults, auth=AUTH)

sandbox = session.sandbox()
result = sandbox.exec(["echo", "hello"]).result()

# Fermer la session (arrête toutes les sandboxes)
session.close().result()

Ce que fait close()

L’appel à close() lance l’arrêt de tous les Sandbox créés via la session ou adoptés par celle-ci, et renvoie immédiatement un OperationRef[None]. Appelez session.close().result() pour attendre la fin du nettoyage.

Gestion des erreurs

Les sessions sont nettoyées même si des exceptions se produisent :

from sandbox_auth import AUTH
with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    sandbox = session.sandbox()
    raise RuntimeError("Something went wrong!")
# Le sandbox est tout de même nettoyé

Adopter des bacs à sable externes

Confiez à la session la gestion des bacs à sable créés en dehors de celle-ci :

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import Sandbox

with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    # Trouver les sandboxes existants
    existing = Sandbox.list(tags=["orphaned-work"], auth=AUTH).result()

    # Les adopter pour qu'ils soient nettoyés
    for sandbox in existing:
        session.adopt(sandbox)

    # session.close() les nettoiera désormais eux aussi

Propriétés de Session

Consultez l’état de la session grâce aux propriétés intégrées, telles que sandbox_count :

from sandbox_auth import AUTH
session = cwsandbox.Session(defaults=defaults, auth=AUTH)

# Nombre de bacs à sable suivis
print(session.sandbox_count)  # 0

sandbox = session.sandbox()
print(session.sandbox_count)  # 1

Quand utiliser les sessions

Cas d’utilisation	Approche recommandée
Sandbox unique, tâche simple	`Sandbox.run()` avec un gestionnaire de contexte
Plusieurs bacs à sable, configuration partagée	Session
API de décorateurs de fonctions	Session requise
Pool de workers	Session
Commande ponctuelle	Appel direct à `Sandbox.run()`

Sans sessions

Les sessions ne sont pas nécessaires pour une Sandbox unique :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

# Utilisation directe sans session
with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# Nettoyage géré par le gestionnaire de contexte

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Choisir l’authentification

Aperçu de la session

Utilisation de base

Créer des bacs à sable

session.sandbox()

Remplacer les valeurs par défaut

Gestion de sandboxes multiples

Cycle de vie de la session

Fermeture manuelle

Ce que fait close()

Gestion des erreurs

Adopter des bacs à sable externes

Propriétés de Session

Quand utiliser les sessions

Sans sessions

​Choisir l’authentification

​Aperçu de la session

​Utilisation de base

​Créer des bacs à sable

​session.sandbox()

​Remplacer les valeurs par défaut

​Gestion de sandboxes multiples

​Cycle de vie de la session

​Fermeture manuelle

​Ce que fait close()

​Gestion des erreurs

​Adopter des bacs à sable externes

​Propriétés de Session

​Quand utiliser les sessions

​Sans sessions

Choisir l’authentification

Aperçu de la session

Utilisation de base

Créer des bacs à sable

session.sandbox()

Remplacer les valeurs par défaut

Gestion de sandboxes multiples

Cycle de vie de la session

Fermeture manuelle

Ce que fait close()

Gestion des erreurs

Adopter des bacs à sable externes

Propriétés de Session

Quand utiliser les sessions

Sans sessions