Skip to main content
Ce guide présente les options de configuration de la sandbox, notamment les ressources, les fichiers montés, les ports, les annotations et les délais d’expiration. Servez-vous-en comme référence pour adapter l’environnement d’exécution d’une sandbox aux exigences d’une charge de travail, par exemple pour réserver de la capacité GPU, exposer un service ou définir des délais d’expiration pour les opérations. Cette page s’adresse aux développeurs qui utilisent le SDK Python cwsandbox pour lancer et gérer des Sandbox.

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 Sandbox. 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 depuis 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.
Utilisez votre clé API Forge avec la stratégie d’authentification W&B du SDK :
sandbox_auth.py
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. Lorsque vous créez une session avec auth=AUTH, les Sandbox qui lui appartiennent sont également authentifiées. Utilisez le même identifiant d’authentification pour vous reconnecter à vos Sandbox, les lister ou les nettoyer.

Aperçu

Vous pouvez définir la configuration de la sandbox à trois niveaux, présentés de la portée la plus large à la plus spécifique :
  • SandboxDefaults : valeurs par défaut partagées par toutes les Sandbox d’une session.
  • Sandbox.run() kwargs : remplacements propres à chaque sandbox.
  • @session.function() kwargs : configuration propre à une fonction.
Les sections suivantes décrivent en détail chaque aspect de la configuration.

Ressources

Configurez les ressources CPU, mémoire et GPU à l’aide de la dataclass ResourceOptions ou d’un dictionnaire standard. Le mode sans serveur est le mode de placement par défaut. Pour les Sandbox sans serveur, définissez des demandes de ressources et des limites identiques pour le CPU et la mémoire. Pour définir des demandes de ressources et des limites différentes, utilisez le placement CKS avec un exécuteur dont la politique l’autorise. Pour choisir les valeurs, consultez Dimensionner le CPU et la mémoire d’une Sandbox. Ne comptez pas sur le mode sans serveur pour harmoniser des valeurs différentes. Le fait qu’une création aboutisse avec des demandes de ressources et des limites différentes ne signifie pas que le dépassement de ressources (bursting) est pris en charge. Les exemples suivants utilisent des demandes de ressources et des limites identiques :
Les deux formes sont équivalentes : le SDK convertit automatiquement les dicts en ResourceOptions en interne. ResourceOptions distingue les demandes de ressources des limites. Les demandes de ressources indiquent à l’ordonnanceur ce dont la Sandbox a besoin. Les limites fixent le maximum qu’elle peut consommer. Pour savoir comment Kubernetes s’appuie sur les demandes de ressources et les limites pour attribuer des classes de Qualité de service, consultez la documentation Kubernetes.

Champs de ResourceOptions

Tous les champs sont facultatifs côté client et valent None par défaut. L’allocation résolue doit respecter la politique applicable. Si vous omettez l’allocation des ressources, les demandes de ressources et les limites sont toutes deux définies à partir des valeurs par défaut de CPU et de mémoire de cette politique, qui doivent être complètes et positives.

QoS Guaranteed

La Qualité de service Guaranteed dépend des ressources de chacun des conteneurs du Pod. Avec des allocations au niveau des conteneurs, chaque conteneur doit avoir des demandes de ressources en CPU et en mémoire strictement positives, assorties de limites identiques pour chaque ressource. Cela vaut aussi pour les conteneurs d’initialisation et les sidecars. Il ne suffit pas que les valeurs soient égales pour le seul conteneur de votre charge de travail pour déterminer la classe de QoS de l’ensemble du Pod de la sandbox. Une sandbox qui tente d’utiliser plus de CPU que sa limite le permet reste néanmoins bridée.
Lorsque les demandes de ressources et les limites sont égales, une syntaxe abrégée sous forme de dict plat est disponible. Le SDK normalise les dicts plats en définissant les demandes de ressources et les limites sur les mêmes valeurs.

QoS Burstable

Sur un exécuteur CKS dont la politique autorise des demandes de ressources et des limites différentes, des demandes de ressources plus faibles attribuent à la sandbox la classe de Qualité de service Burstable. Avec des demandes de ressources plus faibles, l’ordonnanceur peut regrouper davantage de sandboxes sur les nœuds, tandis que chaque sandbox peut monter jusqu’à sa limite si la capacité le permet. Suivez le guide Utiliser votre propre infrastructure de calcul et définissez CWSANDBOX_API_KEY sur un jeton d’accès à l’API CoreWeave. Remplacez [RUNNER-ID] par l’ID d’un exécuteur CKS dont la politique autorise ces demandes de ressources et ces limites :

Valeurs de CPU

Indiquez le CPU en millicœurs ou en cœurs entiers. Pour plus de détails, voir Resource units in Kubernetes.

Valeurs de mémoire

