Perceptrón con PyTorch

Objetivo

Aprender tensores, autograd, optimizadores y un clasificador lineal.

Dataset real

• Dataset: banknote_authentication
• Fuente: UCI
• Referencia: https://archive.ics.uci.edu/dataset/267/banknote+authentication
• Licencia/condiciones: Consultar ficha UCI
• Uso: los datos se descargan desde la fuente; no hay ejemplos sintéticos ni archivos inventados.

Características extraídas de imágenes reales de billetes.

Fundamento matemático

z=xW+b; BCEWithLogitsLoss.

Protocolo experimental

1. Descargar y verificar la procedencia.
2. Conservar o crear una partición reproducible.
3. Ajustar transformaciones únicamente con train.
4. Seleccionar modelo e hiperparámetros usando validation.
5. Evaluar test una sola vez tras congelar la decisión.
6. Comparar con la línea base: Regresión logística.
7. Guardar configuración, entorno, métricas, predicciones, gráficos y modelo.

Ejecución

python labs/01_pytorch_perceptron/train.py --quick
python labs/01_pytorch_perceptron/train.py --config improved

Preparar únicamente el dataset:

python -m neural_labs.cli dataset --lab 01_pytorch_perceptron

Inferencia y exportación:

neural-labs predict --lab 01_pytorch_perceptron --run latest --input sample.json
neural-labs export --lab 01_pytorch_perceptron --run latest --format onnx --verify

Métricas

accuracy, balanced_accuracy, precision, recall, f1, roc_auc, pr_auc.

Archivos

• notebook.ipynb: recorrido completo y ejecutable.
• notebook_student.ipynb: actividades evaluables sin soluciones.
• notebook_solution.ipynb: resolución docente y pruebas de referencia.
• train.py: interfaz de terminal que usa el mismo código del cuaderno.
• configs/baseline.yaml: configuración base.
• configs/improved.yaml: configuración ampliada.
• data/dataset.yaml: procedencia, licencia y política de partición.

Ejercicios

• Cambiar una decisión experimental y justificarla.
• Analizar errores por clase o segmento.
• Comparar costo, precisión y latencia.
• Documentar sesgos, limitaciones y usos no recomendados.

Material formativo v3

• theory.md: fundamento, protocolo y riesgos de interpretación.
• experiments.md: hipótesis, variables controladas y tabla multi-semilla.
• assessment.md: preguntas y rúbrica de evaluación.
• lesson.yaml: resultados de aprendizaje, prerrequisitos y entregables.

Comandos profesionales

neural-labs quality --lab 01_pytorch_perceptron --quick
neural-labs benchmark --lab 01_pytorch_perceptron --quick --split-seed 42 --training-seeds 41 42 43
neural-labs leaderboard

Sellado del experimento

La partición se controla con split_seed; la inicialización y el entrenamiento con training_seed. El conjunto test se abre solamente después de seleccionar el checkpoint mediante validación y escribir experiment.lock.json.

🧠 Teoría

Teoría — Perceptrón con PyTorch

Propósito

Aprender tensores, autograd, optimizadores y un clasificador lineal.

Idea central

Este laboratorio estudia clasificador lineal con autograd usando banknote_authentication, un dataset público real procedente de UCI.

El salto respecto al laboratorio anterior no está en las matemáticas —seguimos entrenando esencialmente una neurona logística— sino en la ingeniería: en lugar de derivar los gradientes a mano, dejamos que PyTorch los construya automáticamente. Cada operación sobre un tensor con requires_grad=True se registra en un grafo de cómputo dinámico; al invocar loss.backward(), el motor autograd recorre ese grafo en sentido inverso aplicando la regla de la cadena y deposita en .grad exactamente las mismas derivadas que en el lab 00 escribimos manualmente.

El problema —distinguir billetes auténticos de falsos a partir de cuatro estadísticos extraídos por transformada wavelet de imágenes reales— es casi linealmente separable, lo que lo hace ideal para verificar que la maquinaria (tensores, Dataset/DataLoader, optimizador, bucle de entrenamiento) funciona antes de abordar problemas donde un solo hiperplano ya no basta. La pregunta crítica del laboratorio anticipa precisamente esa limitación.

Fundamento matemático

El modelo calcula un logit —una puntuación real sin normalizar— mediante una transformación afín de las entradas:

z = x·W + b

Nótese que ahora trabajamos con lotes (batches): x es una matriz de forma (N, d) y la multiplicación x·W produce un vector de N logits en paralelo, aprovechando el álgebra matricial vectorizada. La probabilidad se obtiene, igual que antes, con la sigmoide p = σ(z) = 1 / (1 + e⁻ᶻ), pero aquí introducimos una diferencia importante de estabilidad numérica.

En lugar de calcular σ(z) y luego la entropía cruzada por separado, PyTorch ofrece BCEWithLogitsLoss, que fusiona la sigmoide y la log-verosimilitud en una sola operación numéricamente estable. La razón es que combinar exponencial y logaritmo por separado desborda con logits grandes; la forma fusionada aplica el truco log-sum-exp:

L = (1/N) Σᵢ [ max(zᵢ, 0) − zᵢ·yᵢ + ln(1 + e^(−|zᵢ|)) ]

