Fonctions distantes

Ce guide présente le décorateur @session.function(), qui permet d’exécuter des fonctions Python dans des sandboxes. Il s’adresse aux développeurs qui souhaitent déporter des calculs Python ponctuels vers des environnements isolés sans avoir à gérer eux-mêmes le cycle de vie d’un sandbox. Il explique comment définir des fonctions distantes, quels types d’arguments et de valeurs de retour l’API prend en charge, et dans quels cas cette API est la plus adaptée.

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 sandboxes. 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 lui-même. 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 via 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. Créer une session avec auth=AUTH authentifie également les sandboxes qui lui appartiennent. Conservez le même identifiant d’authentification pour vous reconnecter aux sandboxes, les lister ou les nettoyer.

Aperçu

L’API de décorateur de fonction vous permet d’exécuter des fonctions Python dans des conteneurs sandbox isolés. Utilisez-la pour exécuter à distance des traitements Python distincts tout en conservant un code appelant simple :

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH) as session:
    @session.function()
    def compute(x: int, y: int) -> int:
        return x + y

    # Exécuter dans une sandbox
    result = compute.remote(2, 3).result()
    print(result)  # 5

Utilisation de base

Définir des fonctions

Décorez les fonctions avec @session.function() :

@session.function()
def process_data(data: dict) -> dict:
    # Le code s’exécute dans la sandbox
    import pandas as pd
    df = pd.DataFrame(data)
    return {"mean": df["value"].mean()}

Appeler des fonctions

Appelez .remote() sur la fonction décorée pour l’exécuter dans le sandbox :

# Renvoie immédiatement un OperationRef
ref = compute.remote(2, 3)

# Attendre le résultat (appel bloquant)
result = ref.result()

# En une seule ligne
result = compute.remote(2, 3).result()

Méthodes d’exécution

Exécuter en parallèle avec map()

Exécutez sur plusieurs entrées :

@session.function()
def square(x: int) -> int:
    return x * x

# Exécuter pour chaque entrée
refs = square.map((x,) for x in range(10))

# Récupérer tous les résultats
from cwsandbox import results
all_results = results(refs)  # [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

Avec des tuples pour des arguments multiples :

@session.function()
def add(x: int, y: int) -> int:
    return x + y

# Chaque tuple est dépaqueté en arguments
refs = add.map([(1, 2), (3, 4), (5, 6)])
all_results = results(refs)  # [3, 7, 11]

Exécuter en local avec local()

Exécutez le code en local, sans sandbox, ce qui est pratique pour les tests :

# Aucune sandbox n'est créée : exécution dans le processus courant
result = compute.local(2, 3)
print(result)  # 5

Types des arguments et des valeurs de retour

Les fonctions distantes transmettent les arguments et les valeurs de retour au format JSON. Ils doivent donc être sérialisables en JSON : dictionnaires, listes, chaînes de caractères, nombres, booléens et None.

@session.function()
def process(data: dict) -> dict:
    return {"result": data["value"] * 2}

Si vous transmettez un argument non représentable en JSON, l’appel lève une exception TypeError avant le démarrage de la sandbox :

Example output

TypeError: Function arguments are not JSON-serializable: Object of type ndarray is not JSON serializable

Une valeur de retour que JSON ne peut pas représenter provoque le même échec, avec le message return value is not JSON-serializable. Les objets JSON n’acceptent que des clés de type string. Un dictionnaire dont les clés sont des entiers, des nombres à virgule flottante ou des booléens est rejeté plutôt que converti : ainsi, les types que reçoit votre fonction dans la sandbox correspondent à ceux que vous avez transmis. Pour manipuler des tableaux NumPy, des DataFrames pandas ou des instances de classes personnalisées, convertissez-les en valeurs compatibles avec JSON avant d’appeler la fonction, puis reconstruisez-les à l’intérieur de celle-ci :

@session.function()
def array_mean(values: list[float]) -> float:
    from statistics import fmean
    return fmean(values)

result = array_mean.remote([1.0, 2.0, 3.0, 4.0, 5.0]).result()  # 3.0

Le client n’installe rien avant d’exécuter votre fonction. Toute bibliothèque importée par la fonction, comme NumPy, doit déjà être présente dans l’image de conteneur. Si les données sont trop volumineuses pour être transmises en JSON, écrivez-les dans un stockage accessible depuis la sandbox et transmettez plutôt une référence. Voir Opérations sur les fichiers.

Closures et variables globales

Variables de closure

Les fonctions capturent les variables de leur portée englobante :

multiplier = 10

