060 — Proyecto: modelo trazable de extremo a extremo

← Clase anterior · Índice de la parte · Clase siguiente →

Parte: 04 — Redes neuronales y deep learning
Nivel: intermedio-avanzado · Horas estimadas: 10
Laboratorio: capstone · Estado: EXECUTABLE_CORE

🎯 Propósito

Comprender proyecto: modelo trazable de extremo a extremo dentro de la evolución de la inteligencia artificial, implementar un experimento mínimo verificable y distinguir qué parte constituye evidencia frente a una afirmación todavía no comprobada.

📚 Resultados de aprendizaje

Al finalizar podrás:

1. Explicar proyecto: modelo trazable de extremo a extremo usando los conceptos dataset card, model card, registro, despliegue.
2. Ejecutar el laboratorio con una semilla explícita y revisar su contrato JSON.
3. Identificar al menos un supuesto, una limitación y un riesgo de aplicación.
4. Comparar el enfoque con la etapa anterior de la ruta de aprendizaje.
5. Producir una evidencia reproducible y una conclusión que no exceda los datos.

🧩 Conceptos centrales

dataset card, model card, registro, despliegue

🗺️ Ubicación en el mapa de la IA

Cierre de la parte 04: todo lo anterior (arquitecturas, optimización, transferencia) solo tiene valor si el resultado es verificable por terceros. La crisis de reproducibilidad en ML (resultados que no se replican por semillas, datos o código no declarados) produjo un estándar emergente — dataset cards, model cards, registro de experimentos — que este proyecto practica de extremo a extremo y que la parte 05 asumirá como requisito al trabajar con LLM.

📖 Fundamentos

🧾 Trazabilidad: la cadena completa

Un modelo es trazable cuando cada afirmación sobre él puede seguirse hasta su origen:

datos crudos → transformaciones → splits → entrenamiento → checkpoint → métricas → decisión
     │               │              │           │              │           │
  versión         código         semilla     config        hash        protocolo

Si un eslabón no está registrado, la cadena se rompe: una métrica sin split declarado, o un checkpoint sin configuración, no son evidencia sino anécdota.

📇 Dataset cards y model cards

Datasheets for Datasets (Gebru et al., 2018): documento que responde, para un dataset: motivación, composición, proceso de recolección, preprocesamiento, usos recomendados y desaconsejados, sesgos conocidos. Model Cards (Mitchell et al., 2019): lo análogo para modelos — uso previsto, datos de entrenamiento, métricas desagregadas por subgrupos relevantes, condiciones de fallo conocidas y consideraciones éticas. Ambos son hoy práctica estándar (los hubs de modelos los integran) y la base de la documentación exigida por marcos regulatorios.

🔁 Reproducibilidad técnica

Fuentes de no determinismo y su control:

• Semillas: fijar las de todas las librerías (random, NumPy, framework) y registrarlas como parte del experimento.
• No determinismo de GPU: algunas operaciones CUDA son no deterministas por rendimiento; los frameworks ofrecen modos deterministas (más lentos) — la reproducibilidad bit a bit tiene coste y a veces se sustituye por reproducibilidad estadística (misma media ± varianza entre semillas).
• Entorno: versiones de librerías y drivers fijadas (lockfiles, contenedores).
• Datos: hash del dataset y de cada split; el data leakage entre train y test invalida silenciosamente todo lo demás.

📊 Protocolo de evaluación honesto

Decidir antes de mirar el test set: métrica principal (y por qué, dado el costo de cada tipo de error), baseline contra el que comparar (mayoría, regla simple, modelo anterior), splits (y si hay grupos —pacientes, usuarios— splits por grupo), y número de corridas con semillas distintas para reportar media ± desviación. El test set se toca una vez. Reportar también métricas desagregadas: un accuracy global puede esconder un fallo grave en un subgrupo.

🧮 Ejemplo trabajado

Evaluación trazable de un clasificador binario. Matriz de confusión sobre el test (tocado una única vez, split con semilla registrada 60):

                predicho +   predicho −
real +             TP=40        FN=20
real −             FP=10        TN=30

precisión = 40/(40+10) = 0.800
recall    = 40/(40+20) = 0.667
F1        = 2·(0.8·0.667)/(0.8+0.667) = 0.727
accuracy  = 70/100 = 0.700
baseline mayoritario (predecir siempre +): accuracy = 60/100 = 0.600

Lectura honesta: el modelo supera al baseline en accuracy (0.70 vs 0.60), pero deja escapar un tercio de los positivos (recall 0.667). Si el costo de un falso negativo es alto (p. ej. detección de fallos), esa cifra —no el accuracy— es la que decide, y así debe constar en la model card junto con: semilla, hash de los splits, configuración de entrenamiento y desviación entre corridas (p. ej. accuracy 0.70 ± 0.02 sobre 5 semillas). Con eso, un tercero puede reproducir y auditar la afirmación.

📊 Propiedades y comparación

