Variables d’environnement

Ce guide vous explique comment définir et gérer les variables d’environnement dans les instances CWSandbox. Les variables d’environnement permettent de transmettre à vos Sandbox des valeurs de configuration non sensibles, comme des niveaux de journalisation ou des identifiants de projet. Vous pouvez les définir sur un Sandbox donné, les partager entre les Sandbox d’une même session ou limiter leur portée à des fonctions distantes.

Ne codez pas en dur de clés API, de mots de passe ni d’autres identifiants d’authentification dans environment_variables, et ne les écrivez pas dans les journaux. Privilégiez les références de secret plutôt que la transmission d’identifiants d’authentification en clair. Conservez les valeurs sensibles dans un gestionnaire de secrets, même lorsque l’injection de secrets Forge n’est pas disponible. Ces recommandations s’appliquent aussi bien aux Sandbox sans serveur qu’aux Sandbox CKS.

Pour les Sandbox sans serveur authentifiés avec Forge, utilisez les secrets Forge. Le serveur résout ces références et injecte les valeurs sous forme de variables d’environnement. L’injection de secrets Forge n’est disponible ni pour le placement CKS ni pour les Sandbox authentifiés avec un jeton d’accès à l’API CoreWeave. Pour CKS, utilisez la méthode approuvée par votre organisation pour transmettre des secrets aux charges de travail.

Choisir l’authentification

Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section précise 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 la méthode d’authentification choisie, 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 :

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Utilisez le jeton de votre organisation CoreWeave :

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

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. Une session créée avec auth=AUTH authentifie également les Sandbox qui lui appartiennent. Utilisez le même identifiant d’authentification pour vous reconnecter à vos Sandbox, les lister ou les nettoyer.

Utilisation de base

Pour rendre des valeurs disponibles aux processus exécutés dans la sandbox, transmettez un dictionnaire environment_variables à Sandbox.run :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(
    environment_variables={"LOG_LEVEL": "info"},
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sandbox:
    result = sandbox.exec([
        "python",
        "-c",
        "import os; print(os.environ.get('LOG_LEVEL'));",
    ]).result()
    print(result.stdout.strip())  # "info"

Valeurs par défaut au niveau de la session

Lorsque vous avez besoin des mêmes variables dans plusieurs Sandbox, définissez-les une seule fois dans une session plutôt que de les répéter pour chaque Sandbox. Chaque Sandbox peut remplacer les valeurs par défaut de la session ou ajouter ses propres variables :

from sandbox_auth import AUTH
from cwsandbox import SandboxDefaults, Session

defaults = SandboxDefaults(
    environment_variables={
        "PROJECT_ID": "my-project",
        "LOG_LEVEL": "info",
    },
    resources={"cpu": "1", "memory": "1Gi"},
)

with Session(defaults, auth=AUTH) as session:
    with session.sandbox() as sb1:
        result = sb1.exec([
            "python",
            "-c",
            "import os; print(os.environ.get('LOG_LEVEL'));",
        ]).result()
        print(result.stdout.strip())  # "info"

    # Remplacer LOG_LEVEL et ajouter une nouvelle variable
    with session.sandbox(
        environment_variables={
            "LOG_LEVEL": "debug",  # Remplacer la valeur par défaut de la session
            "MODEL_NAME": "gpt-4",  # Ajouter une nouvelle variable
        }
    ) as sb2:
        result = sb2.exec([
            "python",
            "-c",
            "import os; "
            "print(os.environ.get('PROJECT_ID')); "
            "print(os.environ.get('LOG_LEVEL')); "
            "print(os.environ.get('MODEL_NAME'));",
        ]).result()
        lines = result.stdout.strip().split("\n")
        print(lines)  # ["my-project", "debug", "gpt-4"]

Fonctions distantes

Les fonctions distantes héritent des variables d’environnement de la session et peuvent déclarer les leurs à l’aide du décorateur @session.function. Au moment de l’appel, le SDK fusionne les variables définies au niveau de la fonction avec les valeurs par défaut de la session :

from sandbox_auth import AUTH
with Session(defaults, auth=AUTH) as session:
    @session.function(environment_variables={"MODEL_VERSION": "v2.0"})
    def process(task_id: int) -> dict:
        import os
        return {
            "task": task_id,
            "project": os.environ.get("PROJECT_ID"),  # Provient des valeurs par défaut de la session
            "version": os.environ.get("MODEL_VERSION"),  # Provient du décorateur de fonction
        }

    result = process.remote(42).result()
    print(result)  # {"task": 42, "project": "my-project", "version": "v2.0"}

Les variables d’environnement sont transmises par référence. Les appels de fonctions ultérieurs tiennent compte des modifications apportées au dictionnaire après l’application du décorateur, comme le montre l’exemple suivant.

env_vars = {"MODEL_VERSION": "v2.0"}

@session.function(environment_variables=env_vars)
def process(task_id: int) -> dict:
    import os
    return {"version": os.environ.get("MODEL_VERSION")}

result = process.remote(42).result()  # version : "v2.0"

env_vars["MODEL_VERSION"] = "v3.0"  # Modification du dictionnaire

result = process.remote(42).result()  # version : "v3.0" (modifiée)

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Variables d’environnement

Choisir l’authentification

Utilisation de base

Valeurs par défaut au niveau de la session

Fonctions distantes

​Choisir l’authentification

​Utilisation de base

​Valeurs par défaut au niveau de la session

​Fonctions distantes

Choisir l’authentification

Utilisation de base

Valeurs par défaut au niveau de la session

Fonctions distantes