Necesitas: Docker Desktop corriendo, con ≈ 700 MB libres para las imágenes de RustFS y MLflow · Python 3.11 o más nuevo (se probó con 3.14.3) y ≈ 1.1 GB para el entorno virtual (PyTorch) · git (con tu nombre y correo configurados) · Internet la primera vez (los paquetes, las imágenes y Fashion-MNIST) · Los puertos 9500, 9501 y 5500 libres en tu Mac
Listo cuando: verificar.py mundo en verde: los buckets, los snapshots, el examen, classifier v1–v3 con @champion, los dos candidatos y git. Ya puedes practicar.
¿Algo falló al levantar? ↓
Ojo: El 5000 lo ocupa AirPlay en macOS: por eso MLflow está en el 5500 (y el S3 en 9500, para no chocar con las estaciones anteriores).
python3 -m venv .venv && source .venv/bin/activate · Tarda unos minutos la primera vez (PyTorch pesa ≈ 1 GB). Desde aquí, cada terminal nueva necesita source .venv/bin/activate.
SalidaSalida real · python3 -m venv .venv && source .venv/bin/activate
Python 3.14.3
1.1G
docker compose up -d --wait · La interfaz de MLflow queda en http://localhost:5500: ahí están las corridas del equipo y el modelo classifier.
git init && git add -A && git commit -m "kit recién descomprimido" · Los ids de commit cambian en cada máquina.
SalidaSalida real · git init && git add -A && git commit -m "kit recién descomprimido"
84a11de kit recién descomprimido
SalidaSalida real · python verificar.py mundo
✓ mundo S3 local (fotos, ml-datos con 4 snapshots y golden-v1) · MLflow: classifier v1–v3, @champion = v3, 2 candidatos · git
1/1 en verde
¿Ya está corriendo? Elige cómo practicar
las cuatro rondas
Cada ronda se trabaja en una sesión de Claude Code abierta en la carpeta del kit. Copia el prompt de la ronda y pégalo; el enlace de cada tarjeta te lleva a su sección en esta página. El CLAUDE.md del kit pone las reglas de fondo.
ConstruirRomperCon ayuda
1 · Construir con ayudaCon el Guiado de abajo: construyen juntos los pasos 1 a 6. Empieza aquí.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Construir con ayuda**.
Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a escribir juntos, siguiendo los pasos 0 a 6 de `GUION.md`, el gate que decide si el candidato de octubre puede reemplazar al de producción: leer las reglas y los parámetros de esta noche, evaluar a los tres modelos foto por foto sobre el examen congelado, la no inferioridad pareada, las categorías con McNemar y Holm, los slices y la calibración, un gate que frena de verdad y el registro del challenger.
Entre el paso 0 y el 1, `GUION.md` trae los «Precálculos»: las cuentas de servilleta de la estación. Pídeme que haga cada cuenta yo primero, corrígeme y después corre el comando que la comprueba (o dime en qué paso se va a confirmar).
En cada paso:
1. Dime el objetivo en una línea y explícame los conceptos que usa, rápido, con una analogía y con el término en inglés.
2. Escribe conmigo el archivo del paso, por bloques y con el porqué de cada uno. No me pegues el archivo entero de golpe. El contrato de arriba de cada archivo manda.
3. Dime qué comando correr y espera a que te pegue la salida. Los que cambian algo (`pipeline/gate.py`, `pipeline/registrar.py`, `mundo/modelos.py alias`, `git commit`, `git revert`) no los corras tú sin decírmelo antes.
4. Corre `python verificar.py <checks del paso>` y explícame el resultado. Cuando haya una corrida de gate o una versión nueva, ábrela conmigo en MLflow (http://localhost:5500): parámetros, tags, el reporte y los alias.
5. Anota el paso en la bitácora (sección «Bitácora» de `CLAUDE.md`) con lo que hice, lo que medí y lo que sigue.
Si algo falla, no lo arregles en silencio: muéstrame el error, dime tu hipótesis y arreglémoslo juntos. Al final, corre `python verificar.py` completo y cierra la ronda en `taller/progreso.json`.
3 · Romper con ayudaUna falla real; Claude te guía con preguntas.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Romper con ayuda**.
Lee `CLAUDE.md`. Todo pasa `python verificar.py`. Ahora:
1. Corre `python romper.py --mostrar` (o `--mostrar --falla <id>` si te digo cuál). El script mete la falla en el mundo, la configuración, el entorno o la infraestructura, nunca en mi pipeline, y te dice cuál fue. **A mí no me la digas.** Solo cuéntame la «historia»: qué notó alguien en el equipo.
2. Corre `python verificar.py` y pregúntame qué veo.
3. Guíame con preguntas en este orden: síntoma → hipótesis (pídeme al menos dos) → el comando que confirma o descarta cada una (`git log -p gate.yaml`, `git log -p corrida.yaml`, `git status`, `python mundo/modelos.py versiones`, `python mundo/modelos.py candidatos`, `python mundo/modelos.py gates`, `python mundo/s3.py golden`, `python mundo/s3.py versiones …`, `docker compose ps`, y mis propios `evaluar.py` y `gate.py`) → el arreglo. Si me atoro más de dos veces en el mismo punto, dame una pista concreta y anótala.
4. Cuando lo arregle, corre `python romper.py --verificar`. Ahí sí explícame qué era, el concepto detrás y cómo se vería en C01 de verdad (el golden set de 50,000 fotos, los umbrales en un PR de ml-catalogo, MLflow con Postgres y S3, el canary que mueve champion).
5. Anota en la bitácora la falla, cuánto tardé, cuántas pistas usé y qué aprendí.
Repetimos con otra falla hasta que te diga que paremos. Para volver al estado sano entre fallas: `python romper.py --restaurar`.
2 · Construir soloRehaces todo desde el esqueleto, solo con los objetivos de Solo.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Construir solo**.
Lee `CLAUDE.md`. **No leas `GUION.md`** ni `mundo/equipo.py`, y no me des código: esta ronda la escribo yo desde el esqueleto, con `OBJETIVOS.md` y los contratos de cada archivo como única guía.
Tu papel:
- Primero corre `python mundo/reiniciar.py --pipeline`: respalda mis archivos en `.respaldo/`, pone el esqueleto (`pipeline/evaluar.py`, `gate.py` y `registrar.py` con su contrato) y borra mis corridas de gate, las versiones que registré, el alias challenger y `reportes/` (el historial del registro, los candidatos y el examen se quedan). Confírmame qué se borró y haz conmigo el commit del esqueleto.
- Cuando te lo pida, corre `python verificar.py` (o un check suelto) y dime qué objetivo pasa y cuál no, con el mensaje exacto.
- Si te pregunto algo, contéstame con una pregunta que me acerque o con el concepto, nunca con el código ni con el arreglo. Si te digo «me rindo en este objetivo», ahí sí explícamelo, y anótalo en la bitácora como pista usada.
- Anota en la bitácora cada objetivo cuando pase: cuánto tardé y qué me costó.
Al final, con `python verificar.py` en verde, cierra la ronda en `taller/progreso.json`.
4 · Romper soloUna falla escondida; nadie te da pistas.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Romper solo**.
Lee `CLAUDE.md`. Todo pasa `python verificar.py`.
1. Corre `python romper.py` **sin** `--mostrar`. El script elige una falla al azar y la esconde; tú tampoco sabes cuál es, así que no intentes averiguarla leyendo `romper.py`, `.taller/` ni lo que cambió.
2. Dime solo la «historia» que imprime y la hora de inicio. Desde ahí trabajo yo solo: no me des pistas ni hipótesis. Si te pido correr un comando, córrelo y pégame la salida tal cual, sin interpretarla.
3. Cuando te diga «listo», corre `python romper.py --verificar`. Dime si quedó arreglado, cuál era la falla y cuánto tardé. Si no quedó, dime solo que no y sigo.
4. Si te digo «me rindo», corre `python romper.py --revelar` y explícame la falla completa.
5. Anota en la bitácora la falla, el tiempo, si me rendí y qué haría distinto.
El código que ves es el de la solución de referencia, y cada salida es la que salió al correr el kit en una carpeta limpia.
Precálculos. Antes de escribir el gate, las cuentas de servilleta: cuánto ruido tiene el examen (de ahí sale el margen), qué tan fina es la comparación foto por foto, cuánto ruido tiene una sola categoría, por qué hay que corregir cuando se hacen 10 pruebas a la vez, cuánto pesa la tabla de pares y cuánta erosión se puede colar. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.
1Las reglas y los parámetros de esta nocheSaber, antes de escribir código, contra quién se compara, con qué examen y con qué reglas.
El gate no decide nada que no esté escrito. corrida.yaml trae lo que resolvió el orquestador al arrancar: el candidato y los dos modelos de referencia, por número. gate.yaml trae las reglas: el examen y la huella de su manifest, contra quién se compara y cuánto puede moverse cada cosa. Fíjate en que no dice «el top-1 debe ser 85 %»: dice contra quién y cuánto. Un número absoluto envejece; una comparación contra el que ya está sigue teniendo sentido cada mes.
YAMLgate.yaml
# gate.yaml · las reglas del gate mensual de classifier. Las escribe el equipo ANTES de la corrida y cambian solo en# un PR propio que otra persona revisa (queda anotado en mundo/revisiones.json). Nunca después de ver un resultado.# Tu gate.py las lee de aquí: no copies estos números en el código.examen:
id: golden-v1 # el golden set congelado: s3://ml-datos/golden/golden-v1/ manifest_sha256: 0061343ada92972b0cd41d17ccb17cdd6751e6a3a3296034ad1bae2879355ae9
comparar_contra: [champion, hace_3_meses] # el de hoy y el de hace 3 meses (la defensa contra la erosión)top1_top5:
margen_puntos: 2.4# no inferioridad pareada: Δmin ≥ −2.4 puntos. Es el ruido de un modelo solo en# este examen: 1.96 × √(0.82 × 0.18 ÷ 1,000) × 100 ≈ 2.4 (en C01, con 50,000: 0.3)categorias:
caida_max_puntos: 5# una categoría está rota si su recall cae más de 5 puntos… alfa: 0.05# …y la caída es significativa: McNemar por categoría, corregido con Holmslices:
nombres: [normal, poca_luz, chica]
margen_puntos: 5# no inferioridad pareada por slice (con ≈ 200 fotos, el ruido es ≈ 5 puntos)ece_max: 0.05# calibración del candidato: error de calibración esperado, 15 cubetas
Del equipo. Sus versiones revisadas están en mundo/revisiones.json: el gate comprueba que la de hoy sea una de ellas.
Terminal
grep-v"^#" corrida.yaml
Salida
candidato: cand-2026-10-01 # la corrida de MLflow que dejó la estación 3
champion: 3 # classifier@champion al arrancar la corrida
hace_3_meses: 1 # el champion de julio: la defensa contra la erosión
examen: golden-v1 # el golden set congelado
Terminal
python mundo/modelos.py versiones
El historial del registro: tres meses, cada uno aprobado por su gate.
Salida
v1 — mes 2026-07 · corrida equipo-2026-07-01 · gate passed · labels.json en orden
v2 — mes 2026-08 · corrida equipo-2026-08-01 · gate passed · labels.json en orden
v3 @champion mes 2026-09 · corrida equipo-2026-09-01 · gate passed · labels.json en orden
Terminal
python mundo/modelos.py candidatos
Los dos candidatos de octubre están en el experimento de entrenamiento, sin registrar.
Listo cuando: Puedes decir en voz alta: candidato cand-2026-10-01, contra v3 y v1, con golden-v1 (1,000 fotos, huella 0061343a…) y margen de 2.4 puntos.
Ojo: Las «val_top1» de candidatos son de la validación de cada snapshot, que cambia de mes a mes: no sirven para comparar modelos de meses distintos. Para eso es el examen congelado.
Conceptos de este paso ↓
Gate de evaluaciónevaluation gateUn paso automático del pipeline que decide si un modelo puede avanzar, con reglas escritas antes. Si no se cumplen, el pipeline se detiene.Analogía, por qué importa y la trampa ↓
AnalogíaEl examen de manejo: hay una lista de cosas que tienes que hacer bien, escrita antes de que te subas al coche, y el examinador no la cambia porque le caíste bien.
Por qué importaSin gate, el modelo nuevo llega a producción porque «se ve bien» en una gráfica. Con gate, cada mes se aplica la misma regla, y el historial dice por qué pasó o no pasó cada modelo.
TrampaUn gate que solo mira el promedio global: una categoría rota se esconde detrás de 9 que mejoraron un poco.
Champion y challengerchampion / challengerChampion: el modelo que hoy atiende en producción. Challenger: el que pasó el gate y espera su turno (shadow y canary) para reemplazarlo.Analogía, por qué importa y la trampa ↓
AnalogíaEl campeón de box y el retador: el retador tiene que ganarse la pelea; no basta con decir que está mejor entrenado.
Por qué importaLos dos son alias en el registry, nombres que apuntan a una versión. Cambiar de modelo, o volver atrás, es mover un alias, no reentrenar.
TrampaMover champion a mano «porque ya lo probé en el notebook»: el alias se mueve, pero nadie aprobó ese modelo.
Versión por númeropinned versionEl gate recibe el champion como número (v3), resuelto una sola vez al arrancar, nunca como la pregunta «¿quién es champion?».Analogía, por qué importa y la trampa ↓
AnalogíaComparar contra «el récord de hoy» a media carrera es trampa: el récord puede cambiar mientras corres.
Por qué importaSi el alias se mueve a mitad de la corrida, las predicciones serían de un modelo y el veredicto contra otro. Con el número, el reporte dice exactamente contra quién se comparó.
TrampaRegistrar el veredicto de un gate que comparó contra un champion que ya no es champion: es un veredicto viejo.
Golden set (examen congelado)golden set / frozen test setUn conjunto fijo de fotos con etiquetas revisadas, que ningún entrenamiento ve y que no cambia. Se identifica por su id y por la huella (sha256) de su manifest.Analogía, por qué importa y la trampa ↓
AnalogíaEl metro patrón de París: si cada quien ajusta su metro, ya nadie mide lo mismo.
Por qué importaSolo con el mismo examen se pueden comparar modelos de meses distintos. Si se corrige algo, se publica golden-v2 en un PR propio y todos se vuelven a medir con él.
Trampa«Corregir» unas etiquetas del examen sin cambiarle el nombre: la comparación con los meses anteriores deja de valer y nadie lo nota.
Reglas escritas antespre-registered thresholdsLos umbrales del gate viven en un archivo versionado y cambian solo en un PR propio, revisado por otra persona, antes de la corrida.Analogía, por qué importa y la trampa ↓
AnalogíaLas reglas del partido se acuerdan antes del silbatazo, no al medio tiempo cuando vas perdiendo.
Por qué importaSi se pueden mover después de ver el resultado, cada mes habrá un argumento razonable para aflojar, y el gate deja de medir.
Trampa«Solo por esta vez»: el commit directo a main que afloja una regla para que salga el modelo de la semana.
Precálculo ↓
1
¿De qué tamaño es el margen de no inferioridad?
E = 1.96 × √(q × (1 − q) ÷ N) × 100, en puntos; el margen m es E redondeado
En C01q = 0.85, N = 50,000: 1.96 × √(0.85 × 0.15 ÷ 50,000) × 100≈ 0.31 → m = 0.3 puntos
En el dojoq = 0.82, N = 1,000: 1.96 × √(0.82 × 0.18 ÷ 1,000) × 100≈ 2.38 → m = 2.4 puntos
Qué decides con esto. El margen es lo que el examen ni siquiera puede medir de un modelo solo. Perder menos que eso es perder menos de lo que se ve. Con 1,000 fotos, el dojo solo puede proteger contra pérdidas de más de ≈ 2.4 puntos; C01, con 50,000, contra 0.3. Un examen más grande es un gate más fino.
Terminalterminal · compruébalo en el kit
python-c"
import math
for nombre, q, N in [('C01, golden de 50,000', 0.85, 50000), ('dojo, golden de 1,000', 0.82, 1000)]:
print(f'{nombre}: E = 1.96 × √({q} × {1 - q:.2f} ÷ {N:,}) × 100 = {196 * math.sqrt(q * (1 - q) / N):.2f} puntos')"
Salida
C01, golden de 50,000: E = 1.96 × √(0.85 × 0.15 ÷ 50,000) × 100 = 0.31 puntos
dojo, golden de 1,000: E = 1.96 × √(0.82 × 0.18 ÷ 1,000) × 100 = 2.38 puntos
2Evaluar a los tres, foto por fotoLas predicciones del candidato, del champion y del de hace 3 meses sobre el mismo examen, comprobando cada huella.
Antes de medir, se comprueba que lo que se mide es lo que se dice: el manifest del examen con la huella de gate.yaml y cada foto con la suya; los pesos de cada modelo con la huella de su corrida; su labels.json contra entrada/categorias.json; y que ninguna foto del examen esté en el snapshot con que se entrenó el candidato. Después, cada foto pasa por el preprocess del gateway y por los tres modelos, y se guarda por foto el top-5 y la confianza de cada uno: los pares.
Pythonpipeline/evaluar.py
"""Paso «evaluar» del gate: el candidato, el champion y el de hace 3 meses, sobre el mismo examen, foto por foto.
python pipeline/evaluar.py # los parámetros de corrida.yaml
python pipeline/evaluar.py --candidato <corrida> # otro candidato, con el mismo champion y el mismo examen
Contrato:
- Los modelos entran por NÚMERO de versión (corrida.yaml), nunca por alias: el alias puede moverse a media corrida.
- El examen es golden-v1: su manifest tiene que tener la huella que dice gate.yaml, y cada foto la suya. Si algo no
coincide, se detiene: un examen que cambió no compara nada.
- Ninguna foto del examen puede estar en el snapshot con que se entrenó el candidato (fuga = examen contaminado).
- Cada modelo: sus pesos tienen la huella que anotó su corrida, y su labels.json es entrada/categorias.json.
- Las fotos pasan por el preprocess del gateway (mundo/gateway/preprocess.py), el mismo de producción.
- Deja reportes/<candidato>/pares.parquet (una fila por foto: label, slice y, por modelo, su top-5 y su confianza)
y reportes/<candidato>/evaluacion.json (qué se evaluó, con sus huellas).
"""from __future__ import annotations
import argparse
import io
import json
import sys
import tempfile
from pathlib import Path
import numpy as np
import torch
from _comun import (CLASES, DATOS, EXP_ENTRENAMIENTO, FOTOS, MODELO, REPORTES, corrida, gate, huella_pesos, # noqa: F401
mlflow_cliente, s3, sha256)
from mundo.arquitectura import construir_modelo
from mundo.gateway.preprocess import preprocess
ap = argparse.ArgumentParser()
ap.add_argument("--candidato")
a = ap.parse_args()
cfg, g = corrida(), gate()
candidato = a.candidato or cfg["candidato"]
s = s3()
# 1 · El examen, con sus huellas
examen = g["examen"]
if cfg["examen"] != examen["id"]:
sys.exit(f"✗ corrida.yaml pide el examen {cfg['examen']} y gate.yaml dice {examen['id']}")
man_b = s.get_object(Bucket=DATOS, Key=f"golden/{examen['id']}/manifest.json")["Body"].read()
ifsha256(man_b) != examen["manifest_sha256"]:
sys.exit(f"✗ el manifest de {examen['id']} cambió: su sha256 es {sha256(man_b)[:12]}… y gate.yaml congeló "f"{examen['manifest_sha256'][:12]}…. Un examen que cambió no compara nada: no evalúo")
fotos = json.loads(man_b)["fotos"]
x = []
for f in fotos:
b = s.get_object(Bucket=DATOS, Key=f["image_key"])["Body"].read()
ifsha256(b) != f["image_sha256"]:
sys.exit(f"✗ la foto {f['id']} del examen no es la que se congeló (su sha256 no coincide): no evalúo")
x.append(preprocess(b))
x = torch.from_numpy(np.stack(x))
y = np.array([f["label_id"] for f in fotos])
print(f"[examen] {examen['id']}: {len(fotos)} fotos · manifest {sha256(man_b)[:12]}… = gate.yaml · cada foto con su huella")
# 2 · Los tres modelos, por número, con sus huellasimport mlflow # noqa: E402
c = mlflow_cliente()
exp = c.get_experiment_by_name(EXP_ENTRENAMIENTO)
rs = c.search_runs([exp.experiment_id], filter_string=f"tags.corrida = '{candidato}' and attributes.status = 'FINISHED'", max_results=1)
ifnot rs:
sys.exit(f"✗ no hay una corrida terminada que se llame {candidato} en {EXP_ENTRENAMIENTO}")
run_cand = rs[0]
defcargar(run_id: str, quien: str, huella: str | None):
with tempfile.TemporaryDirectory() as d:
carpeta = Path(mlflow.artifacts.download_artifacts(run_id=run_id, artifact_path="modelo", dst_path=d))
pesos = torch.load(carpeta / "pesos.pt", map_location="cpu", weights_only=True)
labels = json.loads((carpeta / "labels.json").read_text())
if labels != CLASES:
sys.exit(f"✗ el labels.json de {quien} no es entrada/categorias.json ({labels[:3]}…): la salida 0 no sería «{CLASES[0]}»")
ifhuella_pesos(pesos) != huella:
sys.exit(f"✗ los pesos de {quien} no tienen la huella que anotó su corrida: no sé qué estoy evaluando")
m = construir_modelo(len(CLASES))
m.load_state_dict(pesos)
return m.eval(), huella
modelos = {"candidato": cargar(run_cand.info.run_id, candidato, run_cand.data.tags.get("pesos_sha256"))}
versiones = {"candidato": None}
for quien in ("champion", "hace_3_meses"):
v = str(cfg[quien])
ifnot v.isdigit():
sys.exit(f"✗ corrida.yaml: {quien} = {v}. Entra como número de versión, no como alias")
mv = c.get_model_version(MODELO, v)
modelos[quien] = cargar(mv.run_id, f"{MODELO} v{v}", mv.tags.get("pesos_sha256"))
versiones[quien] = v
print(f"[modelos] {candidato} · champion = v{versiones['champion']} · hace 3 meses = v{versiones['hace_3_meses']} · ""pesos con su huella y labels.json en orden")
# 3 · Fuga: ¿alguna foto del examen está en el snapshot del candidato?
sid = run_cand.data.tags["snapshot"]
import pandas as pd # noqa: E402
filas = pd.read_parquet(io.BytesIO(s.get_object(Bucket=DATOS, Key=f"datasets/{sid}/rows.parquet")["Body"].read()))
vistas = set(filas["image_sha256"])
fuga = sum(f["origen_sha256"] in vistas or f["image_sha256"] in vistas for f in fotos)
if fuga:
sys.exit(f"✗ {fuga} fotos del examen están en {sid}, el snapshot con que se entrenó {candidato}: el examen está ""contaminado y el candidato saldría mejor de lo que es. No evalúo")
print(f"[fuga] 0 de {len(fotos)} fotos del examen están en {sid} ({len(filas):,} filas)")
# 4 · Las predicciones, foto por foto
pares = pd.DataFrame({"id": [f["id"] for f in fotos], "label_id": y, "slice": [f["slice"] for f in fotos]})
with torch.no_grad():
for quien, (m, _) in modelos.items():
p = torch.softmax(m(x), 1).numpy()
top5 = np.argsort(-p, 1, kind="stable")[:, :5]
pares[f"{quien}_top5"] = top5.tolist()
pares[f"{quien}_conf"] = p.max(1)
print(f" {quien:<13} top-1 {np.mean(top5[:, 0] == y):.2%} · top-5 {np.mean((top5 == y[:, None]).any(1)):.2%}")
out = REPORTES / candidato
out.mkdir(parents=True, exist_ok=True)
pares.to_parquet(out / "pares.parquet", index=False)
(out / "evaluacion.json").write_text(json.dumps({
"candidato": candidato, "candidato_run_id": run_cand.info.run_id, "snapshot": sid,
"champion_version": versiones["champion"], "hace_3_meses_version": versiones["hace_3_meses"],
"pesos_sha256": {k: v[1] for k, v in modelos.items()},
"examen": examen["id"], "manifest_sha256": sha256(man_b), "fuga": fuga,
"pares_sha256": sha256((out / "pares.parquet").read_bytes())}, ensure_ascii=False, indent=2) + "\n")
print(f"✓ {len(pares)} pares en reportes/{candidato}/pares.parquet")
Cada sys.exit es una razón para no evaluar: un examen que cambió, unos pesos que no son los anotados, unas categorías en otro orden o una fuga.
Terminal
python pipeline/evaluar.py
Salida
[examen] golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · cada foto con su huella
[modelos] cand-2026-10-01 · champion = v3 · hace 3 meses = v1 · pesos con su huella y labels.json en orden
[fuga] 0 de 1000 fotos del examen están en ds-2026-09-01 (8,523 filas)
candidato top-1 83.20% · top-5 99.70%
champion top-1 81.70% · top-5 99.50%
hace_3_meses top-1 73.80% · top-5 99.00%
✓ 1000 pares en reportes/cand-2026-10-01/pares.parquet
Terminal
python-c"import pandas as pd; print(pd.read_parquet('reportes/cand-2026-10-01/pares.parquet').head(3))"
Una fila por foto: su etiqueta, su slice y, por modelo, su top-5 y su confianza.
✓ examen golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · 0 fotos del examen en ds-2026-09-01
✓ pares 1000 pares · top-1 en golden-v1: candidato 83.2 %, champion v3 81.7 %, hace 3 meses v1 73.8 % · 20/20 predicciones del champion recalculadas iguales
✓ labels el labels.json de las 3 versiones y del candidato = entrada/categorias.json (sha 97864728052c…)
3/3 en verde
Listo cuando: 1,000 pares; top-1 en el examen: candidato 83.20 %, champion 81.70 %, hace 3 meses 73.80 %; 20 predicciones del champion recalculadas iguales.
Ojo: Sin model.eval(), la BatchNorm usa las estadísticas de cada lote y las predicciones cambian según con qué otras fotos venga cada una.
Conceptos de este paso ↓
Evaluación pareadapaired evaluationLos dos modelos responden las mismas fotos y se comparan foto por foto: b = solo el nuevo acierta, c = solo el viejo acierta.Analogía, por qué importa y la trampa ↓
AnalogíaDos cocineros preparan los mismos 1,000 platillos; para saber quién es mejor, solo importan los platillos en que uno acertó y el otro no.
Por qué importaLas fotos fáciles (los dos aciertan) y las imposibles (los dos fallan) no dicen nada; solo las discrepancias. Por eso la comparación pareada es más fina que comparar dos promedios.
TrampaGuardar solo «83.2 % vs 81.7 %»: sin los pares no hay prueba pareada, ni categorías, ni slices.
Fuga hacia el examendata leakage / test contaminationQue fotos del examen terminen en los datos de entrenamiento. El modelo ya vio las respuestas: sale mejor en el examen sin ser mejor.Analogía, por qué importa y la trampa ↓
AnalogíaEstudiar con el examen que te van a poner: sacas 10 y no aprendiste nada.
Por qué importaEl gate cruza las huellas del snapshot del candidato con las del examen y se detiene si hay una sola en común. La estación 2 deja el golden set fuera por diseño.
TrampaCelebrar un candidato que «sube 3 puntos» sin preguntar con qué datos se entrenó.
labels.json: el orden es parte del modelolabel mapLa lista que dice qué categoría es cada salida de la red: la salida 0 es «playeras», la 1 «pantalones»… Viaja con los pesos y se registra con su huella.Analogía, por qué importa y la trampa ↓
AnalogíaLas etiquetas de los frascos de la cocina: si las revuelves, el azúcar sigue siendo azúcar, pero le pones sal al café.
Por qué importaCon otro orden, los números del gate salen iguales (se evalúa por índice) y el gateway muestra otra categoría. Solo se nota si se compara el labels.json, o cuando cae la aceptación.
TrampaOrdenar las categorías alfabéticamente «para que se vea limpio».
Precálculo ↓
5
¿Cuánto pesa guardar las predicciones foto por foto?
filas = modelos × fotos; cada fila, el top-5 y la confianza
En C013 modelos × 50,000 fotos = 150,000 filas≈ 5–10 MB en Parquet
En el dojo1,000 fotos, una fila con las 3 columnas de cada modelo≈ 36 kB
Qué decides con esto. Guardar los pares es casi gratis, y sin ellos no hay prueba pareada, ni categorías, ni slices: solo dos promedios que no dicen en qué fotos discrepan. Se guardan siempre, con la corrida del gate.
Lo confirmas en el paso 2: reportes/cand-2026-10-01/pares.parquet pesa ≈ 36 kB.
3No inferioridad pareada, con reglas revisadasEl candidato no es peor que v3 ni que v1 por más de 2.4 puntos, en top-1 y en top-5, y las reglas son las aprobadas.
Primero, el gate comprueba sus propias reglas: gate.yaml en un commit y con una huella revisada. Después cuenta, contra cada modelo de comparar_contra, las fotos donde solo acierta el nuevo (b) y solo el otro (c): Δ = (b − c) ÷ N × 100, SE = √(b + c) ÷ N × 100 y Δmin = Δ − 1.96 × SE. Pasa si Δmin ≥ −2.4. Contra el de hace 3 meses es la misma regla: así se ataja la erosión.
Pythonpipeline/gate.py
# 1 · Las reglas: revisadas y en un commitifgit("status", "--porcelain", "--", "gate.yaml", "corrida.yaml"):
sys.exit("✗ gate.yaml o corrida.yaml tienen cambios sin commit: el veredicto no podría decir con qué reglas se tomó")
gate_sha = sha256((RAIZ / "gate.yaml").read_bytes())
if gate_sha notin {r["gate_yaml_sha256"] for r inrevisiones()}:
sys.exit(f"✗ gate.yaml ({gate_sha[:12]}…) no es ninguna versión revisada de mundo/revisiones.json: alguien cambió las ""reglas sin PR. No juzgo con reglas que nadie aprobó")
# 2 · Los pares de esta corrida
carpeta = REPORTES / candidato
ev = json.loads((carpeta / "evaluacion.json").read_text())
ifstr(ev["champion_version"]) != str(cfg["champion"]) or ev["examen"] != g["examen"]["id"]:
sys.exit(f"✗ los pares de {candidato} son contra champion v{ev['champion_version']} con {ev['examen']}, y esta corrida pide "f"v{cfg['champion']} con {g['examen']['id']}: vuelve a correr evaluar.py")
ifsha256((carpeta / "pares.parquet").read_bytes()) != ev["pares_sha256"]:
sys.exit("✗ pares.parquet no es el que dejó evaluar.py (su huella cambió)")
p = pd.read_parquet(carpeta / "pares.parquet")
y, N = p["label_id"].to_numpy(), len(p)
defacierta(quien: str, k: int) -> np.ndarray:
return np.array([t in top[:k] for t, top inzip(y, p[f"{quien}_top5"])])
defpareada(nuevo: np.ndarray, viejo: np.ndarray, margen: float) -> dict:
b, c, n = int((nuevo & ~viejo).sum()), int((~nuevo & viejo).sum()), len(nuevo)
d, se = (b - c) / n * 100, math.sqrt(b + c) / n * 100return {"b": b, "c": c, "n": n, "delta": round(d, 4), "se": round(se, 4), "delta_min": round(d - 1.96 * se, 4),
"pasa": bool(d - 1.96 * se >= -margen)}
defmcnemar(b: int, c: int) -> float:
"""McNemar exacto, de dos colas: si los dos modelos fueran igual de buenos, cada discrepancia es un volado."""
n = b + c
return1.0if n == 0elsemin(1.0, 2 * sum(math.comb(n, i) for i inrange(min(b, c) + 1)) / 2 ** n)
motivos, r = [], {"candidato": candidato, "champion_version": ev["champion_version"],
"hace_3_meses_version": ev["hace_3_meses_version"], "examen": ev["examen"], "gate_yaml_sha256": gate_sha}
# 3 · No inferioridad, top-1 y top-5, contra cada modelo de comparar_contra
m = g["top1_top5"]["margen_puntos"]
r["no_inferioridad"] = {}
for ref in g["comparar_contra"]:
for k in (1, 5):
x = pareada(acierta("candidato", k), acierta(ref, k), m)
r["no_inferioridad"][f"{ref}_top{k}"] = x
print(f"[no inferioridad] vs {ref:<12} top-{k}: b {x['b']:>3} · c {x['c']:>3} · Δ {x['delta']:+.2f} · "f"SE {x['se']:.2f} · Δmin {x['delta_min']:+.2f} {'≥' if x['pasa'] else '<'} −{m} → {'pasa' if x['pasa'] else 'NO PASA'}")
ifnot x["pasa"]:
motivos.append(f"top-{k} contra {ref}: Δmin {x['delta_min']:+.2f} < −{m}")
Las funciones acierta() y pareada() sirven también para categorías y slices.
✗ gate.yaml (d4d7fc2aa33b…) no es ninguna versión revisada de mundo/revisiones.json: alguien cambió las reglas sin PR. No juzgo con reglas que nadie aprobó
[código 1]
Terminal
git revert --no-edit HEAD
python pipeline/gate.py
Con las reglas revisadas de vuelta.
Salida
[no inferioridad] vs champion top-1: b 38 · c 23 · Δ +1.50 · SE 0.78 · Δmin -0.03 ≥ −2.4 → pasa
[no inferioridad] vs champion top-5: b 2 · c 0 · Δ +0.20 · SE 0.14 · Δmin -0.08 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-1: b 128 · c 34 · Δ +9.40 · SE 1.27 · Δmin +6.91 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-5: b 8 · c 1 · Δ +0.70 · SE 0.30 · Δmin +0.11 ≥ −2.4 → pasa
[categorías] la que más cae: playeras 87.4 → 84.5 (b 1 · c 4 · p de Holm 1) · rotas: ninguna
[slice] normal n 600 · Δ -0.50 · Δmin -2.26 → pasa
[slice] poca_luz n 210 · Δ +4.76 · Δmin +0.59 → pasa
[slice] chica n 190 · Δ +4.21 · Δmin +0.64 → pasa
[calibración] ECE 0.0238 ≤ 0.05
✓ PASA: cand-2026-10-01 es no inferior a v3 y a v1 · corrida gate-cand-2026-10-01
Terminal
python verificar.py no-inferioridad umbrales
Salida
✓ no-inferioridad vs champion: b 38 · c 23 · Δmin -0.03 · vs hace_3_meses: b 128 · c 34 · Δmin +6.91 (margen −2.4, top-5 también)
✓ umbrales gate.yaml = la revisión del PR #41 (2026-07-01) · sin cambios pendientes · 1 gate(s), todos con reglas revisadas
2/2 en verde
Listo cuando: Contra v3: b = 38, c = 23, Δmin = -0.03 ≥ −2.4. Contra v1 pasa con holgura. Y el gate se negó a correr con un gate.yaml sin commit o sin revisión.
Ojo: El candidato acierta 1.5 puntos más que el champion y aun así su Δmin es -0.03: con 61 discrepancias, el examen no puede asegurar que sea mejor, solo que no es peor. Para un reentrenamiento mensual, eso basta.
Conceptos de este paso ↓
No inferioridadnon-inferiority testPedir que el modelo nuevo no sea peor que el actual por más de un margen, con buena seguridad. No se le pide ganar.Analogía, por qué importa y la trampa ↓
AnalogíaUn medicamento genérico más barato: no tiene que curar más que el original, solo no curar menos por más de un margen chico.
Por qué importaEl reentrenamiento mensual busca estar al día, no ganar. Exigir «mejor de forma significativa» bloquearía casi todos los meses; exigir «≥ champion» decidiría con una moneda.
TrampaMirar el centro (Δ) en vez del extremo de abajo (Δmin): un Δ de −0.5 puede pasar o no según cuánto ruido haya.
Margen de no inferioridadnon-inferiority marginCuánto se acepta que el modelo nuevo pierda contra el actual. Se fija antes, del tamaño del ruido del examen: lo que el examen ni siquiera puede medir.Analogía, por qué importa y la trampa ↓
AnalogíaLa tolerancia de una báscula: si mide de ± 100 g, no tiene caso discutir por 50.
Por qué importaEn C01, 0.3 puntos (golden de 50,000). En el dojo, 2.4 (golden de 1,000). Es una decisión de negocio vestida de estadística: en C01, con ≈ 10 millones de fotos al día, 0.3 puntos son ≈ 30,000 primeras sugerencias equivocadas más al día.
TrampaElegirlo después de ver el resultado. Entonces ya no mide: justifica.
Error estándar e intervalostandard error / confidence intervalSE_Δ dice cuánto se movería la diferencia por azar con otras fotos. Δmin = Δ − 1.96 × SE es el extremo de abajo del intervalo de 95 %: lo peor que puede ser, con buena seguridad.Analogía, por qué importa y la trampa ↓
AnalogíaEl margen de error de una encuesta: «42 % ± 3» quiere decir que lo real está, casi seguro, entre 39 y 45.
Por qué importaLa regla del gate es Δmin ≥ −margen. Con pocas discrepancias el intervalo es estrecho; con muchas, ancho.
TrampaConfundir el SE de un modelo solo (el del margen) con el SE pareado (el de la diferencia): el segundo es más chico.
Erosión de calidadslow regressionPerder un poco cada mes, siempre dentro del margen: cada comparación pasa, y la suma de un año es grande.Analogía, por qué importa y la trampa ↓
AnalogíaLa rana en el agua que se calienta despacio: ningún grado de más se nota, la suma sí.
Por qué importaPor eso el gate compara también contra el champion de hace 3 meses: contra él se suman tres meses de pérdida, que no caben en el margen.
TrampaComparar solo contra el mes anterior y creer que eso protege del largo plazo.
Precálculos ↓
2
¿Qué tan fina es la comparación foto por foto?
SE_Δ = √(b + c) ÷ N × 100, donde b + c son las fotos en que los dos modelos discrepan
En C012,100 discrepancias de 50,000: √2,100 ÷ 50,000 × 100≈ 0.09 puntos (intervalo ± 0.18)
En el dojo61 discrepancias de 1,000 (b = 38, c = 23): √61 ÷ 1,000 × 100≈ 0.78 puntos (intervalo ± 1.53)
Qué decides con esto. Las fotos que los dos aciertan o los dos fallan no mueven la diferencia: solo cuentan las que discrepan. Por eso la comparación pareada es más fina que el margen y el gate puede leer pérdidas más chicas que el ruido de un modelo solo.
Lo confirmas en el paso 3: contra el champion salen b = 38 y c = 23, SE = 0.78.
6
¿Cuánta erosión se cuela si solo comparas contra el champion?
cada mes pasa si la pérdida r cumple r + 1.96 × SE_Δ ≤ m; en 12 meses se acumulan 12 × r
En C01r = 0.2 puntos al mes, SE_Δ ≈ 0.045: cada mes pasa; 12 × 0.22.4 puntos al año, sin un solo gate en rojo
En el dojom = 2.4, SE_Δ ≈ 0.78: pasa cada mes cualquier r ≤ 2.4 − 1.96 × 0.78≈ 0.9 puntos al mes
Qué decides con esto. Por eso el gate también compara contra el champion de hace 3 meses, con la misma regla: contra él se suman tres meses de pérdida, que ya no caben en el margen.
Lo confirmas en el paso 3: contra el de hace 3 meses (v1) el candidato está +9.4 puntos arriba; aquí no hubo erosión.
4Categorías, slices y calibraciónNinguna categoría rota, ningún slice abajo de su margen y la confianza del candidato calibrada.
Un promedio que no baja puede esconder una categoría rota. Por categoría, el gate pide dos cosas para declararla rota: que el recall caiga más de 5 puntos y que la caída sea significativa (McNemar con las discrepancias de esa categoría, corregido con Holm porque son 10 pruebas). Por slice, la misma no inferioridad pareada con un margen de 5 puntos (con ≈ 200 fotos, el ruido es de ese tamaño). Y la calibración: el ECE del candidato, con 15 cubetas de confianza, ≤ 0.05. Todo va al reporte y a una corrida de MLflow; si algo falla, la corrida queda FAILED y el proceso sale con código 1.
Pythonpipeline/gate.py
# 4 · Por categoría: caída grande Y significativa (McNemar + Holm)
cg = g["categorias"]
nuevo, viejo = acierta("candidato", 1), acierta("champion", 1)
cats = []
for i, nombre inenumerate(CLASES):
s = y == i
b, c = int((nuevo & ~viejo & s).sum()), int((~nuevo & viejo & s).sum())
cats.append({"categoria": nombre, "n": int(s.sum()), "recall_candidato": round(nuevo[s].mean() * 100, 2),
"recall_champion": round(viejo[s].mean() * 100, 2), "caida": round((viejo[s].mean() - nuevo[s].mean()) * 100, 2),
"b": b, "c": c, "p": mcnemar(b, c)})
orden = sorted(range(len(cats)), key=lambda i: cats[i]["p"]) # Holm: la p más chica contra α/10, la siguiente contra α/9…
maximo = 0.0for rango, i inenumerate(orden):
maximo = max(maximo, min(1.0, cats[i]["p"] * (len(cats) - rango))) # p ajustada, nunca menor que la anterior
cats[i]["p_holm"] = maximo
for x in cats:
x["rota"] = bool(x["caida"] > cg["caida_max_puntos"] and x["p_holm"] < cg["alfa"])
if x["rota"]:
motivos.append(f"categoría {x['categoria']}: recall {x['recall_champion']:.1f} → {x['recall_candidato']:.1f} "f"(−{x['caida']:.1f} puntos, p de Holm {x['p_holm']:.2g})")
r["categorias"] = cats
peor = max(cats, key=lambda x: x["caida"])
print(f"[categorías] la que más cae: {peor['categoria']} {peor['recall_champion']:.1f} → {peor['recall_candidato']:.1f} "f"(b {peor['b']} · c {peor['c']} · p de Holm {peor['p_holm']:.2g}) · rotas: {[x['categoria'] for x in cats if x['rota']] or 'ninguna'}")
# 5 · Slices
r["slices"] = {}
for nombre in g["slices"]["nombres"]:
s = (p["slice"] == nombre).to_numpy()
x = pareada(nuevo[s], viejo[s], g["slices"]["margen_puntos"])
r["slices"][nombre] = x
print(f"[slice] {nombre:<9} n {x['n']:>3} · Δ {x['delta']:+.2f} · Δmin {x['delta_min']:+.2f} → {'pasa' if x['pasa'] else 'NO PASA'}")
ifnot x["pasa"]:
motivos.append(f"slice {nombre}: Δmin {x['delta_min']:+.2f} < −{g['slices']['margen_puntos']}")
# 6 · Calibración: ¿su confianza dice la verdad?
conf = p["candidato_conf"].to_numpy()
cubeta = np.minimum((conf * 15).astype(int), 14)
ece = sum((cubeta == k).sum() / N * abs(nuevo[cubeta == k].mean() - conf[cubeta == k].mean()) for k inrange(15) if (cubeta == k).any())
r["ece"] = round(float(ece), 4)
print(f"[calibración] ECE {ece:.4f} {'≤' if ece <= g['ece_max'] else '>'} {g['ece_max']}")
if ece > g["ece_max"]:
motivos.append(f"ECE {ece:.4f} > {g['ece_max']}")
# 7 · El veredicto: en el reporte, en MLflow y en el código de salida
r["veredicto"], r["motivos"] = ("pasa"ifnot motivos else"no_pasa"), motivos
r["top1"] = {q: round(acierta(q, 1).mean() * 100, 2) for q in ("candidato", "champion", "hace_3_meses")}
(carpeta / "reporte.json").write_text(json.dumps(r, ensure_ascii=False, indent=2) + "\n")
import mlflow # noqa: E402
c = mlflow_cliente()
ifnot c.get_experiment_by_name(EXP_GATE):
c.create_experiment(EXP_GATE)
mlflow.set_experiment(EXP_GATE)
with mlflow.start_run(run_name=f"gate-{candidato}") as run:
mlflow.log_params({"candidato": candidato, "champion_version": ev["champion_version"], "hace_3_meses_version": ev["hace_3_meses_version"],
"examen": ev["examen"], "margen_puntos": m})
mlflow.log_metrics({f"delta_min_{k}": v["delta_min"] for k, v in r["no_inferioridad"].items()} | {"ece": r["ece"]} |
{f"top1_{q}": v for q, v in r["top1"].items()})
mlflow.set_tags({"candidato": candidato, "candidato_run_id": ev["candidato_run_id"], "champion_version": str(ev["champion_version"]),
"examen": ev["examen"], "manifest_sha256": ev["manifest_sha256"], "gate_yaml_sha256": gate_sha,
"commit": git("rev-parse", "HEAD"), "veredicto": r["veredicto"], "motivo": "; ".join(motivos)[:4000] or"—"})
mlflow.log_artifacts(str(carpeta), "reporte")
if motivos:
mlflow.end_run("FAILED")
if motivos:
sys.exit("✗ NO PASA: " + " · ".join(motivos))
print(f"✓ PASA: {candidato} es no inferior a v{ev['champion_version']} y a v{ev['hace_3_meses_version']} · corrida gate-{candidato}")
El último bloque decide: el veredicto va al reporte, a MLflow y al código de salida. sys.exit con un mensaje sale con código 1.
Terminal
python pipeline/gate.py # la misma corrida del paso 3
Salida
[categorías] la que más cae: playeras 87.4 → 84.5 (b 1 · c 4 · p de Holm 1) · rotas: ninguna
[slice] normal n 600 · Δ -0.50 · Δmin -2.26 → pasa
[slice] poca_luz n 210 · Δ +4.76 · Δmin +0.59 → pasa
[slice] chica n 190 · Δ +4.21 · Δmin +0.64 → pasa
[calibración] ECE 0.0238 ≤ 0.05
✓ PASA: cand-2026-10-01 es no inferior a v3 y a v1 · corrida gate-cand-2026-10-01
Terminal
python-c"
import json
r = json.load(open('reportes/cand-2026-10-01/reporte.json'))
for x in r['categorias']:
print(x['categoria'], x['n'], x['recall_champion'], '→', x['recall_candidato'], x['b'], x['c'], x['p'], x['p_holm'])"
Las 10 categorías del reporte (la salida es la del script de prueba, con columnas alineadas).
Salida
playeras n 103 · 87.4 → 84.5 · b 1 · c 4 · p 0.375 · Holm 1.000
pantalones n 105 · 95.2 → 96.2 · b 2 · c 1 · p 1.000 · Holm 1.000
sueteres n 82 · 79.3 → 76.8 · b 3 · c 5 · p 0.727 · Holm 1.000
vestidos n 99 · 75.8 → 79.8 · b 5 · c 1 · p 0.219 · Holm 1.000
abrigos n 102 · 65.7 → 66.7 · b 6 · c 5 · p 1.000 · Holm 1.000
sandalias n 117 · 89.7 → 92.3 · b 5 · c 2 · p 0.453 · Holm 1.000
camisas n 90 · 34.4 → 47.8 · b 13 · c 1 · p 0.002 · Holm 0.018
tenis n 108 · 95.4 → 96.3 · b 1 · c 0 · p 1.000 · Holm 1.000
bolsas n 99 · 93.9 → 93.9 · b 1 · c 1 · p 1.000 · Holm 1.000
botines n 95 · 92.6 → 90.5 · b 1 · c 3 · p 0.625 · Holm 1.000
Terminal
python verificar.py categorias slices
Salida
✓ categorias 10 categorías con McNemar + Holm · la que más cae: playeras (+2.9 puntos, p de Holm 1) · rotas: ninguna
✓ slices Δmin por slice: normal -2.26, poca_luz +0.59, chica +0.64 (margen −5) · ECE 0.0238 ≤ 0.05
2/2 en verde
Listo cuando: 10 categorías con McNemar y Holm, ninguna rota; los tres slices dentro de su margen; ECE ≤ 0.05.
Ojo: Camisas sube 13 puntos y su p es chica: McNemar también detecta mejoras. La regla solo frena caídas.
Conceptos de este paso ↓
Prueba de McNemarMcNemar's testPara dos modelos sobre las mismas fotos: si fueran igual de buenos, cada discrepancia sería un volado. La prueba da la probabilidad (p) de ver un reparto tan desigual de b y c por azar.Analogía, por qué importa y la trampa ↓
AnalogíaSi una moneda sale 21 veces cruz y 2 águila, sospechas que está cargada: es muy raro por azar.
Por qué importaSepara una categoría rota (camisas: 2 contra 21) del ruido (playeras: 1 contra 4). Usa solo las discrepancias de esa categoría.
TrampaUsarla con muy pocas discrepancias y concluir «no hay diferencia»: con 3 discrepancias, ninguna prueba puede ver nada.
Corrección de HolmHolm–Bonferroni correctionAl hacer k pruebas a la vez, ordena las p de menor a mayor y compara la primera contra α/k, la segunda contra α/(k − 1)… Así la falsa alarma de todo el conjunto queda en α.Analogía, por qué importa y la trampa ↓
AnalogíaSi compras 10 boletos de lotería, ganar uno ya no es tan sorprendente: hay que pedir más para creer que no fue suerte.
Por qué importaCon 10 categorías y α = 0.05 sin corregir, ≈ 40 % de los meses alguna «cae» por azar y el gate frena a un modelo sano.
TrampaNo corregir porque «cada prueba es al 5 %»: el 5 % es por prueba, no por gate.
Slicedata sliceUn pedazo del examen con algo en común: fotos con poca luz, fotos chicas, fotos del celular. Se evalúa aparte porque un promedio lo puede esconder.Analogía, por qué importa y la trampa ↓
AnalogíaUn restaurante con 4.5 estrellas que da intoxicación los martes: el promedio no lo dice, el corte por día sí.
Por qué importaEl candidato del proveedor no se ve tan mal en global (−1.3 puntos) y en poca luz su Δmin cae a −5.5: ahí es donde más se nota el lote malo.
TrampaUsar el margen global en un slice chico: con 200 fotos el ruido es ≈ 5 puntos, y el gate se pondría en rojo por azar.
Calibración (ECE)calibration / expected calibration errorSi el modelo dice «90 % seguro», ¿acierta 9 de cada 10? El ECE agrupa las fotos por confianza y promedia la distancia entre confianza y aciertos.Analogía, por qué importa y la trampa ↓
AnalogíaUn pronóstico del clima que dice «70 % de lluvia» y llueve 7 de cada 10 de esos días está bien calibrado.
Por qué importaProducto usa la confianza (por ejemplo, para pedir revisión humana debajo de un umbral). Un modelo que acierta igual pero dice «99 %» siempre rompe esa regla.
TrampaMirar solo la exactitud: dos modelos con el mismo top-1 pueden tener calibraciones muy distintas.
Precálculos ↓
3
¿Cuánto ruido tiene el recall de una sola categoría?
E = 1.96 × √(r × (1 − r) ÷ n) × 100, con n las fotos de esa categoría
En C01una de las 100 grandes, con ≈ 500 fotos y r = 0.85: 1.96 × √(0.85 × 0.15 ÷ 500) × 100≈ 3.1 puntos
En el dojo≈ 100 fotos por categoría y r = 0.85: 1.96 × √(0.85 × 0.15 ÷ 100) × 100≈ 7 puntos
Qué decides con esto. Una caída de 5 puntos en una categoría puede ser azar. Por eso la regla pide dos cosas: que caiga más de 5 puntos y que la caída sea significativa con McNemar, que usa los pares de esa categoría.
Terminalterminal · compruébalo en el kit
python-c"
import math
print(f'una categoría con 100 fotos y recall 0.85: E = 1.96 × √(0.85 × 0.15 ÷ 100) × 100 = {196 * math.sqrt(0.85 * 0.15 / 100):.1f} puntos')"
Salida
una categoría con 100 fotos y recall 0.85: E = 1.96 × √(0.85 × 0.15 ÷ 100) × 100 = 7.0 puntos
4
Si haces 10 pruebas a la vez, ¿cuántas falsas alarmas esperas?
P(al menos una falsa alarma) = 1 − (1 − α)^k, con k pruebas y α = 0.05
Qué decides con esto. Sin corregir, el gate frenaría a un modelo sano casi siempre: con 10 pruebas, 4 de cada 10 meses alguna «cae» por azar. La corrección de Holm vuelve a dejar la falsa alarma del gate completo en 5 %.
Terminalterminal · compruébalo en el kit
python-c"
for k in (10, 100):
print(f'{k} pruebas con α = 0.05 y ninguna diferencia real: P(al menos una falsa alarma) = 1 − 0.95^{k} = {1 - 0.95 ** k:.1%}')"
Salida
10 pruebas con α = 0.05 y ninguna diferencia real: P(al menos una falsa alarma) = 1 − 0.95^10 = 40.1%
100 pruebas con α = 0.05 y ninguna diferencia real: P(al menos una falsa alarma) = 1 − 0.95^100 = 99.4%
5El gate que frenaEl candidato del proveedor no pasa, la corrida queda en rojo y el motivo dice por qué.
El segundo candidato de octubre se entrenó con un lote del proveedor que etiquetó como «playeras» casi la mitad de las camisas. Se evalúa con el mismo champion y el mismo examen. El gate no «devuelve false»: termina con código 1 y su corrida en MLflow queda FAILED, con el motivo. Así el orquestador no sigue a los pasos de después y la alerta de pipeline fallido avisa a alguien.
[examen] golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · cada foto con su huella
[modelos] cand-2026-10-01-proveedor · champion = v3 · hace 3 meses = v1 · pesos con su huella y labels.json en orden
[fuga] 0 de 1000 fotos del examen están en ds-2026-09-01 (8,523 filas)
candidato top-1 80.40% · top-5 99.70%
champion top-1 81.70% · top-5 99.50%
hace_3_meses top-1 73.80% · top-5 99.00%
✓ 1000 pares en reportes/cand-2026-10-01-proveedor/pares.parquet
[no inferioridad] vs champion top-1: b 32 · c 45 · Δ -1.30 · SE 0.88 · Δmin -3.02 < −2.4 → NO PASA
[no inferioridad] vs champion top-5: b 2 · c 0 · Δ +0.20 · SE 0.14 · Δmin -0.08 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-1: b 110 · c 44 · Δ +6.60 · SE 1.24 · Δmin +4.17 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-5: b 8 · c 1 · Δ +0.70 · SE 0.30 · Δmin +0.11 ≥ −2.4 → pasa
[categorías] la que más cae: camisas 34.4 → 13.3 (b 2 · c 21 · p de Holm 0.00066) · rotas: ['camisas']
[slice] normal n 600 · Δ -1.83 · Δmin -3.82 → pasa
[slice] poca_luz n 210 · Δ -0.95 · Δmin -5.52 → NO PASA
[slice] chica n 190 · Δ +0.00 · Δmin -4.13 → pasa
[calibración] ECE 0.0299 ≤ 0.05
✗ NO PASA: top-1 contra champion: Δmin -3.02 < −2.4 · categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066) · slice poca_luz: Δmin -5.52 < −5
[código 1]
Terminal
python mundo/modelos.py gates
Abre la corrida roja en MLflow (experimento c01-gate): el reporte está en sus artefactos.
Salida
FINISHED 17:40 cand-2026-10-01 vs v3 · pasa · —
FAILED 17:40 cand-2026-10-01-proveedor vs v3 · no_pasa · top-1 contra champion: Δmin -3.02 < −2.4; categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066); slice poca_luz: Δmin -5.52 < −5
Terminal
python verificar.py frena
Salida
✓ frena cand-2026-10-01-proveedor: FAILED · top-1 contra champion: Δmin -3.02 < −2.4; categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066); slice poca_luz: Δmin -5.52 < −5 · ninguna versión suya dice gate=passed
1/1 en verde
Listo cuando: El gate del proveedor quedó FAILED y su motivo nombra camisas (p de Holm 0.00066), además del top-1 global y el slice de poca luz.
Ojo: Un gate que atrapa la excepción «para que el pipeline no truene» deja la corrida en verde, salta los pasos siguientes y nadie se entera de que no hubo challenger.
Concepto de este paso ↓
Fallar en rojofail loudlySi el gate no pasa, el paso termina con error (código de salida 1, corrida FAILED) y el pipeline se detiene y avisa. Nunca devuelve «false» y deja seguir.Analogía, por qué importa y la trampa ↓
AnalogíaUna alarma de incendio que en vez de sonar escribe una nota en un cuaderno: técnicamente detectó el fuego.
Por qué importaUn gate que «devuelve false» deja que los pasos siguientes se salten en silencio: la corrida queda en verde, no aparece ningún challenger y nadie se entera.
TrampaAtrapar la excepción del gate «para que el pipeline no truene».
6Registrar el challengerEl candidato que pasó, como una versión nueva de classifier con sus tags y el alias challenger; champion no se toca.
Registrar no es «subir el modelo»: es dejar escrito qué es y por qué pasó. registrar.py busca la última corrida de gate del candidato y se niega si no terminó en verde, si sus reglas no estaban revisadas, si el examen no es el de gate.yaml o si champion ya no es la versión contra la que se comparó (un veredicto viejo). Después crea la versión apuntando a los archivos de la corrida, con sus tags (gate, snapshot, huellas de pesos y de labels.json, examen, champion y Δmin) y le pone challenger. Correrlo dos veces no crea dos versiones.
Pythonpipeline/registrar.py
"""Paso «registrar»: el candidato que pasó el gate se vuelve una versión de classifier con el alias challenger.
python pipeline/registrar.py # el candidato de corrida.yaml
python pipeline/registrar.py --candidato <corrida>
Contrato:
- Solo registra si hay una corrida de gate TERMINADA (FINISHED) para ese candidato, con veredicto «pasa», contra el
champion de corrida.yaml, con un gate.yaml revisado y con el examen que dice gate.yaml. Si no, se detiene.
- Si champion ya no es la versión contra la que se evaluó, el veredicto es viejo: se detiene (hay que volver a evaluar).
- La versión apunta a los archivos de la corrida del candidato (runs:/<run_id>/modelo) y lleva sus tags: gate=passed,
gate_run_id, mes, snapshot, pesos_sha256, labels_sha256 (el de entrada/categorias.json), examen, champion_version,
y el Δmin contra el champion.
- Mueve challenger, nunca champion: champion lo mueve el despliegue cuando termina el canary (estación 10).
- Correrlo dos veces no crea dos versiones.
En C01 este paso va después de la estación 5 (paridad y latencia del engine). En el dojo no hay engine: registra aquí.
"""from __future__ import annotations
import argparse
import json
import sys
from _comun import CLASES, EXP_GATE, MODELO, corrida, gate, mlflow_cliente, revisiones, sha256
ap = argparse.ArgumentParser()
ap.add_argument("--candidato")
a = ap.parse_args()
cfg, g = corrida(), gate()
candidato = a.candidato or cfg["candidato"]
c = mlflow_cliente()
exp = c.get_experiment_by_name(EXP_GATE)
rs = c.search_runs([exp.experiment_id], filter_string=f"tags.candidato = '{candidato}'", max_results=1,
order_by=["attributes.start_time DESC"]) if exp else []
ifnot rs:
sys.exit(f"✗ {candidato} no tiene ninguna corrida de gate: corre evaluar.py y gate.py")
gr = rs[0]
t = gr.data.tags
if gr.info.status != "FINISHED"or t.get("veredicto") != "pasa":
sys.exit(f"✗ el último gate de {candidato} no pasó ({gr.info.status} · {t.get('motivo', '?')}): no se registra")
if t.get("gate_yaml_sha256") notin {r["gate_yaml_sha256"] for r inrevisiones()}:
sys.exit("✗ ese gate se tomó con un gate.yaml que nadie revisó: no cuenta")
if t.get("examen") != g["examen"]["id"] or t.get("manifest_sha256") != g["examen"]["manifest_sha256"]:
sys.exit("✗ ese gate usó otro examen que el de gate.yaml")
champion = c.get_model_version_by_alias(MODELO, "champion").version
if t.get("champion_version") != str(cfg["champion"]) orstr(champion) != str(cfg["champion"]):
sys.exit(f"✗ el gate comparó contra v{t.get('champion_version')}, y hoy champion es v{champion}: el veredicto es viejo. ""Vuelve a evaluar contra el champion de hoy")
run_id = t["candidato_run_id"]
cand = c.get_run(run_id)
ya = [mv for mv in c.search_model_versions(f"name = '{MODELO}'") if mv.run_id == run_id]
if ya:
mv = ya[0]
print(f" {candidato} ya era {MODELO} v{mv.version}")
else:
mv = c.create_model_version(MODELO, source=f"runs:/{run_id}/modelo", run_id=run_id, tags={
"gate": "passed", "gate_run_id": gr.info.run_id, "mes": "2026-10", "snapshot": cand.data.tags["snapshot"],
"pesos_sha256": cand.data.tags["pesos_sha256"], "labels_sha256": sha256((json.dumps(CLASES, ensure_ascii=False) + "\n").encode()), # = el labels.json de la corrida"examen": t["examen"], "champion_version": t["champion_version"],
"delta_min_champion_top1": str(gr.data.metrics["delta_min_champion_top1"])})
c.set_registered_model_alias(MODELO, "challenger", mv.version)
print(f"✓ {MODELO} v{mv.version} @challenger · gate {gr.info.run_id[:8]} · champion sigue en v{champion}")
✗ el último gate de cand-2026-10-01-proveedor no pasó (FAILED · top-1 contra champion: Δmin -3.02 < −2.4; categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066); slice poca_luz: Δmin -5.52 < −5): no se registra
[código 1]
Terminal
python pipeline/registrar.py
Salida
✓ classifier v4 @challenger · gate 06192ef5 · champion sigue en v3
Terminal
python pipeline/registrar.py
Otra vez: no duplica.
Salida
cand-2026-10-01 ya era classifier v4
✓ classifier v4 @challenger · gate 06192ef5 · champion sigue en v3
Terminal
python mundo/modelos.py versiones
Salida
v1 — mes 2026-07 · corrida equipo-2026-07-01 · gate passed · labels.json en orden
v2 — mes 2026-08 · corrida equipo-2026-08-01 · gate passed · labels.json en orden
v3 @champion mes 2026-09 · corrida equipo-2026-09-01 · gate passed · labels.json en orden
v4 @challenger mes 2026-10 · corrida cand-2026-10-01 · gate passed · labels.json en orden
Terminal
python verificar.py registro
Salida
✓ registro @champion = v3 · @challenger = v4 (cand-2026-10-01, gate 06192ef5 contra v3) · labels 97864728… · todo alias apunta a una versión con gate=passed
1/1 en verde
Terminal
python verificar.py
Salida
10/10 en verde
Listo cuando: classifier v4 @challenger con gate=passed y sus tags; @champion sigue en v3; los 10 checks en verde.
Ojo: Volver atrás (rollback) es mover el alias champion a la versión anterior: un comando, segundos. Por eso la versión vieja no se borra.
Concepto de este paso ↓
Registro de modelosmodel registryEl catálogo de modelos: cada versión (v1, v2…) apunta a sus archivos y nunca cambia; los alias (champion, challenger) se mueven; los tags guardan de dónde salió.Analogía, por qué importa y la trampa ↓
AnalogíaEl registro civil: cada acta tiene su número y no se reescribe; lo que cambia es quién ocupa qué puesto.
Por qué importaLa pregunta de la guardia a las 3 de la mañana, «¿qué modelo está sirviendo y de dónde salió?», se contesta con el alias y los tags, en un minuto.
TrampaCreer que los archivos de una corrida no cambian: en MLflow se pueden reemplazar. Por eso la versión guarda las huellas (pesos_sha256, labels_sha256).
Solo
10 objetivos
Empieza con python mundo/reiniciar.py --pipeline y haz commit del esqueleto.
Sin GUION.md: solo estos objetivos y el contrato arriba de cada archivo.
Cada objetivo tiene su check; corre python verificar.py <check> cuando creas que quedó.
Las reglas no se tocan: gate.yaml y corrida.yaml se quedan como vienen.
01El S3 local y MLflow arriba, el mundo creado y la carpeta en git.python verificar.py mundo
02Tu evaluación usa el examen congelado (manifest y fotos con su huella) y comprueba que no haya fuga.python verificar.py examenPista: ¿Dónde dice cuál es la huella correcta del examen?
03Los pares de los tres modelos, por número de versión, en el orden del manifest, con las predicciones de verdad.python verificar.py pares
04Todos los labels.json (versiones y candidato) son entrada/categorias.json.python verificar.py labels
05No inferioridad pareada en top-1 y top-5 contra champion y hace 3 meses: b, c y Δmin correctos.python verificar.py no-inferioridadPista: ¿Qué fotos cuentan para la diferencia?
07Δmin por slice y ECE del candidato.python verificar.py slices
08El gate del candidato del proveedor queda FAILED, con camisas en el motivo, y no se registra.python verificar.py frenaPista: ¿Qué código de salida ve el orquestador?
09Todos tus gates con un gate.yaml revisado, y sin cambios pendientes.python verificar.py umbrales
10El candidato bueno registrado como challenger, con sus tags; champion sigue en v3.python verificar.py registro
Romper
6 fallas
Con todo en verde, romper.py mete una falla en el mundo, la configuración o la infraestructura (nunca en lo que escribiste) y, si hace falta, deja corriendo lo que «pasó anoche». Tú empiezas por verificar.py.
Terminalromper.py
python romper.py --mostrar# con ayuda: Claude sabe cuál espython romper.py # solo: escondida, ni Claude la sabepython romper.py --verificar# ¿ya quedó?python romper.py --revelar# me rindopython romper.py --restaurar# deshacer
Catálogo de fallas (spoilers)El catálogo de abajo trae las respuestas. Ábrelo después de romper, para repasar.Abrir el catálogo
config
Reglas más flexibles, «solo por esta vez»
El equipo de búsqueda necesita que el modelo del proveedor salga esta semana. Alguien de ese equipo subió un commit a gate.yaml directo a main y avisó en el canal: «ya lo destrabé».
Síntoma. verificar.py: ✗ umbrales gate.yaml (24762d4eb7b2…) no es ninguna versión revisada (mundo/revisiones.json): git log -p gate.yaml
99aeff5 Equipo de búsqueda · gate: margen 4.0 y caída por categoría 25 (el modelo del proveedor tiene que salir esta semana)
- margen_puntos: 2.4 # no inferioridad pareada: Δmin ≥ −2.4 puntos. Es el ruido de un modelo solo en
+ margen_puntos: 4.0 # no inferioridad pareada: Δmin ≥ −2.4 puntos. Es el ruido de un modelo solo en
- caida_max_puntos: 5 # una categoría está rota si su recall cae más de 5 puntos…
+ caida_max_puntos: 25 # una categoría está rota si su recall cae más de 5 puntos…
✗ gate.yaml (24762d4eb7b2…) no es ninguna versión revisada de mundo/revisiones.json: alguien cambió las reglas sin PR. No juzgo con reglas que nadie aprobó
[código 1]
El arreglo. Un commit sin revisión dejó margen_puntos: 4.0 y caida_max_puntos: 25: con eso, el candidato del proveedor (camisas −21 puntos) pasaría. Tu gate se niega a juzgar con reglas cuya huella no está en mundo/revisiones.json. Arreglo: git revert --no-edit HEAD. Si de verdad hay que cambiar una regla, va en un PR propio, revisado, antes de la corrida siguiente, y nunca para que pase un modelo en particular.
El equipo de búsqueda revisó a mano el golden set y escribió en el canal: «había 30 etiquetas mal, ya las arreglé». El modelo nuevo ahora sale mejor.
Síntoma. verificar.py: ✗ examen el manifest de golden-v1 en S3 tiene sha256 3ca76bf3ca47… y gate.yaml congeló 0061343ada92…: alguien cambió el examen. python mundo/s3.py versiones golden/golden-v1/manifest.json
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Cambió el manifest del examen.
Cambió gate.yaml.
Cambiaron las fotos.
Terminalcómo confirmar
python mundo/s3.py golden
python mundo/s3.py versiones golden/golden-v1/manifest.json
python pipeline/evaluar.py
Salida
manifest sha256 3ca76bf3ca475d6e… · gate.yaml dice 0061343ada92972b… → DISTINTO
2026-11-17 23:37:11 336503 B version-id b1a0a269-8e78-4149-8b58-852db09d9d3d
2026-11-17 23:40:43 336580 B ACTUAL version-id 996a506c-429a-44ce-983f-6e561faeb277
✗ el manifest de golden-v1 cambió: su sha256 es 3ca76bf3ca47… y gate.yaml congeló 0061343ada92…. Un examen que cambió no compara nada: no evalúo
[código 1]
El arreglo. El manifest de golden-v1 tiene 30 etiquetas cambiadas y su huella ya no es la de gate.yaml: un examen que cambia deja de comparar con los meses anteriores. El bucket tiene versionado: python mundo/s3.py restaurar golden/golden-v1/manifest.json <version-id de la primera> devuelve el examen congelado. Si de verdad había etiquetas malas, se publica golden-v2 en un PR propio y todos los modelos se vuelven a medir con él.
29617d3 Equipo de búsqueda · corrida: el candidato es cand-2026-10-01-r2 (reentrenado con más datos, sube 3 puntos)
FINISHED cand-2026-10-01-r2 ds-2026-09-15 val_top1 0.8596 pesos cc82a8452300
"parent": "ds-2026-09-01",
"total": 9523
"nota": "Reconstruido a mano por el equipo de búsqueda «con todas las fotos etiquetadas que había»."
[examen] golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · cada foto con su huella
[modelos] cand-2026-10-01-r2 · champion = v3 · hace 3 meses = v1 · pesos con su huella y labels.json en orden
✗ 1000 fotos del examen están en ds-2026-09-15, el snapshot con que se entrenó cand-2026-10-01-r2: el examen está contaminado y el candidato saldría mejor de lo que es. No evalúo
[código 1]
El arreglo. El candidato nuevo se entrenó con ds-2026-09-15, un snapshot armado a mano que trae las 1,000 fotos del examen: ya vio las respuestas. Tu evaluar.py cruza las huellas y se detiene. Arreglo: git revert --no-edit HEAD (vuelve el candidato del pipeline) y pedir que el snapshot se reconstruya con el pipeline de la estación 2, que deja fuera el golden set por diseño.
Esta mañana el equipo de búsqueda escribió: «subimos el modelo del proveedor a producción, ya lo probamos en el notebook». La aceptación de sugerencias de camisas se cayó.
Síntoma. verificar.py: ✗ registro classifier@champion = v5, y la corrida de esta noche es contra v3: ¿quién lo movió? python mundo/modelos.py versiones
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Alguien movió champion.
Se registró una versión que nadie aprobó.
El gate dejó pasar al proveedor.
Terminalcómo confirmar
python mundo/modelos.py versiones
Salida
v1 — mes 2026-07 · corrida equipo-2026-07-01 · gate passed · labels.json en orden
v2 — mes 2026-08 · corrida equipo-2026-08-01 · gate passed · labels.json en orden
v3 — mes 2026-09 · corrida equipo-2026-09-01 · gate passed · labels.json en orden
v4 @challenger mes 2026-10 · corrida cand-2026-10-01 · gate passed · labels.json en orden
v5 @champion mes 2026-10 · corrida cand-2026-10-01-proveedor · gate — · labels.json en orden
El arreglo. Alguien registró a mano el candidato del proveedor (sin gate=passed) y le movió @champion: eso ya es producción. El registro no impide mover un alias; la regla de que solo CD lo mueve, después del gate y del canary, es del equipo. Arreglo: python mundo/modelos.py alias champion 3. El rollback es mover el alias, no reentrenar. La versión mal subida se queda sin alias y sin gate=passed.
El equipo de plataforma estrenó un script que «limpia» los artefactos de las corridas. Lo corrieron sobre el candidato de octubre anoche.
Síntoma. verificar.py: ✗ labels el labels.json de v4, cand-2026-10-01 no es entrada/categorias.json: la salida 0 dejaría de ser «playeras». python mundo/modelos.py versiones
✗ registro v4: su labels_sha256 o su labels.json no es el de entrada/categorias.json
✗ labels el labels.json de v4, cand-2026-10-01 no es entrada/categorias.json: la salida 0 dejaría de ser «playeras». python mundo/modelos.py versiones
0/1 en verde · falta: labels
[examen] golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · cada foto con su huella
✗ el labels.json de cand-2026-10-01 no es entrada/categorias.json (['abrigos', 'bolsas', 'botines']…): la salida 0 no sería «playeras»
[código 1]
El arreglo. El modelo/labels.json de la corrida cand-2026-10-01 se sobrescribió en orden alfabético: los archivos de una corrida de MLflow se pueden reemplazar. Los pesos son los mismos, así que la evaluación por índice saldría igual, pero registrado así el gateway mostraría otra categoría. Por eso la versión guarda labels_sha256. Arreglo: python mundo/modelos.py labels cand-2026-10-01 y otra vez evaluar.py.
mlflow: exited · Exited (137) 4 seconds ago
s3: running · Up 6 minutes (healthy)
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=5500): Max retries exceeded with url: /api/2.0/mlflow/experiments/get-by-name?experiment_name=c01-entrenamiento (Caused by NewConnectionError("HTTPConnection(host='localhost', port=5500): Failed to establish a new connection: [Errno 61] Connection refused"))
mlflow.exceptions.MlflowException: API request to http://localhost:5500/api/2.0/mlflow/experiments/get-by-name failed with exception HTTPConnectionPool(host='localhost', port=5500): Max retries exceeded with url: /api/2.0/mlflow/experiments/get-by-name?experiment_name=c01-entrenamiento (Caused by NewConnectionError("HTTPConnection(host='localhost', port=5500): Failed to establish a new connection: [Errno 61] Connection refused"))
real 5.32
El arreglo. El contenedor de MLflow está detenido. Sin el registro no hay champion por número ni candidato, y el gate no puede anotar su veredicto: falla en segundos, y está bien que falle. Un gate que «pasa» porque no pudo medir es peor que uno en rojo. Arreglo: docker compose up -d --wait mlflow.
El gate decide si vale la pena probar; el canary, si se queda.Reglas escritas antes (y cambiadas solo en un PR), el champion por número, el mismo examen congelado y los pares foto por foto. No inferioridad contra el champion y contra el de hace 3 meses, cada categoría y cada slice aparte, y si algo falla, en rojo. Promover y volver atrás es mover un alias.Trampa: Mover los umbrales después de ver el resultado («el slice cayó 6, subo el límite a 7»). El gate deja de medir y empieza a justificar.Listo cuando
El candidato es no inferior al champion y al de hace 3 meses (Δmin ≥ −margen, en top-1 y top-5), sobre el examen congelado y sin fuga.
Ninguna categoría cae más de 5 puntos con una caída significativa (McNemar + Holm), ningún slice cae más que su margen y el ECE está en su límite.
Las reglas eran las revisadas, y el champion entró por número.
Un candidato que rompe una categoría deja la corrida en rojo, con el motivo, y no se registra.
El candidato que pasó es una versión con gate=passed, sus huellas y el alias challenger; champion no se movió.
Sabes qué versión es champion y a cuál vuelves si algo falla.
Así te lo pueden preguntar en una entrevista
¿Cómo decides si el modelo reentrenado puede reemplazar al de producción?
Con un gate automático y reglas escritas antes: los dos modelos sobre el mismo golden set congelado, foto por foto. No inferioridad pareada (el extremo de abajo del intervalo de la diferencia ≥ −margen, con el margen del tamaño del ruido del examen), también contra el modelo de hace 3 meses por la erosión. Además, recall por categoría con McNemar y Holm, slices y calibración. Si pasa, se registra como challenger; el champion se mueve después del canary.
¿Por qué no inferioridad y no «que sea mejor»?
Porque el reentrenamiento mensual busca estar al día, no ganar. Exigir una mejora significativa bloquearía casi todos los meses, y «≥ champion» decide con el ruido: dos modelos iguales salen uno arriba del otro la mitad de las veces. La no inferioridad acepta perder menos de lo que el examen puede medir.
El top-1 global subió, pero una categoría grande se rompió. ¿Cómo lo atrapas?
Recall por categoría contra el champion con los pares de esa categoría: McNemar exacto con sus discrepancias, corregido con Holm porque son muchas pruebas, y además un tamaño mínimo de caída para que importe. Más slices: luz, tamaño, dispositivo.
¿Qué guarda la versión del registry?
Apunta a los artefactos (pesos, labels.json) y lleva tags: gate=passed y la corrida del gate, snapshot, commit, huellas de pesos y de labels.json, examen, contra qué champion se comparó y sus métricas. El alias challenger. Y nunca cambia: lo que se mueve son los alias.
Alguien quiere aflojar un umbral porque el modelo de esta semana no pasa. ¿Qué haces?
No lo muevo para este modelo. Si hay un argumento, va en un PR propio, revisado, que aplica desde la corrida siguiente, con la justificación (por ejemplo, el examen creció y el ruido bajó). Un override para una corrida concreta pide dos personas y deja un tag.
¿Cómo sabes que el examen no está contaminado?
El golden set se congela con un manifest y su huella, se excluye de todos los snapshots por diseño, y el gate cruza las huellas de las fotos del examen con las del snapshot del candidato antes de evaluar: una sola coincidencia detiene todo.
Versión del contenido: 17 de noviembre de 2026.
Contexto opcional
para consultar
Dónde estás en el pipeline
La estación 3 deja un checkpoint candidato con su corrida en MLflow. Esta decide si puede reemplazar al modelo que hoy atiende en producción (el champion), y no lo decide una persona viendo una gráfica: lo decide un gate, un paso automático del pipeline con reglas escritas antes de la corrida. El gate evalúa al candidato, al champion y al champion de hace 3 meses sobre el mismo examen congelado (el golden set), foto por foto. Pide que el candidato no sea peor por más de un margen (no inferioridad), que ninguna categoría se rompa, que ningún slice caiga y que su confianza diga la verdad. Si algo no se cumple, el pipeline se pone en rojo. Si todo pasa, el candidato queda en el registry como una versión nueva con el alias challenger. champion se mueve después, cuando termina el canary.
Entra
el checkpoint candidato: la corrida de MLflow que dejó la estación 3
el champion y el de hace 3 meses, por su número de versión (los resolvió el orquestador al arrancar)
el golden set congelado, con la huella de su manifest
las reglas del gate (gate.yaml), revisadas en un PR antes de la corrida
→4→
Sale
las predicciones de los tres modelos, foto por foto (los pares)
el reporte del gate: veredicto, motivo, no inferioridad, categorías, slices y calibración, en una corrida de MLflow
si pasa: una versión nueva de classifier con el alias challenger y sus tags; si no, una corrida roja que frena el pipeline
El escenario del proyecto
Con kit · 4 rondas
El kit trae el marketplace de C01 el 1 de octubre de 2026, a las 05:00 UTC: el entrenamiento del mes ya terminó y el pipeline llega al gate. En el S3 local están las fotos, los snapshots de junio a septiembre y el examen congelado golden-v1. En MLflow está el historial del registro (julio, agosto y septiembre, que hoy es champion) y dos candidatos de octubre: el bueno y uno entrenado con un lote de etiquetas malo del proveedor. Tú escribes el gate: evaluar a los tres modelos foto por foto, aplicar las reglas y registrar al challenger. Todo corre con un entorno virtual de Python y dos contenedores.
El mundo vive en dos servicios: el S3 local (fotos, snapshots y el examen) y MLflow (las corridas y el registro de modelos). mundo/crear.py los llena igual cada vez y entrena los cinco modelos del equipo, por eso tarda unos minutos. La carpeta tiene que ser un repositorio de git: el gate se niega a juzgar con reglas que no están en un commit.
Glosario: los 18 conceptos
Una línea para entenderlo; abre la tarjeta para la analogía, por qué importa y la trampa.
Gate de evaluaciónevaluation gateUn paso automático del pipeline que decide si un modelo puede avanzar, con reglas escritas antes. Si no se cumplen, el pipeline se detiene.Analogía, por qué importa y la trampa ↓
AnalogíaEl examen de manejo: hay una lista de cosas que tienes que hacer bien, escrita antes de que te subas al coche, y el examinador no la cambia porque le caíste bien.
Por qué importaSin gate, el modelo nuevo llega a producción porque «se ve bien» en una gráfica. Con gate, cada mes se aplica la misma regla, y el historial dice por qué pasó o no pasó cada modelo.
TrampaUn gate que solo mira el promedio global: una categoría rota se esconde detrás de 9 que mejoraron un poco.
Golden set (examen congelado)golden set / frozen test setUn conjunto fijo de fotos con etiquetas revisadas, que ningún entrenamiento ve y que no cambia. Se identifica por su id y por la huella (sha256) de su manifest.Analogía, por qué importa y la trampa ↓
AnalogíaEl metro patrón de París: si cada quien ajusta su metro, ya nadie mide lo mismo.
Por qué importaSolo con el mismo examen se pueden comparar modelos de meses distintos. Si se corrige algo, se publica golden-v2 en un PR propio y todos se vuelven a medir con él.
Trampa«Corregir» unas etiquetas del examen sin cambiarle el nombre: la comparación con los meses anteriores deja de valer y nadie lo nota.
Champion y challengerchampion / challengerChampion: el modelo que hoy atiende en producción. Challenger: el que pasó el gate y espera su turno (shadow y canary) para reemplazarlo.Analogía, por qué importa y la trampa ↓
AnalogíaEl campeón de box y el retador: el retador tiene que ganarse la pelea; no basta con decir que está mejor entrenado.
Por qué importaLos dos son alias en el registry, nombres que apuntan a una versión. Cambiar de modelo, o volver atrás, es mover un alias, no reentrenar.
TrampaMover champion a mano «porque ya lo probé en el notebook»: el alias se mueve, pero nadie aprobó ese modelo.
Registro de modelosmodel registryEl catálogo de modelos: cada versión (v1, v2…) apunta a sus archivos y nunca cambia; los alias (champion, challenger) se mueven; los tags guardan de dónde salió.Analogía, por qué importa y la trampa ↓
AnalogíaEl registro civil: cada acta tiene su número y no se reescribe; lo que cambia es quién ocupa qué puesto.
Por qué importaLa pregunta de la guardia a las 3 de la mañana, «¿qué modelo está sirviendo y de dónde salió?», se contesta con el alias y los tags, en un minuto.
TrampaCreer que los archivos de una corrida no cambian: en MLflow se pueden reemplazar. Por eso la versión guarda las huellas (pesos_sha256, labels_sha256).
Versión por númeropinned versionEl gate recibe el champion como número (v3), resuelto una sola vez al arrancar, nunca como la pregunta «¿quién es champion?».Analogía, por qué importa y la trampa ↓
AnalogíaComparar contra «el récord de hoy» a media carrera es trampa: el récord puede cambiar mientras corres.
Por qué importaSi el alias se mueve a mitad de la corrida, las predicciones serían de un modelo y el veredicto contra otro. Con el número, el reporte dice exactamente contra quién se comparó.
TrampaRegistrar el veredicto de un gate que comparó contra un champion que ya no es champion: es un veredicto viejo.
No inferioridadnon-inferiority testPedir que el modelo nuevo no sea peor que el actual por más de un margen, con buena seguridad. No se le pide ganar.Analogía, por qué importa y la trampa ↓
AnalogíaUn medicamento genérico más barato: no tiene que curar más que el original, solo no curar menos por más de un margen chico.
Por qué importaEl reentrenamiento mensual busca estar al día, no ganar. Exigir «mejor de forma significativa» bloquearía casi todos los meses; exigir «≥ champion» decidiría con una moneda.
TrampaMirar el centro (Δ) en vez del extremo de abajo (Δmin): un Δ de −0.5 puede pasar o no según cuánto ruido haya.
Margen de no inferioridadnon-inferiority marginCuánto se acepta que el modelo nuevo pierda contra el actual. Se fija antes, del tamaño del ruido del examen: lo que el examen ni siquiera puede medir.Analogía, por qué importa y la trampa ↓
AnalogíaLa tolerancia de una báscula: si mide de ± 100 g, no tiene caso discutir por 50.
Por qué importaEn C01, 0.3 puntos (golden de 50,000). En el dojo, 2.4 (golden de 1,000). Es una decisión de negocio vestida de estadística: en C01, con ≈ 10 millones de fotos al día, 0.3 puntos son ≈ 30,000 primeras sugerencias equivocadas más al día.
TrampaElegirlo después de ver el resultado. Entonces ya no mide: justifica.
Evaluación pareadapaired evaluationLos dos modelos responden las mismas fotos y se comparan foto por foto: b = solo el nuevo acierta, c = solo el viejo acierta.Analogía, por qué importa y la trampa ↓
AnalogíaDos cocineros preparan los mismos 1,000 platillos; para saber quién es mejor, solo importan los platillos en que uno acertó y el otro no.
Por qué importaLas fotos fáciles (los dos aciertan) y las imposibles (los dos fallan) no dicen nada; solo las discrepancias. Por eso la comparación pareada es más fina que comparar dos promedios.
TrampaGuardar solo «83.2 % vs 81.7 %»: sin los pares no hay prueba pareada, ni categorías, ni slices.
Error estándar e intervalostandard error / confidence intervalSE_Δ dice cuánto se movería la diferencia por azar con otras fotos. Δmin = Δ − 1.96 × SE es el extremo de abajo del intervalo de 95 %: lo peor que puede ser, con buena seguridad.Analogía, por qué importa y la trampa ↓
AnalogíaEl margen de error de una encuesta: «42 % ± 3» quiere decir que lo real está, casi seguro, entre 39 y 45.
Por qué importaLa regla del gate es Δmin ≥ −margen. Con pocas discrepancias el intervalo es estrecho; con muchas, ancho.
TrampaConfundir el SE de un modelo solo (el del margen) con el SE pareado (el de la diferencia): el segundo es más chico.
Erosión de calidadslow regressionPerder un poco cada mes, siempre dentro del margen: cada comparación pasa, y la suma de un año es grande.Analogía, por qué importa y la trampa ↓
AnalogíaLa rana en el agua que se calienta despacio: ningún grado de más se nota, la suma sí.
Por qué importaPor eso el gate compara también contra el champion de hace 3 meses: contra él se suman tres meses de pérdida, que no caben en el margen.
TrampaComparar solo contra el mes anterior y creer que eso protege del largo plazo.
Prueba de McNemarMcNemar's testPara dos modelos sobre las mismas fotos: si fueran igual de buenos, cada discrepancia sería un volado. La prueba da la probabilidad (p) de ver un reparto tan desigual de b y c por azar.Analogía, por qué importa y la trampa ↓
AnalogíaSi una moneda sale 21 veces cruz y 2 águila, sospechas que está cargada: es muy raro por azar.
Por qué importaSepara una categoría rota (camisas: 2 contra 21) del ruido (playeras: 1 contra 4). Usa solo las discrepancias de esa categoría.
TrampaUsarla con muy pocas discrepancias y concluir «no hay diferencia»: con 3 discrepancias, ninguna prueba puede ver nada.
Corrección de HolmHolm–Bonferroni correctionAl hacer k pruebas a la vez, ordena las p de menor a mayor y compara la primera contra α/k, la segunda contra α/(k − 1)… Así la falsa alarma de todo el conjunto queda en α.Analogía, por qué importa y la trampa ↓
AnalogíaSi compras 10 boletos de lotería, ganar uno ya no es tan sorprendente: hay que pedir más para creer que no fue suerte.
Por qué importaCon 10 categorías y α = 0.05 sin corregir, ≈ 40 % de los meses alguna «cae» por azar y el gate frena a un modelo sano.
TrampaNo corregir porque «cada prueba es al 5 %»: el 5 % es por prueba, no por gate.
Slicedata sliceUn pedazo del examen con algo en común: fotos con poca luz, fotos chicas, fotos del celular. Se evalúa aparte porque un promedio lo puede esconder.Analogía, por qué importa y la trampa ↓
AnalogíaUn restaurante con 4.5 estrellas que da intoxicación los martes: el promedio no lo dice, el corte por día sí.
Por qué importaEl candidato del proveedor no se ve tan mal en global (−1.3 puntos) y en poca luz su Δmin cae a −5.5: ahí es donde más se nota el lote malo.
TrampaUsar el margen global en un slice chico: con 200 fotos el ruido es ≈ 5 puntos, y el gate se pondría en rojo por azar.
Calibración (ECE)calibration / expected calibration errorSi el modelo dice «90 % seguro», ¿acierta 9 de cada 10? El ECE agrupa las fotos por confianza y promedia la distancia entre confianza y aciertos.Analogía, por qué importa y la trampa ↓
AnalogíaUn pronóstico del clima que dice «70 % de lluvia» y llueve 7 de cada 10 de esos días está bien calibrado.
Por qué importaProducto usa la confianza (por ejemplo, para pedir revisión humana debajo de un umbral). Un modelo que acierta igual pero dice «99 %» siempre rompe esa regla.
TrampaMirar solo la exactitud: dos modelos con el mismo top-1 pueden tener calibraciones muy distintas.
Fuga hacia el examendata leakage / test contaminationQue fotos del examen terminen en los datos de entrenamiento. El modelo ya vio las respuestas: sale mejor en el examen sin ser mejor.Analogía, por qué importa y la trampa ↓
AnalogíaEstudiar con el examen que te van a poner: sacas 10 y no aprendiste nada.
Por qué importaEl gate cruza las huellas del snapshot del candidato con las del examen y se detiene si hay una sola en común. La estación 2 deja el golden set fuera por diseño.
TrampaCelebrar un candidato que «sube 3 puntos» sin preguntar con qué datos se entrenó.
labels.json: el orden es parte del modelolabel mapLa lista que dice qué categoría es cada salida de la red: la salida 0 es «playeras», la 1 «pantalones»… Viaja con los pesos y se registra con su huella.Analogía, por qué importa y la trampa ↓
AnalogíaLas etiquetas de los frascos de la cocina: si las revuelves, el azúcar sigue siendo azúcar, pero le pones sal al café.
Por qué importaCon otro orden, los números del gate salen iguales (se evalúa por índice) y el gateway muestra otra categoría. Solo se nota si se compara el labels.json, o cuando cae la aceptación.
TrampaOrdenar las categorías alfabéticamente «para que se vea limpio».
Reglas escritas antespre-registered thresholdsLos umbrales del gate viven en un archivo versionado y cambian solo en un PR propio, revisado por otra persona, antes de la corrida.Analogía, por qué importa y la trampa ↓
AnalogíaLas reglas del partido se acuerdan antes del silbatazo, no al medio tiempo cuando vas perdiendo.
Por qué importaSi se pueden mover después de ver el resultado, cada mes habrá un argumento razonable para aflojar, y el gate deja de medir.
Trampa«Solo por esta vez»: el commit directo a main que afloja una regla para que salga el modelo de la semana.
Fallar en rojofail loudlySi el gate no pasa, el paso termina con error (código de salida 1, corrida FAILED) y el pipeline se detiene y avisa. Nunca devuelve «false» y deja seguir.Analogía, por qué importa y la trampa ↓
AnalogíaUna alarma de incendio que en vez de sonar escribe una nota en un cuaderno: técnicamente detectó el fuego.
Por qué importaUn gate que «devuelve false» deja que los pasos siguientes se salten en silencio: la corrida queda en verde, no aparece ningún challenger y nadie se entera.
TrampaAtrapar la excepción del gate «para que el pipeline no truene».
Nube real vs. local
En C01
En el dojo
El examen
golden-v3: 50,000 fotos
golden-v1: 1,000 fotos (las que la estación 3 dejó fuera de los snapshots), 600 normales, 210 con poca luz y 190 chicas
Categorías
500; el gate revisa por separado las 100 con más tráfico
10, todas
Margen de no inferioridad
0.3 puntos
2.4 puntos (el ruido de un examen de 1,000 fotos)
Contra quién
el champion (v14) y el de hace 3 meses (v12)
el champion (v3, septiembre) y el de hace 3 meses (v1, julio)
Dónde corre
un paso del pipeline en una GPU (evaluar) y otro en CPU (el gate)
la CPU de tu Mac: evaluar ≈ 10 s, el gate ≈ 3 s
Las reglas
gate.yaml en el repositorio ml-catalogo; cambian solo en un PR revisado
gate.yaml en tu carpeta; sus versiones revisadas, en mundo/revisiones.json
Las mismas reglas con otra escala: el margen sale de la misma fórmula (2.4 puntos en lugar de 0.3) y cada categoría tiene ≈ 100 fotos.
El historial de PR del repositorio <code>ml-catalogo</code>
<code>mundo/revisiones.json</code>
En C01, la rama protegida no deja subir gate.yaml sin revisión; aquí el gate comprueba la huella contra la lista de versiones aprobadas.
Los parámetros de la corrida de Argo
<code>corrida.yaml</code>
Los dos traen el champion ya resuelto a un número. El de verdad lo escribe el orquestador; el del dojo lo escribe mundo/crear.py.
Registrar después de la estación 5 (paridad y latencia del engine)
<code>registrar.py</code> justo después del gate
En el dojo no hay engine: el challenger se registra en cuanto pasa el gate. En C01, primero se construye y se prueba el engine.
Evaluar en una GPU
La CPU de tu Mac
1,000 fotos de 32×32 caben en segundos; 50,000 de 224×224 con una ResNet-50, en minutos de GPU.
MLflow con Postgres y S3; Amazon S3
MLflow con SQLite; RustFS en localhost:9500
La misma API y la misma interfaz.
Qué trae el kit y qué escribes tú
Lo que trae no lo escribes
El S3 local y MLflow (compose.yaml). RustFS en el puerto 9500 (buckets fotos y ml-datos, este con versionado) y MLflow en el 5500, con su interfaz.
mundo/crear.py. Crea todo en ≈ 3 minutos: baja Fashion-MNIST, sube las 10,000 fotos, publica 4 snapshots, congela golden-v1 (1,000 fotos con su slice), entrena classifier v1, v2 y v3 (@champion) y los dos candidatos, y escribe corrida.yaml.
gate.yaml y mundo/revisiones.json. Las reglas del gate (el examen y su huella, contra quién, el margen, categorías, slices y calibración) y el registro de sus versiones revisadas: el sustituto del historial de PR.
corrida.yaml. Los parámetros de esta noche, ya resueltos: el candidato, champion = 3 y hace_3_meses = 1.
mundo/gateway/ y mundo/arquitectura.py. El preprocess del gateway (el mismo de la estación 3) y la red.
mundo/modelos.py y mundo/s3.py. Mirar y reparar el registro (versiones, alias, candidatos, gates, labels) y el S3 (el examen, sus versiones y restaurar una).
verificar.py y romper.py. 10 checks con los criterios de «listo» y 6 fallas en el mundo, la configuración o la infraestructura, nunca en lo que escribes.
Lo que escribes lo escribes tú
pipeline/evaluar.pyLos tres modelos por número, con sus huellas, sobre el examen congelado (sin fuga): los pares, foto por foto.
pipeline/gate.pyLas reglas revisadas: no inferioridad pareada, categorías con McNemar y Holm, slices y ECE. Si no pasa, en rojo.
pipeline/registrar.pySolo con un gate que pasó: la versión nueva con sus tags y el alias challenger.
Reglas CLAUDE.md del kit
El CLAUDE.md del kitLas reglas de fondo para Claude Code en la carpeta del kit. Ya viene en el .zip.Ver el CLAUDE.md ↓
prompt
# Dojo de entrenamiento ML engineer's · C01 · Estación 4: Gate de evaluación y registry
Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin GPU ni nube, la estación «Gate de evaluación y registry» del caso C01: decidir, con reglas escritas antes y números foto por foto, si el modelo nuevo puede reemplazar al de producción, y dejarlo registrado como challenger con todo lo que dice qué es. La persona con la que trabajas está aprendiendo; tu trabajo es que **entienda**, no que termine rápido.
## Qué es cada cosa
| Carpeta o archivo | Qué es | ¿Se toca? |
|---|---|---|
| `mundo/` | La empresa ficticia: `crear.py` (fotos, snapshots, el examen congelado, el historial del registro y los dos candidatos de octubre), `arquitectura.py` (la red), `gateway/` (el preprocess del gateway), `modelos.py` (mirar y reparar el registro de MLflow), `s3.py` (mirar el S3 y sus versiones), `revisiones.json` (las versiones aprobadas de `gate.yaml`), `equipo.py`, `reiniciar.py` y el esqueleto. | **No.** Es el mundo. `modelos.py` y `s3.py` sí se usan. |
| `pipeline/evaluar.py`, `gate.py`, `registrar.py` | Lo que escribe la persona. Cada archivo trae su contrato arriba. | **Sí.** |
| `pipeline/_comun.py` | Lo que comparten los pasos: `corrida()`, `gate()`, `revisiones()`, `s3()`, `mlflow_cliente()`, `git()`, `sha256()`, `huella_pesos()` y las constantes. | No. |
| `gate.yaml` | Las reglas del gate (del equipo, revisadas en un PR). | Solo con una revisión aprobada. Nunca para que un modelo pase. |
| `corrida.yaml` | Los parámetros de esta noche, ya resueltos por el orquestador: candidato, champion y el de hace 3 meses, por número. | No a mano. |
| `entrada/categorias.json` | Las 10 categorías; su orden es el `label_id` y es el `labels.json` correcto. | No. |
| `reportes/` | Lo que dejan `evaluar.py` y `gate.py` de cada candidato: pares, evaluación y reporte. Git la ignora. | No a mano. |
| `data/` | Caché local: Fashion-MNIST. Git la ignora. | No. |
| `verificar.py` | Revisa los criterios de «listo», uno por check. | No. |
| `romper.py` | Mete fallas en el mundo, la configuración o la infraestructura. Nunca en lo que escribe la persona. | No. Y no leas su código para adivinar una falla escondida. Tampoco leas `mundo/equipo.py` para resolver un paso. |
| `GUION.md` / `OBJETIVOS.md` | El paso a paso (Construir con ayuda) y solo los objetivos (Construir solo). | No. |
| `taller/progreso.json`, `BITACORA.md` | El registro de las rondas. | Sí, tú los mantienes (ver abajo). |
| `taller/registro.py` | Lo usan `verificar.py` y `romper.py` para anotar en `progreso.json` sus corridas y las fallas cerradas. | No. |
## Cómo se trabaja
- Responde en español neutro, de tú, directo y sin relleno. Términos técnicos en inglés la primera vez, con su explicación.
- Explica siempre el **por qué**. Cuando algo en el dojo es distinto de C01 real (1,000 fotos de examen en lugar de 50,000, 10 categorías en lugar de 500, un margen de 2.4 puntos en lugar de 0.3, `mundo/revisiones.json` en lugar del historial de PR, `corrida.yaml` en lugar de los parámetros de Argo, registrar aquí en lugar de después de la estación 5), dilo en una línea.
- Nunca inventes salidas: si no corriste algo, di que no lo corriste.
- El entorno virtual va activo en cada comando: `source .venv/bin/activate`.
- Antes de correr algo que cambia el mundo o la máquina (`pipeline/gate.py`, `pipeline/registrar.py`, `mundo/modelos.py alias|quitar|labels`, `mundo/s3.py restaurar`, `pip install`, `docker compose …`, `romper.py`, `mundo/*.py`, `git commit`, `git revert`), dilo. Lo que solo lee (`verificar.py`, `pipeline/evaluar.py`, `mundo/modelos.py versiones|candidatos|gates`, `mundo/s3.py ls|golden|tarjeta|versiones`, `git status`, `git log`, `git diff`) se puede correr directo.
- `evaluar.py` tarda ≈ 10 s y el gate ≈ 3 s. `mundo/crear.py`, ≈ 4 min.
- Las reglas no se mueven para que algo pase. Si la persona propone cambiar un umbral después de ver un resultado, explícale por qué no, y cómo se haría bien (un PR propio, antes de la corrida siguiente).
- La interfaz de MLflow está en http://localhost:5500. Úsala para enseñar: las corridas de gate (las rojas también), sus tags, el reporte, las versiones y sus alias.
- Sigue el prompt de la ronda que te pegaron: en Construir solo y en Romper solo **no das código ni pistas** salvo que la persona se rinda.
## Bitácora
Al terminar cada paso, objetivo o falla, agrega una entrada en los dos archivos:
`BITACORA.md`, legible en el celular:
```markdown
## 2026-11-18 10:42 · Construir con ayuda · paso 3 (no inferioridad)
- **Hice:** …
- **Medí:** … (números reales que salieron)
- **Sigue:** …
```
`taller/progreso.json`, el que se importa en «Tu tablero» del Dojo (la página /tablero/ de la app). Agrega a `bitacora` y actualiza `rondas`:
```json
{
"estacion": "c01-gate",
"rondas": {
"guiado": { "estado": "en_curso", "inicio": "2026-11-18T10:05:12-06:00", "fin": null },
"solo": { "estado": "pendiente", "inicio": null, "fin": null, "pistas": 0 },
"romper_ayuda": { "estado": "pendiente", "fallas": [] },
"romper_solo": { "estado": "pendiente", "fallas": [] }
},
"bitacora": [
{ "fecha": "2026-11-18T10:42:30-06:00", "ronda": "guiado", "paso": "no-inferioridad", "hice": "…", "medi": "…", "sigue": "…" }
],
"verificaciones": [
{ "fecha": "2026-11-18T10:41:02-06:00", "pasan": ["mundo", "examen"], "fallan": [] }
]
}
```
- `estado` es `pendiente`, `en_curso` o `hecha`. En el tablero, `guiado` se llama «Construir con ayuda», `solo` «Construir solo», `romper_ayuda` «Romper con ayuda» y `romper_solo` «Romper solo».
- **Fecha y hora en cada avance**, en ISO 8601 con la zona de la Mac: sácala con `date -Iseconds` (da algo como `2026-11-18T10:42:30-06:00`). Nunca solo la fecha.
- `verificaciones` la escribe `verificar.py` solo, en cada corrida. No la edites.
- Cada falla la anota `romper.py` al cerrarla (`--verificar` o `--revelar`): `{ "id", "inicio", "fin", "minutos", "pistas": 0, "rendido", "aprendi": "" }`, con el tiempo real. Tú solo completas `pistas` y `aprendi` en esa misma entrada (la última de su ronda); no agregues otra.
- Mantén el JSON válido: después de editarlo, corre `python -m json.tool taller/progreso.json > /dev/null`.
Sensei es el curso de teoría desde cero de TrueML. Su lección de esta estación explica el porqué de lo que aquí construyes; léela antes o vuelve a ella cuando algo no cierre.