CWSANDBOX_API_KEY. Pour l’authentification par clé API Forge, consultez Premiers pas. Pour les exigences liées à CKS, consultez Modes de placement.
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 sandboxes.
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 sandboxes 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 et applique des demandes de ressources et des limites identiques. 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.
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
Lorsque les demandes de ressources sont égales aux limites, la sandbox se voit attribuer la classe de Qualité de service Guaranteed. L’ordonnanceur réserve l’intégralité de l’allocation, et Kubernetes n’évince les Pods Guaranteed qu’en dernier recours lorsque les ressources du nœud sont sous pression. Une sandbox qui tente d’utiliser plus de CPU que sa limite le permet reste néanmoins bridée. Utilisez cette configuration pour les charges de travail sensibles à la latence.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 : les dicts deviennent des NetworkOptions, Secret ou ResourceOptions selon le cas, et les listes deviennent des tuples.
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"}) est également acceptée et traitée comme une QoS Guaranteed.
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
Exposez des ports pour permettre aux processus exécutés dans la sandbox de servir le trafic provenant de clients externes :Configuration des ports
Pour attribuer à un port une adresse accessible depuis Internet, avec le TLS de la plateforme ou en mode TLS passthrough, consultez Points de terminaison publics.
Réseau
Configurez les options réseau à l’aide de la dataclassNetworkOptions ou d’un dictionnaire standard :
NetworkOptions en interne.
Champs de NetworkOptions
Tous les champs sont facultatifs et valent
None par défaut, auquel cas les valeurs par défaut du backend s’appliquent.
Définir le réseau dans SandboxDefaults
Définissez une configuration réseau par défaut pour toutes les sandboxes :Annotations
Ajoutez des annotations de pod Kubernetes à vos sandboxes. 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 sandboxes 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
Quatre 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 trois autres limitent des requêtes individuelles sans interrompre la sandbox.
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 sandboxes de longue durée.
Comportement à l’expiration de la durée de vie
La plateforme applique la durée de vie en mettant fin à la tâche Kubernetes (Job) sous-jacente de la sandbox : l’arrêt est donc immédiat, et non progressif. En pratique, cela a deux conséquences importantes :- Les processus exécutés dans la sandbox ne bénéficient pas du délai de grâce que fournit
stop(). Toute donnée qui n’a pas encore été écrite est perdue. - Le client ne reçoit aucune erreur ni aucun motif distinct pour cet arrêt. Le SDK ne signale aucun motif d’arrêt sur un objet
Sandbox: vous ne pouvez donc pas distinguer par programmation l’expiration de la durée de vie des autres échecs. Suivez vous-même l’âge des sandboxes de longue durée.
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.
max_timeout_seconds
max_timeout_seconds limite la durée pendant laquelle le serveur tente de placer une sandbox sur un exécuteur avant que la tentative n’échoue. Il s’agit d’un budget de placement côté serveur, et non d’un délai d’expiration de lecture côté client. Il n’a aucune incidence sur la durée d’exécution ultérieure de la sandbox :
max_timeout_seconds est disponible dans Sandbox.run() et session.sandbox(), mais pas dans SandboxDefaults.
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.