Skip to main content
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 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.
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 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 :
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

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.
Pour la QoS Guaranteed, 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 : les dicts deviennent des NetworkOptions, Secret ou ResourceOptions selon le cas, et les listes deviennent des tuples.
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"}) 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 dataclass NetworkOptions ou d’un dictionnaire standard :
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, 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 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

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 :
Pour appliquer une même durée de vie à toutes les sandboxes 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 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.
Définissez une durée de vie largement supérieure à la durée de travail prévue, et arrêtez explicitement les sandboxes une fois votre travail terminé, plutôt que de compter sur leur 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.

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 :
Le serveur accepte des valeurs comprises entre 1 et 300 secondes, avec une valeur par défaut de 30. Toute valeur supérieure à 300 est ramenée à 300. Si les sandboxes ne parviennent pas à démarrer lorsque le cluster est fortement sollicité, augmentez cette valeur. 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 :
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 ports dans une configuration unique, à l’image du lancement d’une charge de travail en production :
Dernière modification le 15 octobre 2026