La mémoire s’exprime dans les unités de mémoire Kubernetes standard :

GPU

Demandez des ressources GPU en plus du CPU et de la mémoire. Une requête GPU ne réserve que des GPU ; définissez donc explicitement le CPU et la mémoire.
Clés de configuration GPU : type et memory_gb sont mutuellement exclusifs. Définissez-en un seul au maximum.

Inspecter les ressources confirmées

Une fois la sandbox démarrée, inspectez l’allocation des ressources confirmée. Cet exemple utilise des demandes de ressources et des limites différentes sur CKS. Effectuez la configuration de CKS, puis définissez CWSANDBOX_API_KEY sur un jeton d’accès à l’API CoreWeave. Remplacez [RUNNER-ID] par l’ID d’un exécuteur CKS qui dispose d’une capacité GPU et d’une politique autorisant ces ressources :

Interopérabilité avec les bibliothèques de configuration

Tous les types de configuration (NetworkOptions, Secret, ResourceOptions) acceptent soit la dataclass, soit un dictionnaire standard. Les bibliothèques de configuration ML qui résolvent les configurations en dicts ou en objets de type dict peuvent ainsi transmettre directement les valeurs au SDK, sans conversion manuelle. SandboxDefaults.from_dict() accepte un dictionnaire standard ou un DictConfig OmegaConf, et convertit automatiquement les champs imbriqués. Il convertit les configurations de réseau et de secret en leurs types SDK, et les mappages de ressources en dictionnaires standard. Le SDK normalise ensuite ces dicts de ressources en ResourceOptions lors de la construction d’une sandbox.
Chaque champ accepte également un dict lorsque vous le transmettez directement à Sandbox.run() ou à session.sandbox(). Pour les ressources, la forme dict imbriquée correspond aux champs de ResourceOptions. La forme dict plate ({"cpu": "1", "memory": "1Gi"}) définit des demandes de ressources et des limites identiques pour le CPU et la mémoire du conteneur de la charge de travail. Les exigences de la QoS Guaranteed s’appliquent toujours à chaque conteneur du Pod.

Fichiers montés

Les fichiers montés vous permettent de fournir à la sandbox, dès son démarrage, des fichiers de configuration, des scripts ou d’autres ressources en lecture seule, sans avoir à les intégrer à une image de conteneur.

Options de montage

Les fichiers montés sont en lecture seule. Pour les fichiers à modifier, utilisez write_file().

Ports

Déclarez les ports avec services=[Service(...)]. Une déclaration telle que Service(port=8080, name="web"), sans visibility ni endpoint, reste locale au conteneur et ne demande aucune exposition externe. Pour servir du HTTP à des clients sur Internet, demandez un point de terminaison HTTPS public. Cet exemple s’exécute sur une capacité sans serveur, démarre un serveur HTTP sur le port 8080, puis interroge depuis votre machine locale l’URL HTTPS qui lui est attribuée. La plateforme assure la terminaison TLS et transmet le trafic HTTP au port du conteneur. L’exemple utilise EndpointAuth.OPEN : toute personne disposant de l’URL peut donc y accéder sans identifiant d’authentification. Il utilise le répertoire /tmp du conteneur de démonstration comme racine des documents. L’identifiant d’authentification utilisé avec auth=AUTH autorise la création et la suppression de la sandbox. Il n’est pas requis pour les requêtes vers ce point de terminaison OPEN.
Le script effectue de nouvelles tentatives jusqu’à ce que l’URL et le serveur HTTP soient prêts, affiche HTTP 200: directory listing received en cas de succès, puis supprime la sandbox après la tentative d’accès. La durée de vie de 5 minutes limite en outre sa durée d’exécution. Le paramètre ports a été supprimé dans cwsandbox 1.x. Toute valeur transmise à ce paramètre lève une exception TypeError. Utilisez plutôt services=[Service(...)].

Champs du service

Chaque entrée de sandbox.service_urls est un tuple (port, name, url). Une URL peut apparaître alors que la sandbox est encore à l’état CREATING ; une URL attribuée ne garantit donc pas que l’application soit à l’écoute. Un service simple n’a pas de valeur endpoint. Pour connaître les règles de combinaison de services simples et de points de terminaison dans une même sandbox, voir Déclarer un point de terminaison. En HTTPS, EndpointAuth.OPEN autorise l’accès sans authentification. EndpointAuth.SHARE_TOKEN nécessite un jeton de partage renvoyé lors de la création, le SDK Python 1.16.0 ou version ultérieure, ainsi qu’un déploiement prenant en charge le HTTPS avec jeton de partage. En mode TLS passthrough, l’authentification du point de terminaison n’est pas définie : votre charge de travail se charge de la terminaison TLS et du contrôle d’accès. Pour l’acheminement et l’authentification des points de terminaison, voir Points de terminaison publics. Les pages générées référence Service et référence Endpoint décrivent la version 1.14.2 du SDK, qui prend en charge OPEN mais est antérieure à SHARE_TOKEN.

