Sessions

Ces exemples utilisent un jeton d’accès à l’API CoreWeave défini dans CWSANDBOX_API_KEY. Pour l’authentification par clé API Forge, consultez Premiers pas. Pour connaître les exigences relatives à CKS, consultez Modes de placement. 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.

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

import cwsandbox
from cwsandbox import SandboxDefaults

# Définir une configuration partagée
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("project-alpha",),
)

# Créer une session à l’aide d’un gestionnaire de contexte
with cwsandbox.Session(defaults=defaults) 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 :

with cwsandbox.Session(defaults=defaults) 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é :

with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    sandbox.start().result()  # Démarrage explicite
    sandbox.wait()            # Attendre l’état RUNNING
    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 :

from cwsandbox import ResourceOptions

# Session avec la configuration de base
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project",),
)

with cwsandbox.Session(defaults=defaults) as session:
    # Remplacer l’image et les ressources pour cette sandbox
    gpu_sandbox = session.sandbox(
        command="sleep",
        args=["infinity"],
        container_image="pytorch/pytorch:latest",
        resources=ResourceOptions(
            requests={"cpu": "4", "memory": "16Gi"},
            limits={"cpu": "8", "memory": "32Gi"},
            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 :

with cwsandbox.Session(defaults=defaults) 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 :

session = cwsandbox.Session(defaults=defaults)

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() effectue les actions suivantes :

Arrête tous les bacs à sable créés via la session ou adoptés par celle-ci.
Attend la fin du nettoyage.
Renvoie OperationRef[None].

Gestion des erreurs

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

with cwsandbox.Session(defaults=defaults) 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 :

import cwsandbox
from cwsandbox import Sandbox

with cwsandbox.Session(defaults=defaults) as session:
    # Trouver les sandboxes existants
    existing = Sandbox.list(tags=["orphaned-work"]).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 :

session = cwsandbox.Session(defaults=defaults)

# 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 cwsandbox import Sandbox

# Utilisation directe sans session
with Sandbox.run() 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

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

​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

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