flowchart LR
    D["datos crudos<br/>+ dataset card"] --> S["splits con semilla<br/>hash registrado"]
    S --> T["entrenamiento<br/>config + seed + commit"]
    T --> C["checkpoint<br/>hash del artefacto"]
    C --> E["evaluación<br/>protocolo predefinido"]
    E --> M["model card:<br/>métricas ± σ, límites, usos"]
    M --> G{"¿supera baseline<br/>y criterios?"}
    G -->|sí| R["registro y despliegue controlado"]
    G -->|no| I["iterar: nunca sobre el test set"]

⚠️ Errores conceptuales frecuentes

1. "Fijé la semilla, luego es reproducible." La semilla es un eslabón; sin versiones de entorno, hash de datos y config registrada, la cadena sigue rota.
2. "Elegí la mejor corrida de 20 para el informe." Eso es selección post-hoc: la estimación honesta es media ± desviación de todas, o una corrida nueva con protocolo prefijado.
3. "El accuracy global resume el modelo." Puede ocultar fallos por subgrupo y es engañoso con clases desbalanceadas (el baseline mayoritario ya da el 60 % aquí).
4. "Validar varias veces contra el test set está bien si no entreno con él." Cada mirada al test para tomar decisiones filtra información: es sobreajuste de selección, más lento pero igual de real.
5. "Las cards son burocracia." Son el contrato que permite a un tercero decidir si el modelo sirve para su caso; sin ellas, cada reutilización es un experimento a ciegas.

🚀 Del aprendizaje a la operación

En producción se añaden: registro de modelos con promoción por etapas (staging → producción), monitoreo de deriva de datos y de rendimiento en vivo, rollback automático ante degradación, auditoría de acceso a datos sensibles y revalidación periódica. La disciplina es la misma de esta clase; solo cambia la escala y que el "tercero que audita" puede ser un regulador.

🧪 Laboratorio

python lab.py

El laboratorio llama a ai_evolution.labs.run_lab("capstone"). Esta decisión evita 183 implementaciones divergentes: cada clase tiene un entrypoint propio, pero los motores didácticos se prueban como una biblioteca común.

🔍 Evidencia esperada

• tipo de laboratorio y semilla;
• entradas o decisiones observables;
• resultado estructurado;
• lista evidence con hechos que pueden inspeccionarse;
• lista limitations que impide presentar la demo como producción.

📓 Notebooks

• 📓 notebook.ipynb: recorrido guiado con la materia resumida.
• ✍️ notebook_student.ipynb: ejercicios para resolver.
• ✅ notebook_solution.ipynb: solución de referencia explicada.

📝 Evaluación

Consulta assessment.md para preguntas y criterio de aceptación.

⚠️ Errores comunes

❓ Preguntas frecuentes

¿Debo usar una API comercial?
No. El núcleo funciona localmente. Las extensiones LIVE se documentan por separado.

¿El laboratorio representa una implementación industrial?
No por sí solo. Enseña el contrato y el patrón; producción exige integración, seguridad, observabilidad, pruebas y operación.

¿Dónde profundizo?
Revisa las especializaciones enlazadas en el README raíz y la ruta siguiente.

🔗 Referencias

• Mitchell, M. et al. (2019). Model Cards for Model Reporting. arXiv:1810.03993 — uso: fuente primaria del mecanismo estudiado
• Gebru, T. et al. (2018). Datasheets for Datasets. arXiv:1803.09010 — uso: fuente primaria del mecanismo estudiado
• Pineau, J. et al. (2020). Improving Reproducibility in Machine Learning Research. arXiv:2003.12206 — uso: fuente primaria del mecanismo estudiado
• Notas oficiales de PyTorch sobre reproducibilidad y determinismo. pytorch.org/docs/stable/notes/randomness.html — uso: referencia consultada en su fuente original
• Documentación de MLflow (registro de experimentos y modelos). mlflow.org/docs/latest — uso: referencia consultada en su fuente original

📚 Bibliografía de apoyo

Bloque generado por python scripts/link_sources_to_classes.py. Cada obra lleva su localizador verificado en sources/bibliography.json.

Los papers dicen de dónde salió el mecanismo. Estas obras lo desarrollan con el espacio que una clase no tiene: teoría completa, demostraciones y ejercicios.

⬅️ Clase anterior

059 — Transferencia, fine-tuning y destilación

➡️ Siguiente clase

061 — Clasificación y representación visual

📝 Evaluación completa

❓ Preguntas

1. Define proyecto: modelo trazable de extremo a extremo sin usar una marca o framework como definición.
2. Explica la relación entre dataset card, model card, registro, despliegue.
3. Ejecuta lab.py dos veces con la misma semilla. ¿Qué debe conservarse?
4. Identifica una afirmación permitida y una afirmación exagerada sobre el resultado.
5. Propón una prueba negativa o un caso límite.

🏆 Reto verificable

Amplía el resultado del laboratorio con una clave student_extension que incluya:

• el supuesto que estás probando;
• una medición o comprobación;
• la conclusión;
• una limitación.

✅ Criterio de aceptación

• [ ] lab.py termina con código 0.
• [ ] El resultado contiene kind, seed, evidence y limitations.
• [ ] La extensión no modifica el comportamiento de otras clases.
• [ ] La interpretación referencia datos impresos por el laboratorio.
• [ ] Se declara al menos un riesgo o condición de no uso.