Réseau

Configurez le trafic sortant et entrant à l’aide de la dataclass NetworkOptions ou d’un dictionnaire standard. Les règles de trafic sortant et d’ingress accordent des accès par rapport à une référence qui refuse tout par défaut. Une liste egress non vide remplace les autorisations de destination par défaut de la politique de l’exécuteur. Les autorisations par nom d’hôte nécessitent un exécuteur qui prend en charge le trafic sortant HTTPS par nom d’hôte, ainsi qu’une politique qui autorise chacune des destinations demandées. Pour un placement CKS, demandez à votre administrateur de vérifier les contraintes réseau de l’exécuteur. Pour un placement sans serveur, CoreWeave gère le pool et sa politique. Si le pool rejette ces règles de nom d’hôte, contactez le Support CoreWeave. Pour télécharger des paquets depuis PyPI, autorisez à la fois pypi.org pour l’index des paquets et files.pythonhosted.org pour les fichiers des paquets. Les autorisations pypi.org et *.pypi.org ne couvrent pas files.pythonhosted.org :
Les deux formes sont équivalentes : le SDK convertit automatiquement les dicts en NetworkOptions en interne.

Champs de NetworkOptions

Tous les champs sont facultatifs et valent None par défaut. Une liste de règles vide dont l’option de blocage correspondante n’est pas définie ou vaut False entraîne l’application de la valeur par défaut de la politique de l’exécuteur. L’exposition des ports passe par services, et non par NetworkOptions. Pour la liste complète des champs EgressRule et IngressRule, voir Règles réseau. Une EgressRule requiert exactement une destination : dns_name, cidr, tenant, any ou selector. Une autorisation DNS accepte un nom exact ou un seul caractère générique placé tout à gauche, par exemple *.pypi.org. Une IngressRule requiert exactement une source : cidr, tenant ou any. Les champs egress_mode, ingress_mode et exposed_ports ne sont pas pris en charge dans cwsandbox 1.x. Utilisez plutôt les champs ci-dessus et déclarez les ports avec services. deny_egress=True ne garantit pas une isolation réseau complète. Le trafic requis par la plateforme peut rester autorisé, et le DNS sortant est contrôlé séparément. Le type Python NetworkOptions n’expose pas dnsEgress. Pour modifier ce mode, utilisez l’API NetworkConfig, si elle le prend en charge.
Le SDK Python applique les options réseau à la création d’une sandbox et ne fournit aucune méthode pour mettre à jour la politique réseau d’une sandbox en cours d’exécution. Pour la procédure via l’API, voir Politiques réseau dynamiques. Les ports exposés et la visibilité des services restent des paramètres définis à la création.

Définir le réseau dans SandboxDefaults

Définissez une configuration réseau par défaut pour toutes les Sandbox :
Un network défini pour une sandbox remplace la valeur SandboxDefaults.network au lieu d’être fusionné avec elle. Dans l’exemple ci-dessus, sb3 désactive les autorisations de destination ; le DNS reste contrôlé séparément.

Annotations

Ajoutez des annotations de pod Kubernetes à vos Sandbox. Les annotations sont des paires clé-valeur de chaînes de caractères associées au pod sous-jacent. Elles sont utiles pour les intégrations qui lisent les métadonnées des pods, comme les ordonnanceurs, les outils d’allocation des coûts ou les automatisations externes.

Valeurs par défaut au niveau de la session

Définissez des annotations par défaut pour toutes les Sandbox d’une session :

Comportement de fusion

Lorsque vous fournissez à la fois SandboxDefaults.annotations et des annotations propres à chaque sandbox, le SDK les fusionne. En cas de conflit de clés, les valeurs explicitement définies pour la sandbox l’emportent, selon la même sémantique que pour environment_variables.

Intégration avec SUNK

Pour transmettre le contexte Slurm sous forme d’annotations de pod dans le cadre de l’intégration avec SUNK, consultez le guide d’intégration du SUNK Pod Scheduler.

Validation

Le SDK ne valide ni les clés ni les valeurs des annotations. C’est le serveur qui valide les préfixes de clé réservés, le format des valeurs et le nombre maximum d’entrées.

Secrets

Pour en savoir plus sur l’injection de secrets d’équipe Forge, les exigences d’authentification et des exemples en Python et TypeScript, consultez Utiliser les secrets Forge.

Délais d’expiration

