5.3 Versionnage des données et des modèles - Machine Learning en géosciences

🖥️ Diapositives du cours — Séance 27 (ven. 4 déc.)

Une expérience suivie (section 5.2) enregistre quel code a produit un nombre. Ce n’est que la moitié de la provenance. L’autre moitié, c’est quelles données et quel modèle. Cette page traite les deux, puis montre comment câbler les vérifications dans l’intégration continue.

Versionner les données¶

Pourquoi Git échoue sur les données¶

Git stocke chaque version de chaque fichier et calcule les différences ligne à ligne. Cette conception se brise sur les données de trois manières. D’abord la taille : Git copie le contenu dans chaque clone, donc une archive de formes d’onde de 5 Go fait de chaque git clone un téléchargement de 5 Go, et dix versions en font cinquante. Ensuite les différences : les formats binaires (HDF5, Parquet, GeoTIFF, miniSEED) ne se comparent pas ligne à ligne de façon utile, donc Git stocke des copies quasi complètes à chaque version. Enfin les limites d’hébergement : GitHub refuse purement et simplement les fichiers de plus de 100 Mo. Les données demandent un autre mécanisme ; la bonne nouvelle, c’est que ce mécanisme peut rester ancré dans Git.

Les outils, un paragraphe chacun¶

git-lfs (Large File Storage) est le plus petit pas en avant : Git stocke un petit fichier pointeur, et le contenu réel vit sur un serveur LFS, récupéré au checkout. Il préserve intégralement le workflow Git et convient bien à une poignée de fichiers moyens (poids de modèle, un jeu de données de référence). Il devient coûteux et lent à l’échelle de dizaines de gigaoctets, et le quota LFS de GitHub est limité.

DVC (Data Version Control) est git-lfs généralisé aux jeux de données et aux flux de traitement. dvc add data/raw/catalog.parquet écrit un minuscule métafichier .dvc (une somme de contrôle et une taille) que vous validez dans Git ; le contenu part vers un dépôt distant de votre choix — S3, GCS, un serveur de laboratoire, voire Google Drive. dvc checkout matérialise exactement la version des données correspondant au commit courant. DVC décrit aussi des flux de traitement (dvc.yaml) : des étapes aux entrées et sorties déclarées, réexécutées seulement quand leurs entrées changent.

lakeFS apporte la sémantique de Git à un stockage objet : branches, commits et fusions sur tout un bucket de style S3. Vous pouvez créer une branche d’un lac de données pétaoctet en quelques millisecondes (c’est de la copie sur écriture), y mener une expérience, puis fusionner ou jeter. C’est une infrastructure qu’opère un laboratoire ou un centre de données, pas un outil par projet — utile à connaître pour le jour où vous rejoindrez un groupe qui travaille à cette échelle.

La pratique minimale viable¶

Vous n’avez besoin d’aucun de ces outils pour être en sécurité. Le plancher, atteignable avec ce que vous avez déjà :

Les données brutes sont immuables (section 5.1). Un répertoire, écrit une fois, jamais édité.
Les sommes de contrôle sont enregistrées. Un fichier SHA256SUMS, ou une somme de contrôle dans votre script de téléchargement, validé dans Git. Dès lors, « les données » sont un objet vérifiable, pas un nom de fichier.
Chaque jeu de données traité est (script + données brutes + paramètres), le tout sous Git. Régénérer vaut mieux que stocker. Là où la régénération est lente, stockez le produit et la recette.

Le dépôt de données de ce cours fonctionne exactement ainsi : les carnets récupèrent les fichiers avec pooch, qui prend une URL plus un known_hash et refuse de poursuivre si le téléchargement ne correspond pas :

import pooch
fname = pooch.retrieve(
    url="https://github.com/UW-MLGEO/MLGeo-dataset/raw/main/data/catalog.csv",
    known_hash="sha256:6f1c1a3f...",
)

Si le fichier change en amont, la vérification d’empreinte échoue bruyamment au lieu de laisser votre analyse changer en silence. Cet unique argument est un système de versionnage de données en miniature.

Versionner les modèles¶

Un modèle entraîné est un produit dérivé, comme un jeu de données traité : c’est (version du code + version des données + configuration + aléa). N’enregistrer que les poids jette la provenance. Enregistrez le paquet complet :

torch.save({
    "state_dict": model.state_dict(),
    "config": config,                    # architecture + training hyperparameters
    "data_version": "catalog v2.1, sha256:6f1c1a3f...",
    "code_version": "git 3f2a9c1",
    "metrics": {"val_f1": 0.83, "test_f1": None},   # test stays hidden until the end
    "seed": 42,
}, "models/detector_v1.2.0.pt")