@session.function()
def multiply(x: int) -> int:
    return x * multiplier  # Capture la variable 'multiplier'

result = multiply.remote(5).result()  # 50

Variables globales

Le décorateur sérialise avec la fonction les variables globales auxquelles elle fait référence :

CONFIG = {"threshold": 0.5}

@session.function()
def check_value(x: float) -> bool:
    return x > CONFIG["threshold"]

result = check_value.remote(0.7).result()  # True

Les variables de closure capturées et les variables globales sont transférées vers la sandbox au format JSON, tout comme les arguments et les valeurs de retour. Si une fonction capture une valeur non représentable en JSON, l’appel échoue pour cette raison, même si tous les arguments que vous transmettez sont valides.

Image de conteneur

Remplacez l’image de conteneur pour certaines fonctions :

@session.function(container_image="pytorch/pytorch:latest")
def train_model(data: dict) -> dict:
    import torch
    # Code d'entraînement sur GPU
    return {"loss": 0.01}

Gestion des erreurs

Les exceptions levées par une fonction se propagent jusqu’à l’appelant :

@session.function()
def failing_function() -> None:
    raise ValueError("Something went wrong")

try:
    failing_function.remote().result()
except Exception as e:
    print(f"Function failed: {e}")

Quand utiliser les fonctions plutôt que les sandboxes

Utilisez le tableau suivant pour déterminer laquelle de l’API du décorateur de fonction ou de l’API sandbox convient le mieux à votre charge de travail.

Cas d’utilisation	API recommandée
Calcul Python simple	Décorateur de fonction
Map/reduce sur des données	Décorateur de fonction
Flux de travail interactif, commandes multiples	Sandbox
Sortie en diffusion en continu	Sandbox
Manipulation de fichiers	Sandbox
Processus de longue durée	Sandbox

Limitations

L’API de fonctions est volontairement simple. Pour les flux de travail complexes :

Nouvelles tentatives et backoff : implémentez-les dans le code appelant.
Dépendances entre tâches et DAG : utilisez un orchestrateur de flux de travail comme Airflow ou Prefect.
Ordonnancement complexe : utilisez directement l’API de sandbox.

Exemple complet

L’exemple suivant réunit les concepts présentés dans ce guide. Il illustre l’exécution unique et l’exécution parallèle, ainsi qu’un calcul dont l’argument et la valeur de retour sont transmis au format JSON :

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults, results

defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("remote-functions-demo",),
    resources={"cpu": "1", "memory": "1Gi"},
)

with cwsandbox.Session(defaults=defaults, auth=AUTH) as session:
    @session.function()
    def square(x: int) -> int:
        return x * x

    # L’argument est une liste et le résultat un nombre à virgule flottante : tous deux sont donc sérialisables en JSON
    @session.function()
    def array_mean(values: list[float]) -> float:
        from statistics import fmean
        return fmean(values)

    # Exécution unique
    result = square.remote(7).result()
    print(f"7 squared: {result}")

    # Exécution en parallèle
    refs = square.map((x,) for x in range(5))
    all_results = results(refs)
    print(f"Squares: {all_results}")

    # Calcul compatible JSON
    mean = array_mean.remote([1.0, 2.0, 3.0, 4.0, 5.0]).result()
    print(f"Array mean: {mean}")

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Choisir l’authentification

Aperçu

Utilisation de base

Définir des fonctions

Appeler des fonctions

Méthodes d’exécution

Exécuter en parallèle avec map()

Exécuter en local avec local()

Types des arguments et des valeurs de retour

Closures et variables globales

Variables de closure

Variables globales

Image de conteneur

Gestion des erreurs

Quand utiliser les fonctions plutôt que les sandboxes

Limitations

Exemple complet

​Choisir l’authentification

​Aperçu

​Utilisation de base

​Définir des fonctions

​Appeler des fonctions

​Méthodes d’exécution

​Exécuter en parallèle avec map()

​Exécuter en local avec local()

​Types des arguments et des valeurs de retour

​Closures et variables globales

​Variables de closure

​Variables globales

​Image de conteneur

​Gestion des erreurs

​Quand utiliser les fonctions plutôt que les sandboxes

​Limitations

​Exemple complet

Choisir l’authentification

Aperçu

Utilisation de base

Définir des fonctions

Appeler des fonctions

Méthodes d’exécution

Exécuter en parallèle avec map()

Exécuter en local avec local()

Types des arguments et des valeurs de retour

Closures et variables globales

Variables de closure

Variables globales

Image de conteneur

Gestion des erreurs

Quand utiliser les fonctions plutôt que les sandboxes

Limitations

Exemple complet