Git para datos/notebooks
Los notebooks de Jupyter, las exportaciones de parquet y los checkpoints de modelos necesitan políticas de Git diferentes a las del código de aplicación: nbstripout, Git LFS y las herramientas de versionado de datos mantienen las PRs revisables y los repositorios pequeños.
Receta
pip install nbstripout
nbstripout --install --attributes
git add .gitattributes notebooks/analysis.ipynb
git commit -m "chore: strip notebook outputs on commit"Cuándo usar esto:
- Repositorios de ciencia de datos con exploración de
.ipynb - Equipos de ML que comparten notebooks que deben diferenciarse en las PRs
- Archivos Parquet/modelos demasiado grandes para objetos git normales
- Cumplimiento que requiere que la PII nunca esté en el historial de git
Ejemplo de trabajo
# Extracto de .pre-commit-config.yaml
repos:
- repo: https://github.com/kynan/nbstripout
rev: 0.7.1
hooks:
- id: nbstripout
# Rastrea artefactos grandes con LFS
git lfs install
git lfs track "*.parquet"
git lfs track "models/*.pt"
git add .gitattributes
git commit -m "chore: LFS track parquet and model weights"# Prefiere referenciar datos por URI en notebooks
DATA_URI = "s3://acme-analytics/processed/orders/dt=2026-07-08/"
# no: pd.read_csv("data/orders_10gb.csv") # confirmado en gitLo que esto demuestra:
- El hook nbstripout borra las salidas antes de confirmar
- Los punteros LFS reemplazan los blobs inflados en el historial de git
- Los notebooks referencian rutas de datos externas
.gitattributesdocumenta las reglas de filtro
Inmersión Profunda
Cómo funciona
- JSON de Notebook - Almacena código, metadatos y salidas. Las salidas cambian en cada ejecución, causando diffs enormes.
- nbstripout - Filtro git clean/smudge que elimina
outputsyexecution_count. - Git LFS - Almacena archivos grandes en el servidor LFS; el repo contiene archivos de texto puntero.
- DVC - Versiona datos en S3/GCS con pequeños archivos
.dvcen git.
Selector de Estrategia
| Activo | Estrategia |
|---|---|
| Notebooks | nbstripout + opcional Jupytext .py |
| Archivos de 10MB-5GB | Git LFS con monitorización de cuota |
| Datasets | DVC, rutas de partición en la nube, catálogo |
| Secretos en notebooks | Nunca - usa env + pydantic-settings |
Notas de Python
# Notebook emparejado con Jupytext
jupytext --set-formats ipynb,py:percent analysis.ipynb
git add analysis.ipynb analysis.pyErrores comunes
- Confirmar salidas una vez - Historial permanentemente inflado incluso después de nbstripout. Solución: filter-repo o BFG si se filtró; prevenir con hooks.
- Costos de ancho de banda de LFS - Las clones de CI descargan LFS. Solución:
GIT_LFS_SKIP_SMUDGE=1en CI que no necesita datos. - PII en CSV confirmado - Incidente GDPR. Solución: fixtures sintéticas en git; datos de producción en bucket de bóveda.
- Conflictos de fusión binarios en notebooks - Infierno JSON. Solución: eliminar salidas; un editor por archivo de notebook.
- DVC fuera de sincronización - Se extrajo la versión incorrecta de los datos. Solución: confirmar
.dvccon código;dvc pullen la documentación de CI. - Pickle en notebooks - Riesgo de ejecución de código arbitrario. Solución: parquet/JSON para intercambio.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Parámetros de Papermill | Ejecuciones programadas de notebooks | El código de biblioteca pertenece a módulos .py |
| Scripts Marimo / percent | Fuente amigable con Git primero | El equipo está estandarizado en Jupyter clásico |
| SageMaker / Colab solamente | Sin git local para notebooks | La organización requiere revisión de PR en git |
| Quarto | Pipeline de publicación de informes | Solo EDA interna rápida |
Preguntas frecuentes
¿nbstripout o borrar manualmente?
Automatizar con pre-commit - el borrado manual se olvida en cada confirmación.
¿LFS o DVC?
LFS para pocos binarios grandes en el repo; DVC para pipelines de datasets versionados y experimentos reproducibles.
¿Revisar PRs de notebooks?
Usa el diff de notebooks de GitHub o revisa .py emparejados de Jupytext para cambios legibles.
¿Ejecutar notebooks en CI?
papermill o nbclient con fixtures de datos fijadas - no datos de producción en vivo.
¿ipynb en paquete de biblioteca?
Evitar - mover la lógica a módulos src/; mantener notebooks en notebooks/ o docs/.
¿Límites del nivel gratuito de Git LFS?
Monitoriza el almacenamiento y el ancho de banda en GitHub - migra datos grandes al almacén de objetos cuando se excedan.
¿Conflictos de fusión en ipynb?
Vuelve a ejecutar nbstripout en ambos lados o elige el notebook de un autor y aplica las celdas manualmente.
¿Salidas de nbconvert en git?
No confirmes exportaciones HTML/PDF - genéralas en artefactos de CI.
¿Artefactos de wandb vs git?
Almacena artefactos de ejecución en W&B/S3; git rastrea solo el SHA del commit de entrenamiento y el YAML de configuración.
¿pre-commit lento en repo enorme?
Limita nbstripout solo a la ruta notebooks/ en la expresión regular files del hook.
Relacionado
- Conceptos básicos de ingeniería de datos - normas de pipelines
- Configuración de Git - configuración de hooks
- Lista de verificación de resolución de conflictos de fusión - conflictos de notebooks
- 30 Reglas de código de datos/ML - reglas del equipo
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.