Opérations sur les fichiers

Ce guide explique comment lire, écrire et gérer des fichiers dans une instance de sandbox CoreWeave à l’aide du client CWSandbox. Il s’adresse aux développeurs qui conçoivent des flux de travail chargés de transférer des données vers et depuis des bacs à sable. Il aborde notamment les téléversements et téléchargements en parallèle, la gestion des erreurs et les bonnes pratiques pour les fichiers volumineux.

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. Consultez Choisir et obtenir des identifiants d’authentification pour obtenir une clé ou un jeton. 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. 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. 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.

Opérations de base

Les exemples de cette section présentent les opérations sur les fichiers les plus courantes : écrire des données dans un chemin de la sandbox, puis les relire. Les opérations sur les fichiers renvoient des objets OperationRef. Utilisez .result() pour bloquer l’exécution jusqu’à l’achèvement de l’opération.

Écrire des fichiers

Laissez la sandbox s’exécuter pendant que vous écrivez et lisez des fichiers. Cet exemple crée deux fichiers, puis les lit avant que le gestionnaire de contexte n’arrête la sandbox :

import json

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    sandbox.write_file("/tmp/data.txt", b"Hello, World!").result()

    config = {"key": "value", "count": 42}
    sandbox.write_file("/tmp/config.json", json.dumps(config).encode()).result()

    content = sandbox.read_file("/tmp/data.txt").result()
    print(content.decode())  # "Hello, World!"

    config_bytes = sandbox.read_file("/tmp/config.json").result()
    restored_config = json.loads(config_bytes.decode())
    print(restored_config)

Lire des fichiers

read_file() renvoie le contenu du fichier sous forme d’octets. L’exemple de la section Écrire des fichiers utilise decode() pour lire du texte et json.loads() pour analyser du JSON. Ces deux lectures s’exécutent dans le contexte du sandbox actif.

Opérations parallèles

Les opérations sur les fichiers rendent la main immédiatement, ce qui permet naturellement de les paralléliser. Lorsque vous avez plusieurs fichiers indépendants, effectuer les téléversements ou les téléchargements en parallèle peut réduire la durée totale de transfert.

Téléversements parallèles

from cwsandbox import results

# Lancer tous les téléversements simultanément
write_refs = [
    sandbox.write_file("/app/config.json", config_bytes),
    sandbox.write_file("/app/data.csv", data_bytes),
    sandbox.write_file("/app/model.pkl", model_bytes),
]

# Attendre la fin de tous les téléversements
results(write_refs)

Téléchargements parallèles

# Lancer tous les téléchargements en parallèle
read_refs = [
    sandbox.read_file("/app/output.json"),
    sandbox.read_file("/app/metrics.json"),
    sandbox.read_file("/app/logs.txt"),
]

# Récupérer tous les résultats
output, metrics, logs = results(read_refs)

Schéma téléversement-traitement-téléchargement

Voici un flux de travail courant : téléverser les fichiers d’entrée, lancer le traitement, puis télécharger les résultats.

from sandbox_auth import AUTH
from cwsandbox import Sandbox, results

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    # 1. Téléversements en parallèle
    results([
        sandbox.write_file("/app/config.json", config_bytes),
        sandbox.write_file("/app/input.csv", input_bytes),
    ])

    # 2. Traitement séquentiel
    sandbox.exec(["pip", "install", "-r", "requirements.txt"]).result()
    sandbox.exec(["python", "/app/process.py"]).result()

    # 3. Téléchargements en parallèle
    output, metrics = results([
        sandbox.read_file("/app/output.json"),
        sandbox.read_file("/app/metrics.json"),
    ])

Gestion des erreurs

Les opérations sur les fichiers peuvent échouer si un chemin n’existe pas ou n’est pas accessible en écriture. Interceptez SandboxFileError pour gérer ces cas et identifier le chemin concerné.

Fichier introuvable

from cwsandbox import SandboxFileError

try:
    content = sandbox.read_file("/nonexistent/file.txt").result()
except SandboxFileError as e:
    print(f"File error: {e.filepath}")

Erreurs d’écriture

try:
    sandbox.write_file("/readonly/path.txt", b"data").result()
except SandboxFileError as e:
    print(f"Cannot write to: {e.filepath}")

Fichiers binaires

Les opérations sur les fichiers prennent en charge tout type de contenu binaire, y compris les images et les objets Python sérialisés :

# Images
with open("image.png", "rb") as f:
    sandbox.write_file("/app/image.png", f.read()).result()

