English · Español

00 — Por qué el bucle de entrenamiento (training loop) es un ejercicio de corrección¶

La tentación en esta fase es tunear hiperparámetros. Es un error. El 90% del trabajo aquí es que el loop sea correcto y reproducible — batching, máscaras, reducción de pérdida (loss), schedule, checkpoints. Una vez correcto, los hiperparámetros son una tarde de barridos. Antes de ser correcto, los hiperparámetros son ruido sobre ruido.

La trampa¶

Cuando alguien abre "bucle de entrenamiento" en un tutorial, espera aprender cómo hacer mejor el modelo. Batches más grandes, mejor tasa de aprendizaje (learning rate), más warmup, schedules sofisticados, medias móviles exponenciales. Esta intuición es errónea en el sentido más importante: el trabajo de un bucle de entrenamiento es ser correcto, no óptimo.

Un loop correcto entrena el modelo que las matemáticas dicen que deberías estar entrenando. Un loop incorrecto entrena un modelo distinto — uno que es silenciosamente un 5% peor, o que diverge los martes, o cuyo checkpoint, al recargarse, predice logits ligeramente distintos. Cada minuto invertido en tunear un loop incorrecto se desperdicia. Cada fase posterior que se apoya encima (depurar dinámica en la 19, evaluar calidad en la 20, sampling en la 21, optimizar inferencia en la 22) queda envenenada por el cimiento.

La Fase 18 es una fase de corrección. El entregable es:

Un bucle de entrenamiento que has verificado personalmente que hace exactamente lo que dicen las matemáticas, con cada componente que mantiene estado (pesos, momentos del optimizador, paso del scheduler, RNG, iterador de datos) serializado y restaurable.

Los hiperparámetros vienen después. Ganar también.

Las cinco máquinas de estado¶

Un bucle de entrenamiento es el interleaving de cinco máquinas de estado:

El modelo. Parámetros \(\theta\). Actualizados una vez por paso.
El optimizador. AdamW mantiene \(m_t, v_t, t\) por parámetro. Actualizados una vez por paso.
El scheduler. Mantiene el paso actual \(t\) y la forma del schedule. Actualizado una vez por paso.
El iterador de datos. Mantiene la epoch actual + posición + semilla del RNG para el shuffle. Actualizado una vez por batch.
El RNG de control de entrenamiento. Usado para dropout, augmentation, sampling. Distinto del RNG del shuffle de datos.

Un checkpoint que solo guarda \(\theta\) es un checkpoint roto: recargarlo da el mismo modelo pero una trayectoria distinta del optimizador, una LR distinta, un siguiente batch distinto, un patrón de dropout distinto. El run de entrenamiento tras una recarga no es el mismo run que el run de entrenamiento antes. Este es el significado profundo de "recarga byte a byte" en la DoD: cada una de las cinco máquinas de estado se restaura, de modo que el run producido byte a byte a través de un límite de checkpoint coincide con el run que nunca checkpointeó.

Si puedes articular las cinco máquinas de estado y dónde vive cada una en tu loop, has pasado el filtro conceptual de la Fase 18.

Por qué el corpus de gramática verbal es el banco de pruebas adecuado¶

El corpus de la Fase 12 tiene 600 formas en total: 20 verbos × 5 tiempos × 3 personas, con pares inglés ↔ español. Tres propiedades lo convierten en el banco de pruebas adecuado para la Fase 18:

Suficientemente pequeño para que los bugs sean visibles. Si tu curva de pérdida tiene un bump de 0.3-ppl porque tu reducción de loss es sum y no mean, lo verás en 100 pasos, no en 10000. En un corpus de 1B tokens ese bump se esconde en el ruido.
Suficientemente estructurado para que el modelo pueda tener éxito. La rejilla (verbo × tiempo × persona) tiene regularidad interna — los verbos regulares siguen -ed, los irregulares no. Un loop correcto sobre un modelo diminuto visiblemente aprende el patrón. Un loop incorrecto se queda atascado.
La generalización held-out es significativa. Si dejas cuatro verbos fuera por completo, el modelo tiene que generalizar desde los demás. Esto es exactamente lo que prueba el harness de evaluación de la Fase 20, en forma previa, durante el entrenamiento: ¿baja la PPL en los verbos held-out, o solo en los verbos de train?

