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 nomsandbox_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.
- 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 :
sandbox_auth.py
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.
Ressources
Configurez les ressources CPU, mémoire et GPU à l’aide de la dataclassResourceOptions 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 :
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.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éfinissezCWSANDBOX_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.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éfinissezCWSANDBOX_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.
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 avecservices=[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.
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 dataclassNetworkOptions 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 :
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 :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 foisSandboxDefaults.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 :
SandboxDefaults :
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.
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 dansSandbox.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 :
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 :
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.