Versionnez les modèles sémantiquement, comme du logiciel. Incrémentez la version majeure quand l’interface change (entrées ou sorties différentes — les consommateurs doivent s’adapter) ; la version mineure quand le comportement change mais pas l’interface (réentraînement sur de nouvelles données, nouvelle architecture, même tâche) ; la version corrective (patch) pour des correctifs qui ne devraient pas changer le comportement (bogue d’export, correction de métadonnées). « Le modèle », dans votre rapport, doit toujours désigner une version précise.

Fiches de modèle¶

Une fiche de modèle (model card) est une description courte et normalisée de ce à quoi sert un modèle et de là où il se casse — introduite par Mitchell et al. (2019, « Model Cards for Model Reporting », FAT* '19), et désormais attendue sur les plateformes de modèles. Dix lignes suffisent pour un projet de cours :

# Model card: detector_v1.2.0
- **Task**: P-wave arrival detection on 100 Hz, 3-component seismograms
- **Architecture**: 1-D CNN, 120k parameters (config in models/detector_v1.2.0.pt)
- **Training data**: catalog v2.1 (sha256:6f1c1a3f...), 2015-2022, Pacific Northwest
- **Metrics**: recall 0.92 at 1 false alarm/day on the hidden test set
- **Known limits**: recall drops to 0.60 below SNR 3; untested outside the PNW;
  not evaluated on borehole instruments
- **Intended use**: research catalog building. Not for earthquake early warning.
- **Contact / license**: mlgeo-team-4, MIT

Les lignes « known limits » et « intended use » sont celles qui comptent. Ce sont aussi celles qu’un agent ne peut pas écrire à votre place, parce qu’elles encodent un jugement sur ce que vous n’avez pas testé. Le chapitre 7.2 s’appuie là-dessus quand vous rédigerez la déclaration d’impact en aval de votre projet final.

L’intégration continue au service de la science : recopier le motif de ce livre¶

Le workflow de ce livre (.github/workflows/build.yaml) fait trois choses à chaque pull request :

Il recrée l’environnement épinglé avec prefix-dev/setup-pixi, à partir du pixi.lock validé (avec mise en cache, donc c’est rapide après la première exécution).
Il exécute tous les carnets via myst build --execute --html. Toute cellule qui lève une exception fait échouer la construction.
Il vérifie tous les liens (myst build --check-links), pour que les références aux données, aux articles et aux autres pages ne pourrissent pas en silence.

Pour recopier le motif dans un dépôt de projet, le workflow entier tient en une vingtaine de lignes :

name: ci
on: [pull_request, push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: prefix-dev/setup-pixi@v0.9.0
        with: { cache: true }
      - run: pixi run pytest tests -q
      - run: pixi run jupyter nbconvert --to notebook --execute notebooks/*.ipynb

Adaptez les deux dernières lignes à votre projet : tests unitaires de vos fonctions de traitement, exécution des carnets qui produisent vos figures. Gardez des temps d’exécution de carnet courts — utilisez un petit sous-ensemble de données ou une variable d’environnement SMOKE_TEST pour l’intégration continue, et lancez l’étude complète en dehors. Si votre flux ne peut pas se terminer en intégration continue, même sous forme réduite, il est bon de le savoir : cela signifie que personne, vous compris, ne peut le vérifier à bas coût.

Encore un motif issu de ce cours : la notation comme intégration continue. Le classement de la classe (exercice du chapitre 3.5) est un workflow qui exécute le prédicteur que vous avez soumis contre un ensemble de test caché et publie le score. La leçon générale se transpose à la recherche : chaque fois qu’un nombre compte — un banc d’essai, une entrée de classement, une métrique mise en avant — arrangez-vous pour qu’une machine, et non son auteur, le calcule.

Liste de contrôle¶

aucun fichier de plus de ~50 Mo n’est suivi directement dans Git
chaque jeu de données brutes a une somme de contrôle enregistrée (known_hash de pooch, SHA256SUMS, ou métafichier DVC)
chaque jeu de données traité peut être régénéré par un script validé
chaque modèle enregistré regroupe poids + configuration + version des données + métriques, et porte un numéro de version
les modèles qui quittent votre portable ont une fiche de modèle
l’intégration continue exécute le flux (ou un test de fumée réduit) à chaque pull request