5.3 Control de versiones de datos y modelos - Machine Learning en las Geociencias

🖥️ Diapositivas — Sesión 27 (vie 4 dic)

Un experimento con seguimiento (sección 5.2) registra qué código produjo un número. Eso es solo la mitad de la procedencia. La otra mitad es qué datos y qué modelo. Esta página cubre ambos y luego muestra cómo conectar las verificaciones a la CI.

Control de versiones de datos¶

Por qué Git falla con los datos¶

Git almacena cada versión de cada archivo y calcula diferencias línea por línea. Ese diseño se rompe con los datos por tres vías. Primera, el tamaño: Git copia el contenido en cada clon, así que un archivo de formas de onda de 5 GB convierte cada git clone en una descarga de 5 GB, y diez versiones la convierten en cincuenta. Segunda, las diferencias: los formatos binarios (HDF5, Parquet, GeoTIFF, miniSEED) no producen diferencias con sentido, así que Git guarda copias casi completas por versión. Tercera, los límites de alojamiento: GitHub rechaza de plano los archivos de más de 100 MB. Los datos necesitan otro mecanismo; la buena noticia es que ese mecanismo todavía puede anclarse en Git.

Las herramientas, un párrafo cada una¶

git-lfs (Large File Storage) es el paso más pequeño hacia arriba: Git guarda un pequeño archivo apuntador, y el contenido real vive en un servidor LFS, que se descarga al hacer checkout. Mantiene intacto el flujo de trabajo de Git y funciona bien para un puñado de archivos medianos (pesos de modelos, un conjunto de datos de referencia). Se vuelve caro y lento en las decenas de gigabytes, y la cuota de LFS en GitHub es limitada.

DVC (Data Version Control) es git-lfs generalizado a conjuntos de datos y flujos de trabajo. dvc add data/raw/catalog.parquet escribe un diminuto metaarchivo .dvc (una suma de verificación más un tamaño) que usted confirma en Git; el contenido va a un remoto que usted elija — S3, GCS, un servidor del laboratorio, incluso Google Drive. dvc checkout materializa exactamente la versión de datos que corresponde al commit actual. DVC también describe flujos de trabajo (dvc.yaml): etapas con entradas y salidas declaradas, reejecutadas solo cuando cambian sus entradas.

lakeFS lleva la semántica de Git a un almacén de objetos: ramas, commits y fusiones sobre un bucket entero estilo S3. Usted puede crear una rama de un lago de datos de un petabyte en milisegundos (es copia al escribir), correr un experimento contra ella, y fusionarla o descartarla. Es infraestructura que opera un laboratorio o un centro de datos, no una herramienta por proyecto — conviene saber que existe para cuando se integre a un grupo que trabaje a esa escala.

La práctica mínima viable¶

Usted no necesita ninguna de estas herramientas para estar a salvo. El piso, alcanzable con lo que ya tiene:

Los datos crudos son inmutables (sección 5.1). Un directorio, se escribe una vez, nunca se edita.
Las sumas de verificación quedan registradas. Un archivo SHA256SUMS, o una suma de verificación en su script de descarga, confirmada en Git. Ahora «los datos» son un objeto verificable, no un nombre de archivo.
Cada conjunto de datos procesado es (script + datos crudos + parámetros), todo bajo Git. Regenerar le gana a almacenar. Donde la regeneración sea lenta, guarde el producto y la receta.

El repositorio de datos de este curso funciona exactamente así: los cuadernos obtienen archivos con pooch, que toma una URL más un known_hash y se niega a continuar si la descarga no coincide:

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

Si el archivo cambia río arriba, la verificación del hash falla ruidosamente en lugar de que su análisis cambie en silencio. Ese único argumento es un sistema de control de versiones de datos en miniatura.

Control de versiones de modelos¶

Un modelo entrenado es un producto derivado, como un conjunto de datos procesado: es (versión del código + versión de los datos + configuración + aleatoriedad). Guardar solo los pesos tira a la basura la procedencia. Guarde el paquete completo:

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")

Versione los modelos semánticamente, como se hace con el software. Suba la versión mayor cuando cambie la interfaz (entradas o salidas distintas — quienes lo consumen deben adaptarse); la versión menor cuando cambie el comportamiento pero no la interfaz (reentrenado con datos nuevos, arquitectura nueva, misma tarea); la versión de parche para correcciones que no deberían cambiar el comportamiento (error de exportación, corrección de metadatos). «El modelo», en su informe, debería significar siempre una versión específica.

Fichas de modelo¶

Una ficha de modelo (model card) es una descripción corta y estándar de para qué sirve un modelo y dónde se rompe — introducida por Mitchell et al. (2019, «Model Cards for Model Reporting», FAT* '19), y hoy esperada en los repositorios de modelos. Diez líneas bastan para un proyecto de curso:

# 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

Las líneas de «límites conocidos» y «uso previsto» son las que importan. También son las que un agente no puede escribir por usted, porque codifican un juicio sobre lo que usted no probó. El capítulo 7.2 se apoya en esto cuando usted redacte la declaración de impacto aguas abajo de su proyecto final.

CI para la ciencia: copiar el patrón de este libro¶

El flujo de trabajo de este libro (.github/workflows/build.yaml) hace tres cosas en cada pull request:

Recrea el entorno fijado con prefix-dev/setup-pixi, usando el pixi.lock confirmado (con caché, así que es rápido después de la primera corrida).
Ejecuta cada cuaderno mediante myst build --execute --html. Cualquier celda que lance una excepción hace fallar la construcción.
Revisa cada enlace (myst build --check-links), para que las referencias a datos, artículos y otras páginas no se pudran en silencio.

Para copiar el patrón a un repositorio de proyecto, el flujo de trabajo completo son unas veinte líneas:

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

Adapte las dos últimas líneas a su proyecto: pruebas unitarias para sus funciones de procesamiento, ejecución de los cuadernos que producen sus figuras. Mantenga cortos los tiempos de ejecución de los cuadernos — use un subconjunto pequeño de datos o una variable de entorno SMOKE_TEST para la CI, y corra el estudio completo fuera de ella. Si su flujo de trabajo no puede terminar en CI ni siquiera en forma reducida, eso vale la pena saberlo: significa que nadie, usted incluido, puede verificarlo de forma barata.

Un patrón más de este curso: la calificación como CI. La tabla de clasificación de la clase (ejercicio del capítulo 3.5) es un flujo de trabajo que ejecuta el predictor que usted entregó contra un conjunto de prueba oculto y publica el puntaje. La lección general se transfiere a la investigación: siempre que un número importe — una comparativa, una entrada en una tabla de clasificación, una métrica de titular — arregle las cosas para que lo calcule una máquina y no su autor.

Lista de verificación¶

ningún archivo de más de ~50 MB está rastreado directamente en Git
cada conjunto de datos crudo tiene una suma de verificación registrada (known_hash de pooch, SHA256SUMS o metaarchivo de DVC)
cada conjunto de datos procesado puede regenerarse con un script confirmado
cada modelo guardado empaqueta pesos + configuración + versión de los datos + métricas, y tiene un número de versión
los modelos que salen de su laptop tienen una ficha de modelo
la CI ejecuta el flujo de trabajo (o una prueba de humo reducida) en cada pull request