Trois paramètres déterminent la durée d’exécution d’une sandbox et de ses opérations. Leurs noms se ressemblant, le tableau suivant indique ce que chacun d’eux limite. Seul max_lifetime_seconds met fin à une sandbox. Les deux autres limitent des requêtes individuelles sans interrompre la sandbox. Le paramètre max_timeout_seconds a été supprimé dans cwsandbox 1.x. Si vous lui transmettez une valeur, une exception TypeError est levée. Utilisez request_timeout_seconds pour définir le délai d’expiration des requêtes client.

max_lifetime_seconds

max_lifetime_seconds définit la durée de vie totale d’une sandbox, mesurée en temps réel. Lorsqu’une sandbox atteint cette durée, la plateforme y met fin, même si des tâches sont encore en cours. Si vous ne définissez pas max_lifetime_seconds, la valeur par défaut de la politique de l’exécuteur s’applique. Si la politique ne fournit aucune valeur par défaut positive pour la durée de vie, la plateforme applique une durée de 10 minutes. Pour les tâches de longue durée, définissez explicitement cette valeur :
Pour appliquer une même durée de vie à toutes les Sandbox créées par une session, définissez-la dans SandboxDefaults :
Un argument max_lifetime_seconds explicite passé à Sandbox.run() est prioritaire sur la valeur définie dans defaults. Comme la valeur par défaut de cet argument est None, vous ne pouvez pas l’utiliser pour supprimer une durée de vie déjà définie par defaults. La durée de vie maximale que vous pouvez demander est de 30 jours (2 592 000 secondes), aussi bien pour le placement sans serveur que pour le placement CKS. La plateforme rejette toute demande supérieure.
Vous ne pouvez pas modifier max_lifetime_seconds une fois une sandbox démarrée. Aucune API ne permet de prolonger la durée de vie d’une sandbox en cours d’exécution : choisissez donc la valeur lors de sa création. Pour continuer à travailler au-delà de cette limite, capturez ce dont vous avez besoin et démarrez une nouvelle sandbox avec une durée de vie pouvant aller jusqu’à 30 jours.
Pour des exemples de création et les valeurs par défaut des politiques d’exécuteur CKS, consultez Exécuter des Sandbox de longue durée.

Comportement à l’expiration de la durée de vie

La plateforme applique la durée de vie au moyen d’une échéance définie sur le Job Kubernetes sous-jacent de la sandbox. Une fois l’échéance atteinte, la charge de travail est arrêtée, même si des traitements sont encore en cours. Enregistrez les résultats ou les points de contrôle en dehors de la sandbox avant l’expiration. Le SDK Python expose le motif signalé par le backend dans Sandbox.status_reason, mis en cache à partir de la dernière réponse de l’API. L’expiration de la durée de vie peut se traduire par un motif commençant par DeadlineExceeded. Si le SDK lève SandboxFailedError, son attribut status_reason contient également le motif signalé par le backend. Comme le motif n’est pas toujours renseigné, surveillez aussi l’âge des Sandbox de longue durée. Définissez une durée de vie largement supérieure à la durée prévue de vos traitements. Lorsque vous avez terminé, arrêtez explicitement les Sandbox au lieu de compter sur l’expiration.

timeout_seconds

timeout_seconds limite la durée d’une opération individuelle sur une sandbox en cours d’exécution :
Ce paramètre détermine combien de temps le client attend une réponse. Si l’attente dépasse le délai d’expiration, le SDK lève SandboxTimeoutError. La sandbox, elle, continue de s’exécuter. Le décompte ne commence qu’une fois la sandbox passée à l’état RUNNING, si bien que le temps de démarrage n’est pas pris en compte. Veillez à ce que timeout_seconds reste inférieur à la valeur max_lifetime_seconds de la sandbox. Une commande dont le délai d’expiration dépasse la durée de vie restante de la sandbox s’arrête lorsque la sandbox se termine.

request_timeout_seconds

request_timeout_seconds est le délai d’expiration HTTP côté client appliqué à la plupart des RPC. Il sert également de valeur de repli lorsqu’un appel ne transmet pas son propre timeout_seconds. Définissez-le dans SandboxDefaults :
L’interrogation du statut utilise plutôt poll_rpc_timeout_seconds, de sorte qu’une interrogation bloquée échoue rapidement au lieu de rester en attente pendant toute la durée du délai d’expiration de la requête. Pour la liste complète des options de réglage côté client, consultez la référence SandboxDefaults.

Exemple complet

L’exemple suivant réunit des valeurs par défaut, des remplacements propres à chaque sandbox, des fichiers montés et des déclarations de services. Il télécharge des paquets depuis PyPI et les importe pour vérifier l’installation. Le pool sans serveur doit satisfaire aux exigences d’autorisation des noms d’hôte. Cet exemple déclare un port de service, mais ne démarre aucun serveur et ne crée aucun point de terminaison public :
Dernière modification le 4 novembre 2026