# Fichiers pickle (ne désérialisez que des données provenant de sources fiables)
import pickle
model_bytes = pickle.dumps(my_model)
sandbox.write_file("/app/model.pkl", model_bytes).result()

# Téléchargement et désérialisation
model_bytes = sandbox.read_file("/app/trained_model.pkl").result()
trained_model = pickle.loads(model_bytes)

Ne désérialisez avec pickle que des données provenant de sources de confiance. Le chargement d’un fichier pickle peut entraîner l’exécution de code arbitraire.

Encodage du texte

Les fichiers sont transférés sous forme d’octets : vous devez donc encoder et décoder explicitement le texte pour éviter toute corruption des caractères non ASCII.

# Écrire du texte
text = "Hello, Unicode! "
sandbox.write_file("/app/text.txt", text.encode("utf-8")).result()

# Lire du texte
content = sandbox.read_file("/app/text.txt").result()
text = content.decode("utf-8")

Considérations relatives aux fichiers volumineux

Les API read_file et write_file sont surtout adaptées aux fichiers de petite ou moyenne taille. Pour les fichiers volumineux, tenez compte des points suivants :

Tenez compte de la bande passante, car les fichiers transitent par l’API.
Dans la mesure du possible, utilisez la diffusion en continu pour les datasets volumineux.
Accédez directement au stockage d’objets plutôt que de faire transiter les données par l’API.

Le paramètre object_storage_access crée des identifiants d’authentification CoreWeave AI Object Storage temporaires et les fournit aux conteneurs du sandbox. Votre charge de travail lit et écrit alors directement dans les buckets, si bien que les objets volumineux ne transitent jamais par read_file ni par write_file. Votre organisation doit au préalable enregistrer une configuration de fédération d’identités de charges de travail auprès du plan de contrôle des sandbox ; voir Accès au stockage d’objets. L’exemple suivant utilise l’authentification CoreWeave pour démarrer un sandbox avec un accès en lecture-écriture à un bucket, puis vérifie que les identifiants d’authentification ont bien été injectés. Définissez CWSANDBOX_API_KEY sur un jeton d’accès à l’API CoreWeave de l’organisation configurée, puis remplacez [BUCKET-NAME] par le nom de votre bucket :

from cwsandbox import AuthStrategy, ObjectStorageAccess, ObjectStoragePermission, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    container_image="python:3.11",
    object_storage_access=ObjectStorageAccess(
        buckets=["[BUCKET-NAME]"],
        permission=ObjectStoragePermission.READ_WRITE,
    ),
    resources={"cpu": "1", "memory": "1Gi"},
) as sandbox:
    result = sandbox.exec(["printenv", "AWS_ENDPOINT_URL_S3"]).result()
    print(result.stdout)

Le sandbox définit les variables d’environnement que les SDK AWS lisent pour obtenir les identifiants de conteneur, si bien que tout client compatible S3 exécuté à l’intérieur fonctionne sans clés explicites. Pour connaître ces variables et consulter un exemple Boto3, voir Utiliser les identifiants d’authentification dans le sandbox. Pour restreindre l’identifiant d’authentification à un préfixe de clé, utilisez object_prefix. Pour les charges de travail qui ne font que lire des données, utilisez ObjectStoragePermission.READ. Pour les données temporaires volumineuses qui restent locales au sandbox, joignez plutôt un volume. Voir Volumes.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Opérations sur les fichiers

Choisir l’authentification

Opérations de base

Écrire des fichiers

Lire des fichiers

Opérations parallèles

Téléversements parallèles

Téléchargements parallèles

Schéma téléversement-traitement-téléchargement

Gestion des erreurs

Fichier introuvable

Erreurs d’écriture

Fichiers binaires

Encodage du texte

Considérations relatives aux fichiers volumineux

​Choisir l’authentification

​Opérations de base

​Écrire des fichiers

​Lire des fichiers

​Opérations parallèles

​Téléversements parallèles

​Téléchargements parallèles

​Schéma téléversement-traitement-téléchargement

​Gestion des erreurs

​Fichier introuvable

​Erreurs d’écriture

​Fichiers binaires

​Encodage du texte

​Considérations relatives aux fichiers volumineux

Choisir l’authentification

Opérations de base

Écrire des fichiers

Lire des fichiers

Opérations parallèles

Téléversements parallèles

Téléchargements parallèles

Schéma téléversement-traitement-téléchargement

Gestion des erreurs

Fichier introuvable

Erreurs d’écriture

Fichiers binaires

Encodage du texte

Considérations relatives aux fichiers volumineux