Estas tres propiedades son por qué el currículo ejecuta la Fase 18 sobre gramática, no sobre Shakespeare o Wikipedia. Necesitas ver los bugs del loop. Un corpus más grande los escondería.

Qué significa "batir la baseline" aquí¶

La baseline de n-gram de la Fase 14 es un modelo a nivel de token sin noción de "verbo" o "tiempo". Puntúa PPL sobre el val set por pura estadística de conteos. Sobre un corpus tan regular, la baseline de n-gram es en realidad bastante fuerte: los bigramas atrapan to + walk → walked, los trigramas atrapan la concordancia de persona (he + walk + s). Un transformer naive con una reducción de pérdida mala o una máscara que falta perderá contra la baseline de n-gram.

Ese es el punto. La DoD dice "batir la baseline". Si tu loop es correcto, la bates con una reducción de perplexity de ~30% (target val PPL aproximadamente 0.7× la baseline de n-gram). Si tu loop es incorrecto, no la bates, y el gate se niega a avanzar hasta que encuentres el bug. La baseline es un oráculo de corrección, no un objetivo vanidoso.

Lo que esta fase te pide interiorizar¶

Cinco hábitos no negociables de aquí en adelante:

Cada run de entrenamiento tiene un manifest. seed, versions, config, git_sha, data_manifest_hash. Confirmado antes de que el run empiece, no añadido a posteriori.
La reducción de pérdida es una elección y la escribes. "Reduzco con mean over (B, L) después de enmascarar el padding". Si no puedes decir cuál, tu pérdida no está haciendo lo que crees.
Los checkpoints son atómicos + tienen manifest. Sin ficheros .safetensors escritos a medias. Sin "ya añadiré la seed al JSON la próxima vez".
La precisión mixta es matemáticas primero, optimización segundo. Aprendes el rango dinámico de fp16 antes de aprender el truco del loss scaling.
Pickle nunca toca los pesos del modelo. Solo safetensors. El caso de higiene está en theory/04-checkpoints-and-mlflow.md y security/supply-chain.md.

Interioriza estos una vez en la Fase 18; cada fase posterior que toque entrenamiento los asume.

La forma de la fase¶

Teoría 01 es la más larga: batching, padding, attention masks, convenciones de reducción de pérdida. La mayoría de los bugs en bucles de entrenamiento viven en uno de esos cuatro. Léela dos veces.
Teoría 02 consolida las matemáticas del optimizador de la Fase 4 en la referencia de implementación — lo que re-derivarás de memoria cuando escribas loop.py.
Teoría 03 es el preview de precisión mixta. Corta, densa, sin entrenamiento real en precisión mixta. La Fase 26 aterriza la cosa real.
Teoría 04 es checkpoints + mlflow. El contenido práctico más corto pero el más relevante en seguridad: pickle está prohibido, y la razón es mecánica (es RCE).
Lab 00 ensambla batches desde el corpus de verbos.
Lab 01 corre el primer entrenamiento real y bate la baseline.
Lab 02 demuestra que el round-trip del checkpoint es bit-idéntico.
Lab 03 mide el drift de fp16.
Lab 04 conecta mlflow.

Planifica ~12–18 horas de estudio en 6–8 sesiones.

Detente aquí si¶

Te tienta empezar a codificar antes de leer theory/01. El bug más común de la Fase 18 — confundir reducción de pérdida por token, por secuencia y por batch — se arregla en 30 segundos si las matemáticas están frescas, y cuesta 6 horas de depuración si no lo están. Lee primero.

Lo que esta fase NO cubre¶

Tuning. Sin grid searches, sin Bayesian opt, sin barridos de hiperparámetros.
Entrenamiento real en precisión mixta. Preview solo forward. Backward en fp16 + loss scaling vive en la Fase 26.
Entrenamiento multi-GPU / distribuido. Fase 35.
Métricas de eval más allá de la perplexity. Fase 20. La Fase 18 usa PPL como oráculo de corrección (vs baseline de n-gram), no como medida de calidad.
Estrategias de sampling (top-k, top-p, etc.). Fase 21.
PyTorch. Fase 24. La Fase 18 usa NumPy puro + tensores minitorch hechos a mano.

Siguiente: theory/01-batching-loss-mask.md.