Opérations sur les fichiers

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 connaître les exigences liées à CKS, consultez Modes de placement. 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.

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

from cwsandbox import Sandbox

with Sandbox.run() as sandbox:
    # Écrire des octets dans un fichier
    sandbox.write_file("/app/data.txt", b"Hello, World!").result()

    # Écrire du JSON
    import json
    config = {"key": "value", "count": 42}
    sandbox.write_file(
        "/app/config.json",
        json.dumps(config).encode()
    ).result()

Lire des fichiers

# Lire le contenu du fichier sous forme d’octets
content = sandbox.read_file("/app/data.txt").result()
print(content.decode())  # "Hello, World!"

# Lire un fichier JSON
config_bytes = sandbox.read_file("/app/config.json").result()
config = json.loads(config_bytes.decode())

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 cwsandbox import Sandbox, results

with Sandbox.run() 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,
    ),
) 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

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

​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

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