que es algebraicamente idéntica a −(1/N) Σᵢ [ yᵢ·ln σ(zᵢ) + (1−yᵢ)·ln(1−σ(zᵢ)) ] pero no produce ni ∞ ni NaN en los extremos. Por eso la buena práctica es que la última capa devuelva logits crudos y la pérdida se encargue internamente de la sigmoide.

La magia de autograd es que, definida L, no necesitamos escribir ∂L/∂W. El grafo sabe que ∂L/∂z = (σ(z) − y)/N y propaga hacia atrás por la regla de la cadena hasta ∂L/∂W = xᵀ·(σ(z) − y)/N. El optimizador (por ejemplo SGD o Adam) consume esos gradientes y actualiza los parámetros θ ← θ − η·∇_θ L, encapsulando la regla de actualización que en el lab 00 escribíamos línea por línea. El ciclo canónico es: optimizer.zero_grad() → loss.backward() → optimizer.step(); olvidar el zero_grad acumula gradientes de iteraciones previas, un error clásico que el laboratorio permite observar.

La formulación debe conectarse con cuatro elementos: representación de entrada, función del modelo, función de pérdida y regla de actualización. El notebook muestra las dimensiones de los tensores y conserva la misma implementación que el script de terminal.

Protocolo científico

• Ajustar transformaciones, vocabulario, normalización y selección de variables solo con train.
• Usar validation para arquitectura, hiperparámetros, checkpoint y umbrales.
• Evaluar test una vez, después de congelar las decisiones.
• Comparar contra Regresión logística.
• Reportar variación entre semillas e intervalos de confianza; una métrica puntual no expresa toda la incertidumbre.

Riesgos de interpretación

Características extraídas de imágenes reales de billetes.

El dataset refleja su proceso de recolección y no representa automáticamente otros períodos, países o poblaciones. Una asociación predictiva no demuestra causalidad.

Pregunta crítica

¿Qué ejemplos no puede separar un único hiperplano?

🔗 Referencias

Las referencias apuntan a las obras; no se reproduce su contenido, la redacción es original.

• Géron — Hands-On Machine Learning (3.ª ed., O'Reilly 2022), cap. 10 — introducción a redes con Keras/PyTorch, logits y funciones de pérdida.
• Goodfellow, Bengio & Courville — Deep Learning (MIT Press 2016), cap. 6 — redes hacia adelante, entropía cruzada y descenso de gradiente basado en grafos.
• Zhang et al. — Dive into Deep Learning (d2l.ai, 2023), cap. 3–5 — regresión lineal/softmax en frameworks modernos y mecánica de entrenamiento.
• Paszke et al. (2019), PyTorch: An Imperative Style, High-Performance Deep Learning Library, NeurIPS — diseño del framework y del motor de diferenciación automática.
• Documentación oficial de PyTorch (autograd) — https://pytorch.org/docs/stable/notes/autograd.html — grafo dinámico y semántica de backward().
• Fuente del dataset: https://archive.ics.uci.edu/dataset/267/banknote+authentication
• Consulte docs/experiment-protocol.md, docs/reproducibility.md y docs/ethics-and-licenses.md.

🔬 Experimentos

Plan de experimentos — Perceptrón con PyTorch

Hipótesis principal

Aprender tensores, autograd, optimizadores y un clasificador lineal. La hipótesis debe aceptarse o rechazarse comparando el modelo con Regresión logística y no solo observando que la pérdida disminuye.

Experimento mínimo

1. Ejecutar baseline.yaml con tres semillas.
2. Ejecutar improved.yaml con las mismas semillas.
3. Mantener fija la partición de datos dentro de cada semilla.
4. Elegir la variante con validation.
5. Comparar la variante elegida contra la línea base en test.
6. Revisar intervalos de confianza, errores y costo computacional.

Experimento específico

Verificar la frontera de decisión y el efecto de la normalización.

Variables controladas

• Dataset y política de partición.
• Semillas declaradas.
• Presupuesto de épocas y criterio de parada.
• Métrica de selección: accuracy o la especificada en la configuración.
• Hardware y versiones registradas en environment.json.

Tabla que debe completarse

Criterio de conclusión

La conclusión debe declarar magnitud de la mejora, incertidumbre, costo adicional, errores relevantes y condiciones bajo las cuales el resultado podría no repetirse.

📝 Evaluación

Evaluación — Perceptrón con PyTorch

Evidencias obligatorias

• Dataset preparado y auditoría sin solapamientos.
• Notebook ejecutado sin celdas omitidas.
• Línea base y modelo neuronal comparados.
• Resultados de al menos tres semillas o justificación del costo.
• Análisis de errores y limitaciones.
• Model card actualizada.

Preguntas

1. Explique con sus palabras: z=xW+b; BCEWithLogitsLoss.
2. ¿Qué información del dataset solo puede utilizarse durante entrenamiento?
3. ¿Por qué la línea base Regresión logística es una comparación razonable?
4. ¿Qué ejemplos no puede separar un único hiperplano?
5. ¿Qué cambiaría antes de usar este modelo fuera del laboratorio?

Rúbrica

La aprobación exige al menos 70% y cero errores críticos de fuga de datos.