Necesitas: Docker Desktop corriendo, con ≈ 400 MB libres para la imagen de RustFS · Python 3.11 o más nuevo (se probó con 3.14.3) y ≈ 300 MB para el entorno virtual · git (con tu nombre y correo configurados) · Los puertos 9300 y 9301 libres en tu Mac
Listo cuando: verificar.py mundo en verde. Ya puedes practicar.
¿Algo falló al levantar? ↓
Ojo: Si el 9300 está ocupado, lsof -nP -iTCP:9300 -sTCP:LISTEN te dice quién. La consola web de RustFS está en http://localhost:9301 (usuario taller, contraseña taller-secreto): ahí ves los dos buckets.
python3 -m venv .venv && source .venv/bin/activate · Tarda ≈ 1 minuto la primera vez. Desde aquí, cada terminal nueva necesita source .venv/bin/activate.
SalidaSalida real · python3 -m venv .venv && source .venv/bin/activate
Python 3.14.3
SalidaSalida real · docker compose up -d --wait
Container taller-c01-versionado-s3-1 Waiting
Container taller-c01-versionado-s3-1 Healthy
buckets: fotos (el producto) y ml-datos (con versiones)
s3://fotos: 3120 fotos, 7.3 MB
entrada/: 3120 publicaciones, 3908 eventos de labels, golden de 280 huellas
s3://ml-datos/datasets/ds-2026-08-01/: 2013 filas (1882 train · 131 val)
entrada/borrados.csv: 14 huellas de s-217 (fotos borradas del bucket el 15 de septiembre)
corridas/run-20260901-061500.json: modelo-2026-09-01 ← ds-2026-08-01 (accuracy_val 0.7481)
✓ mundo listo
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"
6087a76 dvc init
c038d9d kit recién descomprimido
SalidaSalida real · python verificar.py mundo
✓ mundo S3 local con fotos (1000+) y ml-datos (ds-2026-08-01 publicado) · entrada/ completa · git y DVC 3.67.1
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 8. Empieza aquí.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 2 de C01, «Versionado y linaje», ronda **Construir con ayuda**.
Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a escribir juntos, siguiendo los pasos 0 a 8 de `GUION.md`, el pipeline que convierte los labels del mes en el snapshot `ds-2026-09-01`: los labels al corte, el manifest, el split estable, el contrato de datos, la publicación inmutable con su tarjeta, el pipeline como DAG con DVC, el entrenamiento que deja los punteros del linaje y la búsqueda al revés (de una foto a sus snapshots y modelos).
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, línea por línea y con el porqué de cada una. 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/5_publicar.py`, `dvc repro`, `pipeline/6_entrenar.py`, `git commit`, `mundo/s3.py borrar-version`) no los corras tú sin decírmelo antes.
4. Corre `python verificar.py <check del paso>` y explícame el resultado.
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 2 de C01, «Versionado y linaje», 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 o la infraestructura, nunca en mi pipeline ni en mi `dvc.yaml`, 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 (`dvc status`, `git status`, `python mundo/s3.py versiones …`, `python mundo/s3.py versionado …`, `python pipeline/7_linaje.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 (Amazon S3, la política del bucket, el orquestador, MLflow).
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 2 de C01, «Versionado y linaje», ronda **Construir solo**.
Lee `CLAUDE.md`. **No leas `GUION.md`** ni `mundo/comun.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/, `dvc.yaml` vacío y `params.yaml` de fábrica), borra `data/`, mis corridas y los snapshots que publiqué (deja el de agosto). 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 2 de C01, «Versionado y linaje», 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 pipeline, las cuentas de servilleta del versionado: cuánto pesa un snapshot que cita en vez de copiar, cuánto cuesta guardar un año, cuánto cuesta comprobar cada huella al leer, qué pasa si el split se sortea cada mes y cuántas filas son normales. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.
1Labels al cortePara cada foto, el label vigente al 1 de octubre a las 00:00 UTC.
Los labels llegan como eventos: quien vende elige una categoría al publicar, moderación corrige días después y la cola de etiquetado de la estación 1 agrega labels humanos. Nada se edita. El snapshot de septiembre es una consulta: de los eventos de antes del corte, el más reciente de cada foto. Encima va la regla de la estación 1: una elección de quien vende cuenta solo si ya tiene 30 días sin que nadie la corrija.
Pythonpipeline/1_labels.py
"""Paso 1 · Labels al corte.
Entra: entrada/labels-eventos.parquet los labels como eventos (nunca se editan: corregir es agregar otro)
params.yaml snapshot.corte y labels.dias_maduracion
Sale: data/labels.parquet una fila por foto con el label vigente al corte:
image_key, label_id, label_source, guia_version, label_ts
Reglas: solo cuentan los eventos con ts antes del corte; de cada foto gana el más reciente (si empatan, el event_id
mayor); si el que gana es de quien vende ("vendedor"), cuenta solo si ya tiene dias_maduracion días al corte.
"""from datetime import timedelta
import pandas as pd
from _comun import DATA, ENTRADA, params, utc
p = params()
corte = utc(p["snapshot"]["corte"])
dias = p["labels"]["dias_maduracion"]
ev = pd.read_parquet(ENTRADA / "labels-eventos.parquet")
antes = ev[ev["ts"] < corte] # point-in-time: solo lo que ya existía
vigente = antes.sort_values(["ts", "event_id"]).groupby("image_key").tail(1) # el más reciente gana
madura = (vigente["label_source"] != "vendedor") | (vigente["ts"] <= corte - timedelta(days=dias))
labels = vigente[madura].rename(columns={"ts": "label_ts"})
labels = labels[["image_key", "label_id", "label_source", "guia_version", "label_ts"]].sort_values("image_key")
labels.to_parquet(DATA / "labels.parquet", index=False)
print(f"eventos: {len(ev)} · antes del corte {corte:%Y-%m-%d %H:%M} UTC: {len(antes)} · después (se ignoran): {len(ev) - len(antes)}")
print(f"fotos con label vigente: {len(vigente)} · sin madurar (quien vende, < {dias} días): {(~madura).sum()}")
print(f"data/labels.parquet: {len(labels)} labels · {labels['label_source'].value_counts().to_dict()}")
utc() de _comun.py rechaza una fecha sin zona: nunca adivina.
Terminal
python pipeline/1_labels.py
Salida
eventos: 3908 · antes del corte 2026-10-01 00:00 UTC: 3796 · después (se ignoran): 112
fotos con label vigente: 3120 · sin madurar (quien vende, < 30 días): 507
data/labels.parquet: 2613 labels · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
Terminal
python-c"import pandas as pd; print(pd.read_parquet('data/labels.parquet').head(3).to_string(index=False))"
guia_version es nulo cuando el label lo puso quien vende o moderación: la guía es del etiquetado humano.
✓ labels 2613 labels vigentes al 2026-10-01T00:00:00Z · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
1/1 en verde
Listo cuando: 2,613 labels: ninguno de después del corte y ninguna elección de quien vende con menos de 30 días.
Ojo: 112 eventos son de después del corte: si entran, el snapshot cambia según el día en que lo corras. Y el orden importa: ordena por hora antes de quedarte con el último.
Conceptos de este paso ↓
Labels como eventosappend-only label eventsCada label es una fila nueva que nunca se edita, con su fuente, su guía y su hora. Corregir es agregar otro evento más nuevo.Analogía, por qué importa y la trampa ↓
AnalogíaEl historial de un expediente médico: el diagnóstico nuevo no borra el viejo, se escribe abajo con fecha.
Por qué importaCon eso, un snapshot es una consulta: «para cada foto, el label más reciente que ya existía a tal hora». Nada se pierde y se puede explicar por qué el modelo de agosto aprendió lo que aprendió.
TrampaSi la tabla guarda una fila por foto y la corrección la reescribe, ya no sabes qué label había el día del corte.
Corte (point-in-time)point-in-time cutoffLa hora, en UTC, hasta la que cuenta lo que existe: un snapshot solo ve eventos de antes del corte.Analogía, por qué importa y la trampa ↓
AnalogíaEl cierre de una votación: los votos que llegan después cuentan para la siguiente.
Por qué importaHace que el snapshot sea reproducible: correrlo hoy o en un año da lo mismo, aunque sigan llegando eventos. También el registro de borrados se lee al corte.
TrampaUn corte sin zona horaria (2026-10-01 00:00) se interpreta en la hora de la máquina: en México son 6 horas de diferencia y se cuelan eventos.
2El manifestUna fila por label, con la llave y la huella de su foto.
El manifest no copia fotos: las cita por llave y por huella. La huella la calculó el producto al subir la foto y viene en publicaciones.parquet; el entrenamiento la vuelve a calcular al leer (paso 7). validate="one_to_one" hace que pandas truene si una llave aparece dos veces: un join que duplica filas es el error clásico que infla el volumen.
Pythonpipeline/2_manifest.py
"""Paso 2 · El manifest: una fila por foto, con su huella.
Entra: data/labels.parquet del paso 1
entrada/publicaciones.parquet quién vende, cuándo, la llave y el sha256 de cada foto (lo calcula el producto al subirla)
Sale: data/manifest.parquet una fila por label: image_key, image_sha256, seller_id, label_id, label_source,
guia_version, label_ts, created_at, bytes. Las fotos no se copian: se citan por llave + huella.
"""import pandas as pd
from _comun import DATA, ENTRADA
labels = pd.read_parquet(DATA / "labels.parquet")
pubs = pd.read_parquet(ENTRADA / "publicaciones.parquet")
m = labels.merge(pubs[["image_key", "image_sha256", "seller_id", "created_at", "bytes"]],
on="image_key", how="left", validate="one_to_one") # una publicación por llave; si no, truena
huerfanas = m["image_sha256"].isna().sum()
if huerfanas:
raiseSystemExit(f"✗ {huerfanas} labels de fotos que no están en publicaciones.parquet")
m = m[["image_key", "image_sha256", "seller_id", "label_id", "label_source", "guia_version", "label_ts", "created_at", "bytes"]]
m.sort_values("image_key").to_parquet(DATA / "manifest.parquet", index=False)
print(f"data/manifest.parquet: {len(m)} filas · {m['image_sha256'].nunique()} huellas distintas · {m['seller_id'].nunique()} vendedores")
print(f"fotos citadas: {m['bytes'].sum() / 1e6:.1f} MB · manifest: {(DATA / 'manifest.parquet').stat().st_size / 1e3:.0f} kB")
Terminal
python pipeline/2_manifest.py
2,613 filas pero 2,499 huellas: hay fotos repetidas en varias publicaciones. Se resuelve en el paso 3.
✓ manifest 2613 filas, cada una con su llave y su huella · manifest 246 kB · cita 6.1 MB de fotos
1/1 en verde
Listo cuando: Una fila por label, sin huecos, y cada huella igual a la de publicaciones.parquet.
Ojo: 246 kB para citar 6.1 MB: ≈ 4 %. En C01, con fotos de 200 KB, es ≈ 0.1 % (el precálculo «peso»).
Conceptos de este paso ↓
Snapshot inmutableimmutable dataset snapshotUna versión del dataset con id propio (ds-2026-09-01) que, una vez escrita, nadie cambia: ni se borra, ni se reemplaza, ni se le agregan filas.Analogía, por qué importa y la trampa ↓
AnalogíaLa foto de grupo de fin de año: si alguien llega tarde, sale en la del año siguiente; no se retoca la de este año.
Por qué importaEs lo que hace que «el modelo de octubre se entrenó con ds-2026-09-01» sea verdad para siempre. Si el contenido cambia, es otro snapshot con otro id.
TrampaInmutable «por acuerdo» no sirve: un script que corre dos veces o alguien que «arregla» una fila lo rompe sin dar error. Tiene que ser por diseño.
ManifestmanifestUn archivo (aquí, Parquet) con una fila por foto: su llave, su huella, quién la vende, su label, de dónde salió el label y su split.Analogía, por qué importa y la trampa ↓
AnalogíaLa lista de invitados con foto de cada uno, en vez de meter a los invitados en la caja.
Por qué importaCita las fotos en vez de copiarlas: un snapshot pesa ≈ 0.1 % de las imágenes en C01 y se puede guardar uno por mes para siempre.
TrampaSi una foto se borra o cambia bajo la misma llave, la fila apunta a otra cosa. Por eso lleva la huella, y por eso se comprueba al leer.
Huella sha256content hash (SHA-256)64 caracteres hexadecimales que salen de los bytes de un archivo: el mismo contenido da siempre la misma huella; un byte distinto, otra.Analogía, por qué importa y la trampa ↓
AnalogíaUna huella digital: no dice cómo es la persona, pero dice si es la misma.
Por qué importaHay dos: image_sha256 (cada foto) y rows_sha256 (el manifest entero, en la tarjeta). La segunda la guarda cada modelo: si alguien cambia una sola etiqueta, se nota.
TrampaLa huella no impide nada: delata. Y depende de los bytes: el mismo contenido escrito en otro orden da otra huella, por eso las filas se ordenan antes de escribir.
Precálculo ↓
1
¿Cuánto pesa el manifest comparado con las fotos que cita?
manifest = filas × bytes por fila; fotos = filas × bytes por foto; la fracción es bytes por fila ÷ bytes por foto
En C011,932,628 filas × ≈ 200 B = ≈ 387 MB sin comprimir, contra 1,932,628 × ≈ 200 KB = ≈ 387 GB de fotos≈ 0.1 % (y ≈ 97 MB ya en Parquet)
En el dojo≈ 2,600 filas × ≈ 200 B = ≈ 0.5 MB, contra 3,120 fotos de ≈ 2.3 kB (7.3 MB)≈ 9 % sin comprimir: las fotos de juguete son 100 veces más chicas que las de C01
Qué decides con esto. Un snapshot cita, no copia: guardar uno cada mes cuesta casi nada. La proporción depende solo de cuánto pesa cada foto, no de cuántas hay.
Terminalterminal · compruébalo en el kit
python-c"import pandas as pd; p = pd.read_parquet('entrada/publicaciones.parquet'); print(f'{len(p)} publicaciones · {p.bytes.sum() / 1e6:.1f} MB de fotos · {p.bytes.mean() / 1e3:.1f} kB por foto en promedio')"
Salida
3120 publicaciones · 7.3 MB de fotos · 2.3 kB por foto en promedio
Lo confirmas en el paso 2: el manifest real pesa 246 kB en Parquet y cita 6.1 MB de fotos (≈ 4 %).
3Las filas y el split estableSin borrados, sin duplicados, sin golden, y cada vendedor del mismo lado que en agosto.
Tres filtros y una regla. El registro de borrados también se lee al corte: lo que se borró antes del 1 de octubre ya no entra. De cada huella repetida queda la publicación más vieja, que no cambia mes con mes. El golden set nunca entra a entrenar. Y el split no se sortea: la cubeta del vendedor es su sha256 mod 100, el mismo número hoy y dentro de diez años.
Pythonpipeline/3_split.py
"""Paso 3 · Las filas del snapshot: sin borrados, sin duplicados, sin el golden set y con el split estable.
Entra: data/manifest.parquet del paso 2
entrada/borrados.csv el registro de borrados (image_sha256, fecha, motivo)
entrada/golden.parquet las huellas del golden set: nunca entran a entrenar
params.yaml snapshot.corte y split.umbral
Sale: data/rows.parquet las columnas del manifest + split ("train" o "val"), ordenado por image_key
Reglas: fuera las fotos del registro de borrados con fecha antes del corte (el registro también se lee al corte);
de cada huella repetida queda una fila, la de la publicación más vieja (created_at, y si empatan, image_key);
fuera las huellas del golden set; split = "train" si sha256(seller_id) mod 100 < split.umbral, si no "val".
"""import hashlib
import pandas as pd
from _comun import DATA, ENTRADA, params, utc
p = params()
corte = utc(p["snapshot"]["corte"])
umbral = p["split"]["umbral"]
m = pd.read_parquet(DATA / "manifest.parquet")
borr = pd.read_csv(ENTRADA / "borrados.csv")
borr = borr[pd.to_datetime(borr["fecha"], utc=True) < corte] # el registro también se lee al corte
golden = set(pd.read_parquet(ENTRADA / "golden.parquet")["image_sha256"])
n0 = len(m)
m = m[~m["image_sha256"].isin(set(borr["image_sha256"]))]
n_borr = n0 - len(m)
m = m.sort_values(["created_at", "image_key"]).drop_duplicates("image_sha256", keep="first") # la publicación más vieja
n_dup = n0 - n_borr - len(m)
n_gold = m["image_sha256"].isin(golden).sum()
m = m[~m["image_sha256"].isin(golden)]
defcubeta(seller_id: str) -> int:
returnint(hashlib.sha256(seller_id.encode()).hexdigest(), 16) % 100# el mismo número hoy y en diez años
m = m.assign(split=["train"ifcubeta(s) < umbral else"val"for s in m["seller_id"]]).sort_values("image_key")
m.to_parquet(DATA / "rows.parquet", index=False)
print(f"manifest: {n0} · borradas antes del corte: {n_borr} · duplicadas por huella: {n_dup} · del golden set: {n_gold}")
print(f"data/rows.parquet: {len(m)} filas · {m['split'].value_counts().to_dict()} · vendedores en val: {m.loc[m['split'] == 'val', 'seller_id'].nunique()}")
Terminal
python pipeline/3_split.py
Salida
manifest: 2613 · borradas antes del corte: 13 · duplicadas por huella: 114 · del golden set: 19
data/rows.parquet: 2467 filas · {'train': 2309, 'val': 158} · vendedores en val: 17
Terminal
python-c"
import hashlib
for s in ['s-001', 's-002', 's-007', 's-001']:
c = int(hashlib.sha256(s.encode()).hexdigest(), 16) % 100
print(s, c, 'train' if c < 90 else 'val')"
✓ split 2467 filas: sin duplicados, sin golden, sin borrados · {'train': 2309, 'val': 158} por vendedor
✓ split-estable 298 vendedores en los dos snapshots, 0 cambiaron de lado · ninguna foto de val del padre en train
2/2 en verde
Listo cuando: 2,467 filas, un solo lado por vendedor y 0 vendedores que cambiaron de lado contra ds-2026-08-01.
Ojo: Deduplicar por image_key no quita nada: cada publicación tiene su llave. Lo que se repite son los bytes. Y ordena por image_key antes de escribir: el mismo contenido tiene que dar la misma huella.
Conceptos de este paso ↓
Duplicados por huellahash-based deduplicationLa misma foto subida en varias publicaciones cuenta una sola vez: de cada huella queda la fila de la publicación más vieja.Analogía, por qué importa y la trampa ↓
AnalogíaTres copias del mismo examen con distinto nombre en la portada: se califica una.
Por qué importaSi la misma foto cayera en train y en val, la validación premiaría memorizar. Pasa con vendedores que republican y con fotos de catálogo que usan dos tiendas.
TrampaDeduplicar por llave no sirve: cada publicación tiene su llave. Lo que se repite son los bytes, o sea la huella.
Registro de borradosdeletion log (tombstones)Una lista de solo agregar con la huella de cada foto que se borró, la fecha y el motivo.Analogía, por qué importa y la trampa ↓
AnalogíaLa lista de bajas de un club: no se arranca la hoja del acta vieja, se anota la baja con fecha.
Por qué importaRespeta el derecho al borrado sin romper la historia: los snapshots viejos no se reescriben, el siguiente ya no la incluye y el entrenamiento la salta al leer.
TrampaBorrar la foto del bucket sin anotarlo deja filas que apuntan a nada y un entrenamiento que truena; anotarlo sin borrar no cumple la solicitud.
Split establestable split (hash-based)Cada vendedor cae en train o en val por el hash de su seller_id (cubeta = sha256 mod 100) y se queda ahí en todas las versiones.Analogía, por qué importa y la trampa ↓
AnalogíaEl número de lista en la escuela: el mismo alumno tiene el mismo número todo el año, aunque entren alumnos nuevos.
Por qué importaComparar el modelo nuevo contra el viejo solo es justo si ninguno vio el examen del otro. Los vendedores nuevos caen donde les toque, sin mover a nadie.
TrampaSortear otra vez, o mover el umbral «para tener más validación», manda a val vendedores con los que el modelo anterior ya entrenó.
Precálculo ↓
4
Si el split se sorteara otra vez cada mes, ¿cuántas fotos de validación pasarían a train?
se mueven = fotos de validación del padre × fracción que va a train
En C0192,417 × 0.95≈ 87,796 fotos con que se validó el modelo de octubre entrenarían al de noviembre
En el dojo131 fotos de validación en ds-2026-08-01 × 0.90≈ 118 de 131
Qué decides con esto. El split no se sortea: se calcula con el hash del vendedor, y así se mueven cero. Cambiar el umbral también mueve gente: el umbral se fija una vez y no se toca.
Terminalterminal · compruébalo en el kit
python-c"import json, sys; sys.path.insert(0, '.'); from mundo.comun import s3; t = json.loads(s3().get_object(Bucket='ml-datos', Key='datasets/ds-2026-08-01/snapshot.json')['Body'].read()); print('ds-2026-08-01:', t['counts'], '· split:', t['split']['rule'])"
Es el «auditar» de escribir, auditar, publicar. Ya escribiste aparte (en data/); ahora se comprueba todo contra reglas fijas. El padre se lee y se comprueba con su huella antes de usarlo: si alguien lo reescribió, la validación del split estable compararía contra algo falso. El código de salida 1 es lo que hace que DVC se detenga.
Pythonpipeline/4_validar.py
"""Paso 4 · El contrato de datos: auditar antes de publicar (write-audit-publish).
Entra: data/rows.parquet del paso 3
entrada/categorias.json, entrada/golden.parquet
s3://ml-datos/datasets/<padre>/ el snapshot anterior (su tarjeta y sus filas)
params.yaml snapshot.id, snapshot.padre y validar.*
Sale: data/validation.json {"snapshot_id", "padre", "status": "passed" | "failed", "checks": {nombre: "ok" | motivo}}
con los checks esquema, categorias, duplicados, golden, split_vendedor, split_estable, volumen y vendedor.
Si alguno falla, sale con código 1: el pipeline se detiene y no se publica nada.
"""import io
import json
import sys
import pandas as pd
from _comun import DATA, DATOS, ENTRADA, params, s3, sha256
p = params()
v = p["validar"]
rows = pd.read_parquet(DATA / "rows.parquet")
COLUMNAS = ["image_key", "image_sha256", "seller_id", "label_id", "label_source", "guia_version",
"label_ts", "created_at", "bytes", "split"]
# el padre, comprobado con su huella antes de usarlo
cliente = s3()
tarjeta = json.loads(cliente.get_object(Bucket=DATOS, Key=f"datasets/{p['snapshot']['padre']}/snapshot.json")["Body"].read())
crudo = cliente.get_object(Bucket=DATOS, Key=f"datasets/{p['snapshot']['padre']}/rows.parquet")["Body"].read()
ifsha256(crudo) != tarjeta["rows_sha256"]:
sys.exit(f"✗ el padre {p['snapshot']['padre']} no coincide con su tarjeta: alguien lo reescribió")
padre = pd.read_parquet(io.BytesIO(crudo))
lado_padre = padre.drop_duplicates("seller_id").set_index("seller_id")["split"]
lado = rows.drop_duplicates("seller_id").set_index("seller_id")["split"]
comunes = lado.index.intersection(lado_padre.index)
movidos = (lado[comunes] != lado_padre[comunes]).sum()
validas = {int(k) for k in json.loads((ENTRADA / "categorias.json").read_text())}
golden = set(pd.read_parquet(ENTRADA / "golden.parquet")["image_sha256"])
razon = len(rows) / len(padre)
f_vend = (rows["label_source"] == "vendedor").mean()
checks = {
"esquema": "ok"iflist(rows.columns) == COLUMNAS elsef"columnas {list(rows.columns)}",
"categorias": "ok"if rows["label_id"].isin(validas).all() elsef"{(~rows['label_id'].isin(validas)).sum()} labels fuera de las categorías",
"duplicados": "ok"if rows["image_sha256"].is_unique elsef"{rows['image_sha256'].duplicated().sum()} huellas repetidas",
"golden": "ok"ifnot rows["image_sha256"].isin(golden).any() elsef"{rows['image_sha256'].isin(golden).sum()} fotos del golden set",
"split_vendedor": "ok"if rows.groupby("seller_id")["split"].nunique().max() == 1else"hay vendedores en train y en val",
"split_estable": "ok"if movidos == 0elsef"{movidos} de {len(comunes)} vendedores cambiaron de lado contra {p['snapshot']['padre']}",
"volumen": "ok"if v["volumen_min"] <= razon <= v["volumen_max"] elsef"{razon:.2f} veces el padre (rango {v['volumen_min']}–{v['volumen_max']})",
"vendedor": "ok"if f_vend <= v["max_vendedor"] elsef"{f_vend:.0%} de labels de quien vende (máximo {v['max_vendedor']:.0%})",
}
status = "passed"ifall(x == "ok"for x in checks.values()) else"failed"
(DATA / "validation.json").write_text(json.dumps({"snapshot_id": p["snapshot"]["id"], "padre": p["snapshot"]["padre"],
"status": status, "checks": checks}, ensure_ascii=False, indent=2) + "\n")
for k, x in checks.items():
print(f" {'✓' if x == 'ok' else '✗'} {k:<15} {x}")
print(f"{status}: {len(rows)} filas = {razon:.2f} × las {len(padre)} del padre · quien vende {f_vend:.1%} · {len(comunes)} vendedores en los dos, {movidos} movidos")
sys.exit(0if status == "passed"else1)
Terminal
python pipeline/4_validar.py
Salida
✓ esquema ok
✓ categorias ok
✓ duplicados ok
✓ golden ok
✓ split_vendedor ok
✓ split_estable ok
✓ volumen ok
✓ vendedor ok
passed: 2467 filas = 1.23 × las 2013 del padre · quien vende 75.6% · 298 vendedores en los dos, 0 movidos
Listo cuando: data/validation.json con status: passed y las 8 reglas.
Ojo: Un contrato que imprime un aviso y deja seguir no detiene nada. Cada regla viene de un error real: si dudas de una, pregúntate qué falla real atrapa.
Concepto de este paso ↓
Contrato de datosdata contractLas reglas que los datos cumplen antes de entrenar: esquema exacto, categorías válidas, cero duplicados, cero golden, split por vendedor y estable, volumen en rango y tope de labels débiles.Analogía, por qué importa y la trampa ↓
AnalogíaLa revisión de un avión antes de despegar: una lista fija, la misma cada vez, y si un punto falla no se despega.
Por qué importaDetiene el pipeline antes de gastar GPU. Cada regla viene de un error real: un join que duplica, el golden en train, un split que se movió.
TrampaUn contrato que solo avisa y deja seguir no es contrato: el paso de validar tiene que fallar (código de salida 1) para que nada se publique.
Precálculo ↓
5
¿Cuántas filas son normales para el snapshot nuevo, y cuándo es sospechoso?
razón = filas nuevas ÷ filas del padre; el contrato acepta entre 0.8 y 1.5
En C01con 1,932,628 filas, el padre tendría que estar entre 1,932,628 ÷ 1.5 y 1,932,628 ÷ 0.8entre ≈ 1.29 M y ≈ 2.42 M filas
En el dojopadre de 2,013 filas × 0.8 y × 1.5entre 1,610 y 3,020 filas; esperas ≈ 2,013 + las de agosto que maduraron
Qué decides con esto. Un volumen fuera de rango casi nunca es «el negocio creció»: es un join que duplicó, un corte en la zona horaria equivocada o un filtro que se comió medio mes. El pipeline se detiene antes de gastar GPU.
Lo confirmas en el paso 4: 2,467 filas = 1.23 × las 2,013 del padre.
5Publicar sin pisarEl snapshot en s3://ml-datos/datasets/ds-2026-09-01/, escrito una sola vez, con la tarjeta al final.
Tres defensas. Cada PUT lleva IfNoneMatch="*": si la llave existe, S3 responde 412 y no toca nada. Si ya está con el mismo contenido, el paso sigue: correrlo dos veces deja lo mismo (idempotente). La tarjeta va al final: un snapshot sin tarjeta no existe. Y el bucket guarda versiones, así que cualquier reescritura deja rastro. Antes de publicar, tu código va en un commit: la tarjeta guarda ese commit.
Pythonpipeline/5_publicar.py
"""Paso 5 · Publicar el snapshot: inmutable, con la tarjeta al final.
Entra: data/rows.parquet, data/validation.json de los pasos 3 y 4
params.yaml snapshot.id, snapshot.padre, snapshot.corte, split.umbral
Sale: s3://ml-datos/datasets/<id>/rows.parquet, validation.json y, al final, snapshot.json (la tarjeta)
data/publicado.json el recibo: id, rows_sha256 y la version_id de cada llave
Reglas: solo publica si la validación pasó y tu código está en un commit (la tarjeta guarda ese commit).
Toda escritura lleva If-None-Match: * (no pisa nada). Si la llave ya existe con el mismo contenido, sigue
(correrlo dos veces deja lo mismo); si existe con otro contenido, se detiene: un contenido nuevo lleva un id nuevo.
"""import json
import re
import subprocess
import sys
from datetime import datetime, timezone
import pandas as pd
from botocore.exceptions import ClientError
from _comun import DATA, DATOS, RAIZ, params, s3, sha256
p = params()
sid = p["snapshot"]["id"]
ifnot re.fullmatch(r"ds-\d{4}-\d{2}-\d{2}(-r\d+)?", sid):
sys.exit(f"✗ «{sid}» no es un id de snapshot (ds-AAAA-MM-DD, o ds-AAAA-MM-DD-rN si se reemite)")
val = json.loads((DATA / "validation.json").read_text())
if val["status"] != "passed"or val["snapshot_id"] != sid:
sys.exit("✗ la validación no pasó (o es de otro id): no se publica nada")
git = lambda *a: subprocess.run(["git", *a], cwd=RAIZ, capture_output=True, text=True).stdout.strip() # noqa: E731
commit = git("rev-parse", "HEAD")
ifnot commit orgit("status", "--porcelain", "--", "pipeline", "dvc.yaml"):
sys.exit("✗ tu código tiene cambios sin commit: la tarjeta no podría decir con qué código se armó. git commit primero")
rows_b = (DATA / "rows.parquet").read_bytes()
huella = sha256(rows_b)
rows = pd.read_parquet(DATA / "rows.parquet")
cliente, base = s3(), f"datasets/{sid}"defponer(nombre: str, cuerpo: bytes) -> str:
"""PUT condicional: escribe solo si la llave no existe. Devuelve la version_id de lo que quedó."""
key = f"{base}/{nombre}"try:
return cliente.put_object(Bucket=DATOS, Key=key, Body=cuerpo, IfNoneMatch="*")["VersionId"]
except ClientError as e:
if e.response["Error"]["Code"] != "PreconditionFailed":
raise
ya = cliente.get_object(Bucket=DATOS, Key=key)
ifsha256(ya["Body"].read()) != sha256(cuerpo):
sys.exit(f"✗ {key} ya existe con otro contenido (412 Precondition Failed). Un snapshot publicado no se reescribe: ""si el contenido cambió, usa un id nuevo en params.yaml")
print(f" {nombre}: ya estaba, mismo contenido")
return ya["VersionId"]
versiones = {"rows.parquet": poner("rows.parquet", rows_b),
"validation.json": poner("validation.json", (DATA / "validation.json").read_bytes())}
tarjeta = {
"snapshot_id": sid, "parent": p["snapshot"]["padre"], "corte": p["snapshot"]["corte"],
"created_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
"rows_path": f"s3://{DATOS}/{base}/rows.parquet", "rows_sha256": huella,
"counts": {"train": int((rows["split"] == "train").sum()), "val": int((rows["split"] == "val").sum()), "total": len(rows)},
"label_sources": {k: round(float(x), 3) for k, x in rows["label_source"].value_counts(normalize=True).sort_index().items()},
"split": {"by": "seller_id", "rule": f"sha256(seller_id) mod 100 < {p['split']['umbral']} -> train"},
"code": {"repo": "c01-versionado", "commit": commit},
"validation": {"status": val["status"], "report": f"s3://{DATOS}/{base}/validation.json"},
}
try: # la tarjeta va al final: un snapshot sin tarjeta no existe
versiones["snapshot.json"] = cliente.put_object(Bucket=DATOS, Key=f"{base}/snapshot.json", IfNoneMatch="*",
Body=json.dumps(tarjeta, ensure_ascii=False, indent=2).encode())["VersionId"]
except ClientError as e:
if e.response["Error"]["Code"] != "PreconditionFailed":
raise
ya = json.loads(cliente.get_object(Bucket=DATOS, Key=f"{base}/snapshot.json")["Body"].read())
if ya["rows_sha256"] != huella:
sys.exit(f"✗ {base}/snapshot.json ya existe y describe otras filas: usa un id nuevo")
tarjeta = ya
versiones["snapshot.json"] = cliente.head_object(Bucket=DATOS, Key=f"{base}/snapshot.json")["VersionId"]
print(" snapshot.json: ya estaba, describe las mismas filas")
(DATA / "publicado.json").write_text(json.dumps({"snapshot_id": sid, "rows_sha256": huella, "versiones": versiones}, indent=2) + "\n")
print(f"publicado s3://{DATOS}/{base}/ · rows_sha256 {huella[:12]}… · {tarjeta['counts']} · commit {tarjeta['code']['commit'][:7]}")
Terminal
python pipeline/5_publicar.py
Primero sin commit: se niega.
Salida
✗ tu código tiene cambios sin commit: la tarjeta no podría decir con qué código se armó. git commit primero
[código 1]
Terminal
git add -A&&git commit -m"pipeline: pasos 1 a 5"python pipeline/5_publicar.py
Lo que pasa si alguien intenta pisarlo con otro contenido.
Salida
ClientError · An error occurred (PreconditionFailed) when calling the PutObject operation: At least one of the pre-conditions you specified did not hold
datasets/ds-2026-09-01/rows.parquet
2026-11-16 01:39:51 UTC vigente 241680 B sha256 a023a080132a… version 201a0b4b-7153-4886-a6e5-69e800581691
datasets/ds-2026-09-01/snapshot.json
2026-11-16 01:39:51 UTC vigente 778 B sha256 bb923cb10179… version 0307e2fc-bf1a-47c0-b1fd-cb93dec18205
datasets/ds-2026-09-01/validation.json
2026-11-16 01:39:51 UTC vigente 292 B sha256 493b19c2da1f… version a1e0544f-10f6-43d2-8539-46dd467f1c7f
Terminal
python-c"import sys; sys.path.insert(0, 'pipeline'); from _comun import s3; print(s3().get_object(Bucket='ml-datos', Key='datasets/ds-2026-09-01/snapshot.json')['Body'].read().decode())"
La tarjeta: el commit y la hora cambian en tu máquina.
✓ snapshot ds-2026-09-01: 2467 filas (2309 train · 158 val) · rows_sha256 a023a080132a… · parent ds-2026-08-01 · commit 1782106
✓ inmutable versionado Enabled · 2 snapshots (ds-2026-08-01, ds-2026-09-01): cada llave escrita una sola vez y cada uno igual a su tarjeta
2/2 en verde
Listo cuando: La tarjeta, el manifest y el reporte en S3, una versión por llave, y rows_sha256 igual al de tu data/rows.parquet.
Ojo: La tarjeta es lo último que se escribe y lo primero que se lee. Compárala con la de agosto (el mismo comando con ds-2026-08-01): mismo formato, otro parent, otro corte y otro commit. Y en la consola web (http://localhost:9301) puedes ver las versiones de cada llave.
Conceptos de este paso ↓
Escribir, auditar, publicarwrite-audit-publishEl snapshot se arma aparte, se audita con el contrato y solo si pasa se publica, con la tarjeta al final.Analogía, por qué importa y la trampa ↓
AnalogíaImprimir el periódico de prueba, revisarlo y solo entonces mandarlo a todos los puestos.
Por qué importaUn job que se cae a medias no deja un snapshot «a medias» que alguien pueda usar: sin tarjeta no existe. En el dojo, «aparte» es data/ en tu Mac; en C01, un prefijo staging/.
TrampaPublicar la tarjeta primero (o en medio) abre la puerta a entrenar con algo que nadie revisó.
Escritura condicionalconditional write (If-None-Match: *)Un PUT que solo se cumple si la llave no existe. Si ya existe, S3 responde 412 Precondition Failed y no toca nada.Analogía, por qué importa y la trampa ↓
AnalogíaUn buzón con candado: puedes dejar una carta nueva, pero no cambiar la que ya está adentro.
Por qué importaSin ella, un PUT a una llave que existe reemplaza el objeto en silencio: gana el último. Con ella, reescribir un snapshot es un error ruidoso.
TrampaEl header lo pone quien escribe: un script que no lo pone escribe igual. En AWS se vuelve obligatorio con la política del bucket; RustFS no tiene esa condición, así que aquí depende de tu código. Y con versiones solo mira la versión vigente: si es una marca de borrado, el PUT pasa.
Versionado del bucketS3 Versioning y delete markersCon el versionado prendido, un PUT a una llave existente guarda una versión nueva sin destruir la vieja, y un DELETE solo pone una marca de borrado encima.Analogía, por qué importa y la trampa ↓
AnalogíaUn documento con historial de cambios: puedes volver a cualquier versión, y borrar es tachar, no quemar.
Por qué importaEs la red de seguridad: lo que se pisó o se borró por error se recupera borrando la versión mala o la marca. Y deja rastro de cada reescritura.
TrampaProtege versiones, no llaves: el PUT nuevo pasa y es lo que se lee. Y para un borrado por ley hay que borrar cada versión, no solo poner la marca.
Tarjeta del snapshotdataset cardUn JSON chico junto al manifest (snapshot.json): id, padre, corte, conteos, mezcla de fuentes, regla del split, commit del código, rows_sha256 y resultado de la validación.Analogía, por qué importa y la trampa ↓
AnalogíaLa etiqueta de un frasco de laboratorio: qué hay, de qué lote salió, quién lo preparó y cuándo.
Por qué importaEl manifest dice qué hay; la tarjeta, de dónde salió y cómo comprobarlo. Se escribe al final: un snapshot sin tarjeta no existe.
TrampaEl commit de la tarjeta es el del código que armó el snapshot, no el que entrena. Cada artefacto apunta a su propio código.
Precálculo ↓
2
¿Cuánto cuesta guardar un año de snapshots citando, contra copiar las fotos cada mes?
En C0112 × 97 MB = 1.16 GB × US$0.023 por GB al mes, contra 12 × 387 GB × 0.023 (S3 Standard, us-east-1)≈ US$0.03 al mes contra ≈ US$107 al mes, y copiar crece cada mes
En el dojo12 × 242 kB ≈ 2.9 MB, contra 12 × 6.1 MB ≈ 73 MBen tu Mac cuesta cero, pero la proporción es la misma idea
Qué decides con esto. Un snapshot por mes, para siempre, cabe en el presupuesto. Lo caro es copiar. El precio escondido: si el producto borra una foto, la fila apunta a nada; por eso se comprueba al leer y se anota cada borrado.
Lo confirmas en el paso 5: mundo/s3.py versiones muestra rows.parquet de 241,680 B.
6El pipeline como DAGLos pasos 1 a 5 en dvc.yaml: dvc repro corre solo lo que cambió.
Cada stage dice qué corre, qué lee (deps), qué parámetros de params.yaml usa (params) y qué deja (outs). DVC hashea todo eso y lo guarda en dvc.lock; la próxima vez solo corre un stage si algo de su llave cambió. Es la caché de pasos de un orquestador, en tu Mac. Por eso cada parámetro que lee un script va declarado en su stage, y el snapshot se pide por id.
YAMLdvc.yaml
# El pipeline mensual como DAG: cada paso dice qué lee (deps), qué parámetros usa (params) y qué deja (outs).# DVC hashea todo eso; si nada cambió, no vuelve a correr el paso. Por eso cada parámetro que lee un script va aquí.stages:
labels:
cmd: python pipeline/1_labels.py
deps: [pipeline/1_labels.py, pipeline/_comun.py, entrada/labels-eventos.parquet]
params: [snapshot.corte, labels.dias_maduracion]
outs: [data/labels.parquet]
manifest:
cmd: python pipeline/2_manifest.py
deps: [pipeline/2_manifest.py, data/labels.parquet, entrada/publicaciones.parquet]
outs: [data/manifest.parquet]
split:
cmd: python pipeline/3_split.py
deps: [pipeline/3_split.py, data/manifest.parquet, entrada/borrados.csv, entrada/golden.parquet]
params: [snapshot.corte, split.umbral]
outs: [data/rows.parquet]
validar:
cmd: python pipeline/4_validar.py
deps: [pipeline/4_validar.py, data/rows.parquet, entrada/categorias.json, entrada/golden.parquet]
params: [snapshot.id, snapshot.padre, validar]
outs: [data/validation.json]
publicar:
cmd: python pipeline/5_publicar.py
deps: [pipeline/5_publicar.py, data/rows.parquet, data/validation.json]
params: [snapshot.id, snapshot.padre, snapshot.corte, split.umbral]
outs: [data/publicado.json]
Las fotos del bucket no son una dependencia de DVC: si una cambia bajo la misma llave, DVC no se entera. Por eso el entrenamiento comprueba cada huella (paso 7).
Terminal
git add -A&&git commit -m"el pipeline como DAG"dvc repro
La primera vez no hay dvc.lock: corre todo. Publicar es idempotente, así que no pasa nada en S3.
Salida
Running stage 'labels':
> python pipeline/1_labels.py
eventos: 3908 · antes del corte 2026-10-01 00:00 UTC: 3796 · después (se ignoran): 112
fotos con label vigente: 3120 · sin madurar (quien vende, < 30 días): 507
data/labels.parquet: 2613 labels · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
Running stage 'manifest':
> python pipeline/2_manifest.py
data/manifest.parquet: 2613 filas · 2499 huellas distintas · 300 vendedores
fotos citadas: 6.1 MB · manifest: 246 kB
Running stage 'split':
> python pipeline/3_split.py
manifest: 2613 · borradas antes del corte: 13 · duplicadas por huella: 114 · del golden set: 19
data/rows.parquet: 2467 filas · {'train': 2309, 'val': 158} · vendedores en val: 17
Running stage 'validar':
> python pipeline/4_validar.py
passed: 2467 filas = 1.23 × las 2013 del padre · quien vende 75.6% · 298 vendedores en los dos, 0 movidos
Running stage 'publicar':
> python pipeline/5_publicar.py
rows.parquet: ya estaba, mismo contenido
validation.json: ya estaba, mismo contenido
snapshot.json: ya estaba, describe las mismas filas
publicado s3://ml-datos/datasets/ds-2026-09-01/ · rows_sha256 a023a080132a… · {'train': 2309, 'val': 158, 'total': 2467} · commit 1782106
Terminal
dvc repro
La segunda: nada cambió, nada corre.
Salida
Stage 'labels' didn't change, skipping
Stage 'manifest' didn't change, skipping
Stage 'split' didn't change, skipping
Stage 'validar' didn't change, skipping
Stage 'publicar' didn't change, skipping
Data and pipelines are up to date.
git add dvc.lock &&git commit -m"ds-2026-09-01"python verificar.py dag
Salida
✓ dag 5 stages, con sus params declarados · dvc status: al día
1/1 en verde
Listo cuando: 5 stages con sus parámetros declarados y dvc status al día.
Ojo: Si un script lee split.umbral pero el stage no lo declara, cambiarlo no hace correr nada y DVC te da la salida vieja sin avisar. Es la trampa de latest en otra forma: la llave de la caché no ve lo que cambió.
Conceptos de este paso ↓
DAG y caché de pasospipeline DAG y step cacheEl pipeline como pasos con flechas (qué lee y qué deja cada uno). La herramienta guarda la salida de cada paso con una llave hecha de su código, sus parámetros y sus entradas, y la reusa si la llave no cambió.Analogía, por qué importa y la trampa ↓
AnalogíaUna receta con pasos: si ya picaste la cebolla y nadie cambió la cebolla, no la vuelves a picar.
Por qué importaAhorra horas y hace que repetir el pipeline sea seguro. dvc.lock guarda las huellas de cada entrada y salida: también es linaje.
TrampaLo que no está en la llave no existe para la caché: un parámetro que el script lee pero el stage no declara no hace correr el paso, y sale la salida vieja.
Paso idempotenteidempotent stepCorrerlo dos veces deja lo mismo que correrlo una.Analogía, por qué importa y la trampa ↓
AnalogíaEl botón del elevador: picarle cinco veces no llama cinco elevadores.
Por qué importaEl orquestador reintenta pasos que fallan a la mitad. Publicar otra vez el mismo contenido sigue sin error; otro contenido con el mismo id se detiene.
TrampaIdempotente no es «sobrescribe sin preguntar»: eso borra la historia. Es «si ya está igual, no hago nada».
7Entrenar con linajeUna corrida que entrena con ds-2026-09-01, comprueba cada huella al leer y deja sus punteros.
La estación 3 entrena de verdad; aquí importa la entrada y lo que queda anotado. El snapshot llega por id. Se lee la tarjeta primero (sin tarjeta no hay snapshot), se comprueba rows_sha256 y la huella de cada foto. Las fotos del registro de borrados se saltan. La corrida guarda los punteros: snapshot y su huella, commit (con el árbol limpio), huella del entorno y semilla.
Pythonpipeline/6_entrenar.py
"""Paso 6 · Entrenar con un snapshot, comprobando todo al leer, y dejar los punteros del linaje.
Entra: params.yaml entrenar.snapshot (un id, nunca «latest») y entrenar.semilla
s3://ml-datos/datasets/<id>/ la tarjeta y las filas
s3://fotos/… cada foto, por su llave
entrada/borrados.csv las fotos que se borraron: se saltan, con cualquier fecha
Sale: corridas/run-AAAAMMDD-HHMMSS.json run_id, modelo, fecha, snapshot, rows_sha256, commit, arbol_limpio,
entorno_sha256, semilla, metricas y filas {train, val, omitidas_borradas}
Reglas: sin tarjeta no hay snapshot; si la huella de las filas o de una foto no coincide, se detiene.
Solo entrena desde un commit con el árbol limpio (pipeline/, dvc.yaml, dvc.lock, params.yaml).
"""import io
import json
import re
import subprocess
import sys
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, timezone
import pandas as pd
from botocore.exceptions import ClientError
from _comun import CORRIDAS, DATOS, ENTRADA, FOTOS, RAIZ, entrenar, huella_entorno, params, s3, sha256
p = params()["entrenar"]
sid = str(p["snapshot"])
ifnot re.fullmatch(r"ds-\d{4}-\d{2}-\d{2}(-r\d+)?", sid):
sys.exit(f"✗ entrenar.snapshot = «{sid}»: tiene que ser un id de snapshot. Una carpeta como «latest» cambia de ""contenido y la corrida no podría decir con qué datos entrenó")
git = lambda *a: subprocess.run(["git", *a], cwd=RAIZ, capture_output=True, text=True).stdout.strip() # noqa: E731
commit = git("rev-parse", "HEAD")
sucio = git("status", "--porcelain", "--", "pipeline", "dvc.yaml", "dvc.lock", "params.yaml")
ifnot commit or sucio:
sys.exit(f"✗ hay cambios sin commit ({sucio.splitlines()[0] if sucio else 'no hay commits'}): el commit no diría qué código corrió")
cliente = s3()
try:
tarjeta = json.loads(cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/snapshot.json")["Body"].read())
except ClientError:
sys.exit(f"✗ {sid} no tiene tarjeta (snapshot.json): un snapshot sin tarjeta no existe")
crudo = cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/rows.parquet")["Body"].read()
ifsha256(crudo) != tarjeta["rows_sha256"]:
sys.exit(f"✗ las filas de {sid} no coinciden con su tarjeta: alguien las reescribió")
filas = pd.read_parquet(io.BytesIO(crudo))
borrados = set(pd.read_csv(ENTRADA / "borrados.csv")["image_sha256"])
omitidas = filas["image_sha256"].isin(borrados)
leer = filas[~omitidas]
deffoto(fila):
try:
b = cliente.get_object(Bucket=FOTOS, Key=fila.image_key)["Body"].read()
except ClientError:
return fila.image_key, None, "no existe"return fila.image_key, b, Noneifsha256(b) == fila.image_sha256 else"su huella no coincide"withThreadPoolExecutor(16) as ex:
fotos = list(ex.map(foto, leer.itertuples()))
malas = [(k, err) for k, _, err in fotos if err]
if malas:
sys.exit(f"✗ {len(malas)} fotos no se pueden usar, por ejemplo {malas[0][0]}: {malas[0][1]}. ""Si alguien pidió borrarlas, anótalas en entrada/borrados.csv")
bytes_de = {k: b for k, b, _ in fotos}
tr = [(bytes_de[f.image_key], int(f.label_id)) for f in leer.itertuples() if f.split == "train"]
va = [(bytes_de[f.image_key], int(f.label_id)) for f in leer.itertuples() if f.split == "val"]
metricas = entrenar(tr, va, p["semilla"])
ahora = datetime.now(timezone.utc)
corrida = {"run_id": f"run-{ahora:%Y%m%d-%H%M%S}", "modelo": f"modelo-{ahora:%Y-%m-%d}", "fecha": ahora.isoformat(timespec="seconds"),
"snapshot": sid, "rows_sha256": tarjeta["rows_sha256"], "commit": commit, "repo": "c01-versionado", "arbol_limpio": True,
"entorno_sha256": huella_entorno(), "semilla": p["semilla"], "metricas": metricas,
"filas": {"train": len(tr), "val": len(va), "omitidas_borradas": int(omitidas.sum())}}
CORRIDAS.mkdir(exist_ok=True)
(CORRIDAS / f"{corrida['run_id']}.json").write_text(json.dumps(corrida, ensure_ascii=False, indent=2) + "\n")
print(f"{len(leer)} fotos leídas y comprobadas · {int(omitidas.sum())} omitidas por borrado")
print(f"corridas/{corrida['run_id']}.json: {corrida['modelo']} ← {sid} ({tarjeta['rows_sha256'][:12]}…) · commit {commit[:7]} · "f"entorno {corrida['entorno_sha256'][:12]}… · accuracy_val {metricas['accuracy_val']}")
Terminal
python pipeline/6_entrenar.py
Con el script recién escrito y sin commit: se niega.
Salida
✗ hay cambios sin commit (M pipeline/6_entrenar.py): el commit no diría qué código corrió
[código 1]
Terminal
git add -A&&git commit -m"entrenar con linaje"python pipeline/6_entrenar.py
✓ corrida run-20261116-013958 · modelo-2026-11-16 ← ds-2026-09-01 (a023a080132a…) · commit 6ac383f · entorno b25ca3c501e2… · accuracy_val 0.7468
✓ lectura ds-2026-09-01: 2467 fotos existen y su huella coincide · 0 filas en el registro de borrados (se saltan)
2/2 en verde
Listo cuando: Tu corrida apunta a ds-2026-09-01 con su rows_sha256, un commit limpio y la huella del entorno; las 2,467 fotos se leen y coinciden.
Ojo: 0 omitidas: las fotos borradas en septiembre ya no están en este snapshot. Si entrenaras otra vez con ds-2026-08-01, se saltarían 13.
Conceptos de este paso ↓
Id como parámetro, nunca «latest»pass the snapshot id, not a moving pathToda entrada que cambia el resultado llega como un id fijo (ds-2026-09-01), nunca como una carpeta que cambia de contenido sin cambiar de nombre.Analogía, por qué importa y la trampa ↓
AnalogíaPedir «el libro con ISBN tal» en vez de «el libro de la repisa de arriba»: alguien puede cambiar el de la repisa.
Por qué importaLa corrida guarda un puntero que siempre dice lo mismo. Con latest, el registro no dice con qué entrenó y la caché ve la misma llave dos meses seguidos.
Trampa«Para no editar params.yaml cada mes» es la excusa típica. Cambiar el id cada mes es trabajo del orquestador, no de una carpeta mágica.
Commit con el árbol limpioclean working treeEntrenar (y publicar) solo desde un commit sin cambios pendientes en el código, para que el commit diga exactamente qué corrió.Analogía, por qué importa y la trampa ↓
AnalogíaFirmar un contrato solo cuando ya no tiene tachones a mano.
Por qué importaEl commit es uno de los cinco ingredientes de la reproducibilidad (código, datos, configuración, entorno y semilla). Si el script tenía cambios sin commit, el puntero apunta a otro código.
Trampadvc repro cambia dvc.lock: hay que hacer commit después de cada repro, antes de entrenar.
LinajelineageLa cadena de qué salió de qué: modelo ← corrida ← snapshot (id + rows_sha256) ← cada foto (llave + huella), más el commit y el entorno. Se guarda como punteros, no como copias.Analogía, por qué importa y la trampa ↓
AnalogíaEl árbol genealógico con acta de nacimiento en cada rama.
Por qué importaResponde en un minuto las tres preguntas: con qué datos se entrenó, si cambió el código o los datos, y en qué modelos está la foto que pidieron borrar.
TrampaUn puntero que se escribe a mano o «después» se desfasa. Lo escribe el mismo programa que entrena, en el momento.
Precálculo ↓
3
¿Cuánto tarda comprobar la huella de cada foto al leerla?
tiempo = bytes de fotos ÷ velocidad de sha256 en un núcleo
En C01387 GB ÷ ≈ 2.9 GB/s (lo que mide tu Mac) = ≈ 133 s de CPU en un núcleo≈ 2 minutos, contra las 3–4 horas de GPU del fine-tune
En el dojo6.1 MB ÷ 2.9 GB/s≈ 2 ms: lo que tarda es leer del S3, no hashear
Qué decides con esto. Comprobar cada foto al leer es casi gratis frente al entrenamiento. No hay excusa para no hacerlo: si una foto cambió bajo la misma llave, el entrenamiento se detiene en vez de aprender otra cosa.
Terminalterminal · compruébalo en el kit
python-c"import hashlib, time; b = bytes(512 * 2**20); t = time.perf_counter(); hashlib.sha256(b).hexdigest(); s = time.perf_counter() - t; print(f'sha256 de 512 MiB en {s:.2f} s: {512 / 1024 / s:.1f} GiB/s en un núcleo')"
En una M4. 2.7 GiB/s son ≈ 2.9 GB/s. Tu número puede variar.
Salida
sha256 de 512 MiB en 0.19 s: 2.7 GiB/s en un núcleo
8El linaje al revésDe una huella a los snapshots, las corridas y el borrado.
La pregunta de privacidad: alguien pide borrar sus fotos, ¿en qué snapshots y en qué modelos están? Con los punteros es mecánico: buscas la huella en los manifests (comprobados con su tarjeta) y sigues las corridas que usaron esos snapshots.
Pythonpipeline/7_linaje.py
"""Paso 7 · El linaje al revés: ¿en qué snapshots y en qué modelos está esta foto?
python pipeline/7_linaje.py <sha256> # la huella completa o sus primeros 12+ caracteres
python pipeline/7_linaje.py <sha256> --json # lo mismo, en JSON (lo usa verificar.py)
Entra: s3://ml-datos/datasets/*/ cada snapshot con tarjeta (sus filas, comprobadas con su huella)
corridas/*.json cada corrida y el snapshot con que entrenó
entrada/borrados.csv si alguien pidió borrarla
Sale: {"sha256", "snapshots": [{"id", "split", "image_keys"}], "corridas": [{"run_id", "modelo", "snapshot"}],
"borrado": {"fecha", "motivo"} o null}
"""import io
import json
import sys
import pandas as pd
from _comun import CORRIDAS, DATOS, ENTRADA, s3, sha256
args = [a for a in sys.argv[1:] ifnot a.startswith("--")]
ifnot args orlen(args[0]) < 12:
sys.exit("uso: python pipeline/7_linaje.py <sha256 (12+ caracteres)> [--json]")
buscada = args[0].lower()
cliente = s3()
r = cliente.list_objects_v2(Bucket=DATOS, Prefix="datasets/", Delimiter="/")
snaps = []
for sid insorted(x["Prefix"].split("/")[1] for x in r.get("CommonPrefixes", [])):
try:
tarjeta = json.loads(cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/snapshot.json")["Body"].read())
except cliente.exceptions.NoSuchKey:
continue# sin tarjeta no es un snapshot
crudo = cliente.get_object(Bucket=DATOS, Key=f"datasets/{sid}/rows.parquet")["Body"].read()
ifsha256(crudo) != tarjeta["rows_sha256"]:
sys.exit(f"✗ las filas de {sid} no coinciden con su tarjeta: el linaje no es confiable")
f = pd.read_parquet(io.BytesIO(crudo), columns=["image_key", "image_sha256", "split"])
hay = f[f["image_sha256"].str.startswith(buscada)]
iflen(hay):
snaps.append({"id": sid, "split": hay["split"].iloc[0], "image_keys": sorted(hay["image_key"])})
ids = {s["id"] for s in snaps}
corridas = sorted((json.loads(c.read_text()) for c in CORRIDAS.glob("*.json")), key=lambda c: c["fecha"])
usan = [{"run_id": c["run_id"], "modelo": c["modelo"], "snapshot": c["snapshot"]} for c in corridas if c["snapshot"] in ids]
b = pd.read_csv(ENTRADA / "borrados.csv")
b = b[b["image_sha256"].str.startswith(buscada)]
borrado = {"fecha": b["fecha"].iloc[0], "motivo": b["motivo"].iloc[0]} iflen(b) elseNone
out = {"sha256": buscada, "snapshots": snaps, "corridas": usan, "borrado": borrado}
if"--json"in sys.argv:
print(json.dumps(out, ensure_ascii=False, indent=2))
else:
print(f"foto {buscada[:12]}…")
for s in snaps:
print(f" snapshot {s['id']} · {s['split']} · {', '.join(s['image_keys'])}")
for c in usan:
print(f" corrida {c['run_id']} · {c['modelo']} ← {c['snapshot']}")
print(f" borrada el {borrado['fecha']}: {borrado['motivo']}"if borrado else" no está en el registro de borrados")
ifnot snaps:
print(" no aparece en ningún snapshot")
Una foto de la vendedora que pidió borrar: está en el snapshot de agosto y en el modelo de septiembre; el de septiembre ya no la trae.
Salida
foto 299c10e75b6a…
snapshot ds-2026-08-01 · train · 2026/04/14/p-000237.jpg
corrida run-20260901-061500 · modelo-2026-09-01 ← ds-2026-08-01
borrada el 2026-09-15T10:00:00Z: derecho al borrado (solicitud del 2026-09-14)
Terminal
python pipeline/7_linaje.py 000706ca7a412e4b
Una foto que está en los dos snapshots, y por lo tanto en los dos modelos.
Salida
foto 000706ca7a41…
snapshot ds-2026-08-01 · train · 2026/05/03/p-000555.jpg
snapshot ds-2026-09-01 · train · 2026/05/03/p-000555.jpg
corrida run-20260901-061500 · modelo-2026-09-01 ← ds-2026-08-01
corrida run-20261116-013958 · modelo-2026-11-16 ← ds-2026-09-01
no está en el registro de borrados
Terminal
python verificar.py
Todo junto.
Salida
✓ mundo S3 local con fotos (1000+) y ml-datos (ds-2026-08-01 publicado) · entrada/ completa · git y DVC 3.67.1
✓ labels 2613 labels vigentes al 2026-10-01T00:00:00Z · {'vendedor': 1966, 'humano': 465, 'moderador': 182}
✓ manifest 2613 filas, cada una con su llave y su huella · manifest 246 kB · cita 6.1 MB de fotos
✓ split 2467 filas: sin duplicados, sin golden, sin borrados · {'train': 2309, 'val': 158} por vendedor
✓ split-estable 298 vendedores en los dos snapshots, 0 cambiaron de lado · ninguna foto de val del padre en train
✓ validacion passed: esquema, categorias, duplicados, golden, split_vendedor, split_estable, volumen, vendedor
✓ snapshot ds-2026-09-01: 2467 filas (2309 train · 158 val) · rows_sha256 a023a080132a… · parent ds-2026-08-01 · commit 1782106
✓ inmutable versionado Enabled · 2 snapshots (ds-2026-08-01, ds-2026-09-01): cada llave escrita una sola vez y cada uno igual a su tarjeta
✓ dag 5 stages, con sus params declarados · dvc status: al día
✓ corrida run-20261116-013958 · modelo-2026-11-16 ← ds-2026-09-01 (a023a080132a…) · commit 6ac383f · entorno b25ca3c501e2… · accuracy_val 0.7468
✓ lectura ds-2026-09-01: 2467 fotos existen y su huella coincide · 0 filas en el registro de borrados (se saltan)
✓ linaje 299c10e7… → 1 snapshots, 1 corridas, borrada · 000706ca… → 2 snapshots, 2 corridas
12/12 en verde
Listo cuando: verificar.py completo: 12/12 en verde.
Ojo: El modelo de septiembre aprendió con fotos que ya se borraron. Qué hacer con él (reentrenar antes, esperar al siguiente) se decide aparte; el linaje es lo que te deja contestar en un minuto.
Solo
12 objetivos
Antes de empezar, python mundo/reiniciar.py --pipeline: respalda tus archivos en .respaldo/, pone el esqueleto (pipeline/, dvc.yaml vacío, params.yaml de fábrica) y borra data/, tus corridas y los snapshots que publicaste. El de agosto se queda. Haz commit del esqueleto.
Solo tienes OBJETIVOS.md, los contratos al inicio de cada archivo y python verificar.py. Nada de GUION.md ni de mundo/comun.py.
Claude no te da código: te dice qué check falla y te contesta con preguntas.
Mide tu tiempo por objetivo y anota en la bitácora dónde te atoraste.
01El S3 local arriba, el mundo creado, la carpeta en git y DVC iniciado.python verificar.py mundo
02Los labels vigentes al corte, uno por foto, con la regla de 30 días.python verificar.py labelsPista: Primero filtra por hora, después ordena y quédate con el último.
03El manifest: una fila por label, con su llave y su huella.python verificar.py manifest
04Las filas del snapshot sin borrados (al corte), sin duplicados, sin golden y con el split por vendedor.python verificar.py splitPista: De las huellas repetidas, ¿cuál publicación no cambia de un mes a otro?
05Ningún vendedor cambia de lado contra el snapshot de agosto.python verificar.py split-estable
06El reporte del contrato de datos, con las 8 reglas en verde.python verificar.py validacion
07El snapshot publicado en S3 con su tarjeta, desde un commit, igual a tu data/rows.parquet.python verificar.py snapshot
08Cada llave de datasets/ escrita una sola vez, con versionado y escritura condicional.python verificar.py inmutablePista: ¿Qué header hace que S3 conteste 412?
09Los 5 pasos en dvc.yaml, con sus parámetros declarados, y dvc status al día.python verificar.py dag
10Una corrida con un id de snapshot, su huella, un commit limpio, la huella del entorno y la semilla.python verificar.py corrida
11Todas las fotos del snapshot de entrenamiento existen y coinciden, salvo las del registro de borrados.python verificar.py lectura
12De una huella a sus snapshots, sus corridas y su borrado, en JSON con --json.python verificar.py linaje
Romper
7 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
mundo
El snapshot de agosto ya no es el de agosto
Una analista encontró una etiqueta mal en el snapshot de agosto y la «arregló» directo en el bucket, para no esperar al de septiembre. Dice que fue una sola fila.
Síntoma. verificar.py: split-estable e inmutable fallan: las filas de ds-2026-08-01 no coinciden con su tarjeta. 9/12 en verde · falta: split-estable, inmutable, linaje
datasets/ds-2026-08-01/rows.parquet
2026-11-16 01:39:42 UTC anterior 197087 B sha256 438890addbc4… version 0a418377-e76c-415f-9c3f-fb48337766b7
datasets/ds-2026-08-01/rows.parquet
2026-11-16 01:40:24 UTC vigente 197087 B sha256 7485a07c0d13… version ac12099f-1113-4bd2-b294-f4518f475a25
El arreglo. rows.parquet tiene dos versiones: la anterior tiene la huella de la tarjeta. Borra la vigente, la mala: python mundo/s3.py borrar-version ml-datos datasets/ds-2026-08-01/rows.parquet <version_id>. La buena vuelve a ser la vigente. Si la corrección era real, va como evento nuevo y entra al snapshot siguiente.
datasets/ds-2026-09-01/rows.parquet
2026-11-16 01:39:51 UTC vigente 241680 B sha256 a023a080132a… version 201a0b4b-7153-4886-a6e5-69e800581691
datasets/ds-2026-09-01/snapshot.json
2026-11-16 01:39:51 UTC anterior 778 B sha256 bb923cb10179… version 0307e2fc-bf1a-47c0-b1fd-cb93dec18205
datasets/ds-2026-09-01/snapshot.json
2026-11-16 01:40:36 UTC vigente MARCA DE BORRADO version d21d0af9-cd39-42eb-b24b-95b42263991f
datasets/ds-2026-09-01/validation.json
2026-11-16 01:39:51 UTC anterior 292 B sha256 493b19c2da1f… version a1e0544f-10f6-43d2-8539-46dd467f1c7f
datasets/ds-2026-09-01/validation.json
2026-11-16 01:40:36 UTC vigente MARCA DE BORRADO version 5b52d662-2c7b-4e93-a64d-dd5412a327d6
El arreglo. Con versionado, un DELETE sin version_id solo pone una marca de borrado encima. Bórrala: python mundo/s3.py borrar-version ml-datos datasets/ds-2026-09-01/snapshot.json <version_id de la marca>, y lo mismo con validation.json. No vuelvas a correr 5_publicar.py: el PUT condicional solo mira la versión vigente, y si es una marca de borrado, pasa; escribirías una tarjeta nueva (otra hora, quizá otro commit) en vez de recuperar la original. En AWS, una política que niegue s3:DeleteObject en datasets/ lo habría impedido.
Plataforma revisó la factura de almacenamiento y «optimizó» los buckets de ML. Mandó un correo, pero se fue a spam.
Síntoma. verificar.py: solo inmutable falla. ✗ inmutable el versionado de ml-datos está «Suspended»: sin versiones, un PUT o un borrado no deja rastro ni se puede deshacer
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Alguien apagó el versionado.
El S3 perdió datos.
Tu publicar ya no usa escritura condicional.
Terminalcómo confirmar
python mundo/s3.py versionado ml-datos
Salida
ml-datos: versionado Suspended
El arreglo. Préndelo otra vez: python mundo/s3.py versionado ml-datos on. Sin versiones, un PUT sin header reemplaza para siempre y un DELETE borra de verdad: no hay forma de deshacer. En S3, un bucket con versionado nunca vuelve a «sin versionado»: solo se suspende.
Un compañero se cansó de cambiar el id del snapshot cada mes y dejó el entrenamiento «para que siempre agarre el más nuevo».
Síntoma. verificar.py: corrida, lectura y linaje fallan. ✗ corrida entrenar.snapshot = «latest»: tiene que ser un id de snapshot. Una carpeta como «latest» cambia de contenido sin cambiar de nombre, y la corrida no podría decir con qué entrenó
15:entrenar:
16- snapshot: latest # con qué snapshot entrena pipeline/6_entrenar.py: siempre un id, nunca «latest»
17- semilla: 17
✗ entrenar.snapshot = «latest»: tiene que ser un id de snapshot. Una carpeta como «latest» cambia de contenido y la corrida no podría decir con qué datos entrenó
[código 1]
El arreglo. entrenar.snapshot vuelve a ser el id: ds-2026-09-01. Un nombre que cambia de contenido no dice con qué se entrenó, y la caché de un orquestador vería la misma llave dos meses seguidos. Cambiar el id cada mes es trabajo del orquestador.
Producto pidió medir con más ejemplos. Alguien subió la validación del 10 % al 20 % en params.yaml y dejó una nota: «solo es un número».
Síntoma. verificar.py: split y dag fallan. ✗ dag dvc status: el pipeline no está al día (split, publicar cambiaron). Corre dvc repro y mira qué pasa Si corres dvc repro, la validación falla en split_estable y no se publica nada.
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Alguien cambió un parámetro.
Cambió la entrada.
Cambió tu código.
cómo confirmar
dvc status
dvc repro
Salida
split:
changed deps:
params.yaml:
modified: split.umbral
publicar:
changed deps:
params.yaml:
modified: split.umbral
Running stage 'split':
Running stage 'validar':
✗ split_estable 51 de 298 vendedores cambiaron de lado contra ds-2026-08-01
failed: 2467 filas = 1.23 × las 2013 del padre · quien vende 75.6% · 298 vendedores en los dos, 51 movidos
ERROR: failed to reproduce 'validar': failed to run: python pipeline/4_validar.py, exited with 1
El arreglo. split.umbral vuelve a 90 y dvc repro: DVC recupera de su caché la salida que ya tenía para esos parámetros. Si de verdad se quiere más validación, se logra con vendedores nuevos, nunca moviendo a los que ya estaban.
La estación 1 avisó que el primer export de eventos de septiembre salió incompleto: faltaban 40 correcciones de moderación. Ya dejaron el archivo nuevo en entrada/.
Síntoma. verificar.py: labels y dag fallan. ✗ labels tus labels no son los vigentes al corte: sobran 40, faltan 40; revisa que gane el evento más reciente de cada foto Si corres dvc repro, todo pasa hasta publicar, y ahí S3 contesta 412.
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Cambió una entrada del pipeline.
Alguien tocó el snapshot publicado.
Cambió tu código.
cómo confirmar
dvc status
dvc repro
Salida
labels:
changed deps:
modified: entrada/labels-eventos.parquet
Running stage 'labels':
Running stage 'manifest':
Running stage 'split':
Running stage 'validar':
Running stage 'publicar':
✗ datasets/ds-2026-09-01/rows.parquet ya existe con otro contenido (412 Precondition Failed). Un snapshot publicado no se reescribe: si el contenido cambió, usa un id nuevo en params.yaml
ERROR: failed to reproduce 'publicar': failed to run: python pipeline/5_publicar.py, exited with 1
El arreglo. Que publicar falle es correcto: el snapshot publicado no se toca, porque la corrida que lo usó tiene que seguir siendo reproducible. El contenido nuevo lleva un id nuevo: en params.yaml, snapshot.id y entrenar.snapshot pasan a ds-2026-09-01-r2; git commit, dvc repro (publica r2 con parent ds-2026-08-01), git commit de dvc.lock y python pipeline/6_entrenar.py.
Soporte atendió una solicitud de borrado de una vendedora y borró sus fotos del bucket del producto, como dice el proceso. A ML nadie le avisó.
Síntoma. verificar.py: lectura falla. ✗ lectura 4 fotos de ds-2026-09-01 no se pueden leer (2026/05/02/p-000548.jpg: no existe; vendedores s-007) y no están en entrada/borrados.csv
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Se borraron fotos del bucket.
Cambiaron las fotos bajo la misma llave.
El snapshot apunta a llaves que nunca existieron.
Terminalcómo confirmar
python pipeline/6_entrenar.py
Salida
✗ 4 fotos no se pueden usar, por ejemplo 2026/05/02/p-000548.jpg: no existe. Si alguien pidió borrarlas, anótalas en entrada/borrados.csv
[código 1]
El arreglo. El snapshot no se reescribe: se anota el borrado. Busca las huellas que faltan (en data/rows.parquet, o mira dónde está cada una con pipeline/7_linaje.py), agrégalas a entrada/borrados.csv con la fecha de hoy en UTC y el motivo, corre dvc repro (split vuelve a correr y, como el registro se lee al corte, no cambia nada) y haz commit. El snapshot siguiente ya no las incluye; el modelo actual se decide aparte.
Snapshot = manifest, no copia.Un id inmutable que cita cada foto por llave y huella, una tarjeta que se escribe al final, y tres punteros desde cada modelo (snapshot y su huella, commit y entorno). Con eso, «¿con qué se entrenó?» se contesta en un minuto, y un contenido nuevo siempre lleva un id nuevo.Trampa: Inmutable «por convención». Sin escritura condicional y sin versiones, alguien reescribe el prefijo y el modelo de marzo deja de ser reproducible sin que nada truene. Y el versionado protege versiones, no llaves: un PUT nuevo a la misma llave pasa y es lo que se lee. Por eso la tarjeta guarda la huella y el modelo la comprueba.Listo cuando
Los labels del snapshot son los vigentes al corte, en UTC, con la regla de 30 días.
Cada foto cuenta una vez, ninguna del golden set entra, y ningún vendedor cambió de lado contra el padre.
El contrato de datos pasó antes de publicar, y si no hubiera pasado, nada se publicaba.
ds-2026-09-01 está en S3 con manifest, reporte y tarjeta, cada llave escrita una sola vez y con versionado.
dvc repro corre solo lo que cambió, y dvc.lock está en un commit.
Tu corrida guarda el id del snapshot, su huella, un commit limpio, la huella del entorno y la semilla.
Desde una huella llegas a sus snapshots, a sus modelos y a su borrado.
Así te lo pueden preguntar en una entrevista
¿Cómo sabes con qué datos se entrenó el modelo que está en producción?
La corrida guarda el id del snapshot y su rows_sha256. Leo la tarjeta del snapshot, recalculo la huella del manifest y la comparo: si coincide, el manifest me dice cada foto (llave + huella) y su label. Si el parámetro de la corrida fuera una ruta como latest, no lo sabría: por eso el id va como parámetro.
¿Por qué un manifest en vez de copiar las fotos en cada versión?
Porque cita y no copia: en C01 un snapshot pesa ≈ 0.1 % de las fotos (≈ 97 MB contra ≈ 387 GB), así que guardar uno por mes cuesta centavos. El costo escondido es que depende de que las fotos sigan ahí: por eso cada fila lleva la huella, el entrenamiento la comprueba al leer y los borrados se anotan.
¿Cómo evitas que alguien reescriba un snapshot publicado?
Tres capas: escritura condicional (If-None-Match: *, obligatoria por la política del bucket), versionado del bucket para recuperar lo que se pisó o se borró, y la huella en la tarjeta y en cada modelo, que delata cualquier cambio. Object Lock protege versiones, no llaves, así que no basta solo.
Llegaron correcciones de labels de un mes que ya publicaste. ¿Qué haces?
No toco el snapshot publicado: la corrida que lo usó tiene que seguir siendo reproducible. Armo uno nuevo con otro id (aquí, ds-2026-09-01-r2), que pasa por el mismo contrato, y el siguiente entrenamiento apunta a él. Las correcciones son eventos nuevos, así que el corte decide qué entra.
¿Por qué el split va por hash del vendedor y no al azar?
Por dos razones. Por vendedor, para que el modelo no reconozca la mesa o el fondo de alguien que vio en train. Por hash, para que sea estable: el mismo vendedor cae del mismo lado cada mes, y comparar el modelo nuevo contra el viejo es justo. Sortear cada mes movería ≈ 87,796 fotos de validación a train en C01.
Alguien pide borrar sus fotos. ¿Cómo sabes en qué modelos están?
Busco sus huellas en los manifests de todos los snapshots y sigo las corridas que usaron esos snapshots. Las fotos se borran del bucket (todas sus versiones), sus huellas entran a un registro de borrados de solo agregar, el snapshot siguiente ya no las incluye y el entrenamiento las salta al leer. Qué pasa con el modelo actual se decide aparte.
Versión del contenido: 15 de noviembre de 2026.
Contexto opcional
para consultar
Dónde estás en el pipeline
La estación 1 deja los labels del mes. Esta los convierte en un snapshot inmutable: una lista con id (ds-2026-09-01) que cita cada foto por su llave y su huella sha256, con una tarjeta que dice de dónde salió. No copia fotos: las referencia, así que un snapshot nuevo pesa ≈ 0.1 % de las imágenes en C01. Cada modelo guarda tres punteros (el snapshot, el commit y el entorno) y con eso respondes «¿con qué datos?», «¿lo puedo reproducir?» y «¿en qué modelos está esta foto que pidieron borrar?». La estación 3 entrena con ese id.
Entra
los labels del mes como eventos (quien vende, moderación y etiquetado humano), con su hora en UTC
las publicaciones: cada foto con su llave y su sha256, quién la vende y cuándo
el golden set congelado y el registro de borrados
el snapshot anterior, ds-2026-08-01 (el padre)
→2→
Sale
el snapshot ds-2026-09-01 en S3: rows.parquet (el manifest), validation.json y la tarjeta snapshot.json, escritos una sola vez
el reporte de validación del contrato de datos
el pipeline como DAG (dvc.yaml + dvc.lock), en un commit
una corrida con sus tres punteros y la búsqueda de una foto hacia sus snapshots y modelos
El escenario del proyecto
Con kit · 4 rondas
El kit trae el marketplace de C01 seis meses después de la estación 1, a principios de octubre de 2026: 3,120 publicaciones de abril a septiembre con sus fotos en un S3 local, los labels como eventos, el golden set, un registro de borrados y el snapshot de agosto que publicó el equipo. Tú escribes el pipeline que arma el de septiembre y el entrenamiento que deja el linaje. Todo corre con un entorno virtual de Python y un contenedor.
El mundo vive en dos lugares: las fotos y los snapshots en el S3 local, y la entrada en entrada/. mundo/crear.py lo crea igual cada vez (semilla fija), incluido el snapshot de agosto que publicó el equipo: es el padre del tuyo. La carpeta tiene que ser un repositorio de git desde el inicio: el commit es uno de los punteros del linaje, y DVC guarda sus huellas junto al código.
Glosario: los 18 conceptos
Una línea para entenderlo; abre la tarjeta para la analogía, por qué importa y la trampa.
Snapshot inmutableimmutable dataset snapshotUna versión del dataset con id propio (ds-2026-09-01) que, una vez escrita, nadie cambia: ni se borra, ni se reemplaza, ni se le agregan filas.Analogía, por qué importa y la trampa ↓
AnalogíaLa foto de grupo de fin de año: si alguien llega tarde, sale en la del año siguiente; no se retoca la de este año.
Por qué importaEs lo que hace que «el modelo de octubre se entrenó con ds-2026-09-01» sea verdad para siempre. Si el contenido cambia, es otro snapshot con otro id.
TrampaInmutable «por acuerdo» no sirve: un script que corre dos veces o alguien que «arregla» una fila lo rompe sin dar error. Tiene que ser por diseño.
ManifestmanifestUn archivo (aquí, Parquet) con una fila por foto: su llave, su huella, quién la vende, su label, de dónde salió el label y su split.Analogía, por qué importa y la trampa ↓
AnalogíaLa lista de invitados con foto de cada uno, en vez de meter a los invitados en la caja.
Por qué importaCita las fotos en vez de copiarlas: un snapshot pesa ≈ 0.1 % de las imágenes en C01 y se puede guardar uno por mes para siempre.
TrampaSi una foto se borra o cambia bajo la misma llave, la fila apunta a otra cosa. Por eso lleva la huella, y por eso se comprueba al leer.
Huella sha256content hash (SHA-256)64 caracteres hexadecimales que salen de los bytes de un archivo: el mismo contenido da siempre la misma huella; un byte distinto, otra.Analogía, por qué importa y la trampa ↓
AnalogíaUna huella digital: no dice cómo es la persona, pero dice si es la misma.
Por qué importaHay dos: image_sha256 (cada foto) y rows_sha256 (el manifest entero, en la tarjeta). La segunda la guarda cada modelo: si alguien cambia una sola etiqueta, se nota.
TrampaLa huella no impide nada: delata. Y depende de los bytes: el mismo contenido escrito en otro orden da otra huella, por eso las filas se ordenan antes de escribir.
Tarjeta del snapshotdataset cardUn JSON chico junto al manifest (snapshot.json): id, padre, corte, conteos, mezcla de fuentes, regla del split, commit del código, rows_sha256 y resultado de la validación.Analogía, por qué importa y la trampa ↓
AnalogíaLa etiqueta de un frasco de laboratorio: qué hay, de qué lote salió, quién lo preparó y cuándo.
Por qué importaEl manifest dice qué hay; la tarjeta, de dónde salió y cómo comprobarlo. Se escribe al final: un snapshot sin tarjeta no existe.
TrampaEl commit de la tarjeta es el del código que armó el snapshot, no el que entrena. Cada artefacto apunta a su propio código.
Labels como eventosappend-only label eventsCada label es una fila nueva que nunca se edita, con su fuente, su guía y su hora. Corregir es agregar otro evento más nuevo.Analogía, por qué importa y la trampa ↓
AnalogíaEl historial de un expediente médico: el diagnóstico nuevo no borra el viejo, se escribe abajo con fecha.
Por qué importaCon eso, un snapshot es una consulta: «para cada foto, el label más reciente que ya existía a tal hora». Nada se pierde y se puede explicar por qué el modelo de agosto aprendió lo que aprendió.
TrampaSi la tabla guarda una fila por foto y la corrección la reescribe, ya no sabes qué label había el día del corte.
Corte (point-in-time)point-in-time cutoffLa hora, en UTC, hasta la que cuenta lo que existe: un snapshot solo ve eventos de antes del corte.Analogía, por qué importa y la trampa ↓
AnalogíaEl cierre de una votación: los votos que llegan después cuentan para la siguiente.
Por qué importaHace que el snapshot sea reproducible: correrlo hoy o en un año da lo mismo, aunque sigan llegando eventos. También el registro de borrados se lee al corte.
TrampaUn corte sin zona horaria (2026-10-01 00:00) se interpreta en la hora de la máquina: en México son 6 horas de diferencia y se cuelan eventos.
Split establestable split (hash-based)Cada vendedor cae en train o en val por el hash de su seller_id (cubeta = sha256 mod 100) y se queda ahí en todas las versiones.Analogía, por qué importa y la trampa ↓
AnalogíaEl número de lista en la escuela: el mismo alumno tiene el mismo número todo el año, aunque entren alumnos nuevos.
Por qué importaComparar el modelo nuevo contra el viejo solo es justo si ninguno vio el examen del otro. Los vendedores nuevos caen donde les toque, sin mover a nadie.
TrampaSortear otra vez, o mover el umbral «para tener más validación», manda a val vendedores con los que el modelo anterior ya entrenó.
Duplicados por huellahash-based deduplicationLa misma foto subida en varias publicaciones cuenta una sola vez: de cada huella queda la fila de la publicación más vieja.Analogía, por qué importa y la trampa ↓
AnalogíaTres copias del mismo examen con distinto nombre en la portada: se califica una.
Por qué importaSi la misma foto cayera en train y en val, la validación premiaría memorizar. Pasa con vendedores que republican y con fotos de catálogo que usan dos tiendas.
TrampaDeduplicar por llave no sirve: cada publicación tiene su llave. Lo que se repite son los bytes, o sea la huella.
Contrato de datosdata contractLas reglas que los datos cumplen antes de entrenar: esquema exacto, categorías válidas, cero duplicados, cero golden, split por vendedor y estable, volumen en rango y tope de labels débiles.Analogía, por qué importa y la trampa ↓
AnalogíaLa revisión de un avión antes de despegar: una lista fija, la misma cada vez, y si un punto falla no se despega.
Por qué importaDetiene el pipeline antes de gastar GPU. Cada regla viene de un error real: un join que duplica, el golden en train, un split que se movió.
TrampaUn contrato que solo avisa y deja seguir no es contrato: el paso de validar tiene que fallar (código de salida 1) para que nada se publique.
Escribir, auditar, publicarwrite-audit-publishEl snapshot se arma aparte, se audita con el contrato y solo si pasa se publica, con la tarjeta al final.Analogía, por qué importa y la trampa ↓
AnalogíaImprimir el periódico de prueba, revisarlo y solo entonces mandarlo a todos los puestos.
Por qué importaUn job que se cae a medias no deja un snapshot «a medias» que alguien pueda usar: sin tarjeta no existe. En el dojo, «aparte» es data/ en tu Mac; en C01, un prefijo staging/.
TrampaPublicar la tarjeta primero (o en medio) abre la puerta a entrenar con algo que nadie revisó.
Escritura condicionalconditional write (If-None-Match: *)Un PUT que solo se cumple si la llave no existe. Si ya existe, S3 responde 412 Precondition Failed y no toca nada.Analogía, por qué importa y la trampa ↓
AnalogíaUn buzón con candado: puedes dejar una carta nueva, pero no cambiar la que ya está adentro.
Por qué importaSin ella, un PUT a una llave que existe reemplaza el objeto en silencio: gana el último. Con ella, reescribir un snapshot es un error ruidoso.
TrampaEl header lo pone quien escribe: un script que no lo pone escribe igual. En AWS se vuelve obligatorio con la política del bucket; RustFS no tiene esa condición, así que aquí depende de tu código. Y con versiones solo mira la versión vigente: si es una marca de borrado, el PUT pasa.
Versionado del bucketS3 Versioning y delete markersCon el versionado prendido, un PUT a una llave existente guarda una versión nueva sin destruir la vieja, y un DELETE solo pone una marca de borrado encima.Analogía, por qué importa y la trampa ↓
AnalogíaUn documento con historial de cambios: puedes volver a cualquier versión, y borrar es tachar, no quemar.
Por qué importaEs la red de seguridad: lo que se pisó o se borró por error se recupera borrando la versión mala o la marca. Y deja rastro de cada reescritura.
TrampaProtege versiones, no llaves: el PUT nuevo pasa y es lo que se lee. Y para un borrado por ley hay que borrar cada versión, no solo poner la marca.
DAG y caché de pasospipeline DAG y step cacheEl pipeline como pasos con flechas (qué lee y qué deja cada uno). La herramienta guarda la salida de cada paso con una llave hecha de su código, sus parámetros y sus entradas, y la reusa si la llave no cambió.Analogía, por qué importa y la trampa ↓
AnalogíaUna receta con pasos: si ya picaste la cebolla y nadie cambió la cebolla, no la vuelves a picar.
Por qué importaAhorra horas y hace que repetir el pipeline sea seguro. dvc.lock guarda las huellas de cada entrada y salida: también es linaje.
TrampaLo que no está en la llave no existe para la caché: un parámetro que el script lee pero el stage no declara no hace correr el paso, y sale la salida vieja.
Id como parámetro, nunca «latest»pass the snapshot id, not a moving pathToda entrada que cambia el resultado llega como un id fijo (ds-2026-09-01), nunca como una carpeta que cambia de contenido sin cambiar de nombre.Analogía, por qué importa y la trampa ↓
AnalogíaPedir «el libro con ISBN tal» en vez de «el libro de la repisa de arriba»: alguien puede cambiar el de la repisa.
Por qué importaLa corrida guarda un puntero que siempre dice lo mismo. Con latest, el registro no dice con qué entrenó y la caché ve la misma llave dos meses seguidos.
Trampa«Para no editar params.yaml cada mes» es la excusa típica. Cambiar el id cada mes es trabajo del orquestador, no de una carpeta mágica.
LinajelineageLa cadena de qué salió de qué: modelo ← corrida ← snapshot (id + rows_sha256) ← cada foto (llave + huella), más el commit y el entorno. Se guarda como punteros, no como copias.Analogía, por qué importa y la trampa ↓
AnalogíaEl árbol genealógico con acta de nacimiento en cada rama.
Por qué importaResponde en un minuto las tres preguntas: con qué datos se entrenó, si cambió el código o los datos, y en qué modelos está la foto que pidieron borrar.
TrampaUn puntero que se escribe a mano o «después» se desfasa. Lo escribe el mismo programa que entrena, en el momento.
Commit con el árbol limpioclean working treeEntrenar (y publicar) solo desde un commit sin cambios pendientes en el código, para que el commit diga exactamente qué corrió.Analogía, por qué importa y la trampa ↓
AnalogíaFirmar un contrato solo cuando ya no tiene tachones a mano.
Por qué importaEl commit es uno de los cinco ingredientes de la reproducibilidad (código, datos, configuración, entorno y semilla). Si el script tenía cambios sin commit, el puntero apunta a otro código.
Trampadvc repro cambia dvc.lock: hay que hacer commit después de cada repro, antes de entrenar.
Registro de borradosdeletion log (tombstones)Una lista de solo agregar con la huella de cada foto que se borró, la fecha y el motivo.Analogía, por qué importa y la trampa ↓
AnalogíaLa lista de bajas de un club: no se arranca la hoja del acta vieja, se anota la baja con fecha.
Por qué importaRespeta el derecho al borrado sin romper la historia: los snapshots viejos no se reescriben, el siguiente ya no la incluye y el entrenamiento la salta al leer.
TrampaBorrar la foto del bucket sin anotarlo deja filas que apuntan a nada y un entrenamiento que truena; anotarlo sin borrar no cumple la solicitud.
Paso idempotenteidempotent stepCorrerlo dos veces deja lo mismo que correrlo una.Analogía, por qué importa y la trampa ↓
AnalogíaEl botón del elevador: picarle cinco veces no llama cinco elevadores.
Por qué importaEl orquestador reintenta pasos que fallan a la mitad. Publicar otra vez el mismo contenido sigue sin error; otro contenido con el mismo id se detiene.
TrampaIdempotente no es «sobrescribe sin preguntar»: eso borra la historia. Es «si ya está igual, no hago nada».
Nube real vs. local
En C01
En el dojo
Filas del snapshot
1,932,628 fotos (1,840,211 train · 92,417 val)
2,467 fotos (2,309 train · 158 val)
Lo que cita
≈ 387 GB de fotos de ≈ 200 KB; el manifest ≈ 97 MB en Parquet
6.1 MB de fotos de juguete de ≈ 2.3 kB; el manifest 242 kB en Parquet
Split
sha256(seller_id) mod 100 < 95 → train
sha256(seller_id) mod 100 < 90 → train (con 300 vendedores, el 5 % dejaría muy pocos en val)
Dónde vive
Amazon S3, con versionado y una política del bucket que exige If-None-Match: *
RustFS en tu Mac, con versionado; la escritura condicional la pone tu código
Quién lo arma cada mes
el pipeline mensual en el orquestador (por ejemplo Kubeflow Pipelines), con caché por paso
dvc repro sobre dvc.yaml, con la caché de DVC
Dónde quedan los punteros
MLflow: parámetros y tags de la corrida, y el digest de la imagen de entrenamiento
corridas/*.json y la huella de los paquetes instalados
En la nube
En el dojo
Qué cambia
Amazon S3 con política del bucket
RustFS en localhost:9300
La misma API: versionado, marcas de borrado y PUT con If-None-Match (412) funcionan igual. RustFS no acepta la condición s3:if-none-match en una política, así que la escritura condicional depende de tu código; en AWS la política la vuelve obligatoria para todos.
El orquestador del pipeline mensual (por ejemplo Kubeflow Pipelines)
DVC: dvc.yaml + dvc repro
Los dos arman un DAG y reusan la salida de un paso si su llave no cambió. El orquestador corre en un clúster, con horario y reintentos; DVC corre en tu Mac cuando tú lo llamas.
MLflow (parámetros y tags de la corrida)
corridas/*.json
Los mismos punteros en un JSON por corrida. MLflow los guarda en un servidor, con interfaz y búsqueda; lo verás en la estación 3.
El digest de la imagen de entrenamiento
huella_entorno(): sha256 de los paquetes instalados
El digest fija todo el contenedor (sistema, CUDA, drivers); la huella de paquetes solo fija las versiones de Python.
Qué trae el kit y qué escribes tú
Lo que trae no lo escribes
El S3 local (compose.yaml). RustFS en el puerto 9300, con dos buckets: fotos (el del producto) y ml-datos (el de ML, con versionado).
mundo/crear.py. Crea todo con semilla fija en ≈ 10 s: las 3,120 fotos de juguete (64×64, el color y la forma dependen de la categoría), la entrada y el snapshot ds-2026-08-01.
entrada/. Lo que dejó la estación 1 y el producto: publicaciones.parquet, labels-eventos.parquet (3,908 eventos, 112 después del corte), golden.parquet (280 huellas), borrados.csv (las 14 fotos de una vendedora que pidió borrar) y categorias.json.
corridas/run-20260901-061500.json. La corrida del modelo de septiembre, que entrenó con ds-2026-08-01: el registro de corridas (en C01, MLflow).
mundo/s3.py. Mirar y reparar el S3 con permisos de administrador: ls, versiones (con la huella de cada versión), borrar-version y versionado. En C01, el AWS CLI.
verificar.py y romper.py. 12 checks con los criterios de «listo» y 7 fallas en el mundo, la configuración o la infraestructura, nunca en lo que escribes.
Lo que escribes lo escribes tú
pipeline/1_labels.pyLos labels vigentes al corte, con la regla de 30 días para quien vende.
pipeline/2_manifest.pyUna fila por foto con su llave y su huella.
pipeline/3_split.pySin borrados, sin duplicados, sin golden, y el split estable por vendedor.
pipeline/4_validar.pyEl contrato de datos: 8 reglas, y si una falla no se publica nada.
pipeline/5_publicar.pyEl snapshot en S3 con escritura condicional y la tarjeta al final.
dvc.yamlLos pasos 1 a 5 como DAG, con sus entradas, parámetros y salidas.
pipeline/6_entrenar.pyEntrenar con un id, comprobando cada huella, y dejar los tres punteros.
pipeline/7_linaje.pyDe una foto a sus snapshots, sus modelos y su borrado.
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 2: Versionado y linaje
Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin GPU ni nube, la estación «Versionado y linaje» del caso C01: convertir los labels del mes en un snapshot inmutable (manifest + tarjeta) y dejar en cada modelo los punteros que dicen con qué datos, con qué código y en qué entorno se entrenó. 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, eventos de labels, el snapshot de agosto y la corrida de septiembre), `modelo.py` (el entrenamiento de juguete), `s3.py` (mirar y reparar el S3 con permisos de administrador), `reiniciar.py` y el esqueleto. | **No.** Es el mundo. `s3.py` sí se usa para diagnosticar y reparar. |
| `entrada/` | Lo que dejó la estación 1 y el producto: publicaciones, eventos de labels, golden set, categorías y el registro de borrados. | Solo `entrada/borrados.csv`, y solo cuando un arreglo lo pide (se **agregan** filas, nunca se editan). |
| `pipeline/1_labels.py` … `7_linaje.py` | Los 7 pasos de la persona. Cada uno trae su contrato arriba. | **Sí.** Es lo que la persona escribe. |
| `pipeline/_comun.py` | Lo que comparten los pasos: `params()`, `s3()`, `sha256()`, `utc()`, `huella_entorno()`, `entrenar()`. | No. |
| `dvc.yaml` | El pipeline como DAG (paso 6). | **Sí.** |
| `params.yaml` | Los parámetros: el id del snapshot, el corte, el padre, el umbral del split, el snapshot de entrenamiento. | Solo cuando un paso o un arreglo lo pide. |
| `dvc.lock`, `.dvc/` | Las huellas que deja DVC al correr. | No a mano: los escribe `dvc repro`. Sí van en los commits. |
| `data/` | Las salidas del pipeline (DVC las controla; git las ignora). | No a mano. |
| `corridas/` | El registro de corridas (en C01, MLflow). `run-20260901-061500.json` es del equipo. | No a mano: lo escribe `pipeline/6_entrenar.py`. |
| `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/comun.py` para resolver un paso: trae la versión del equipo. |
| `GUION.md` / `OBJETIVOS.md` | El paso a paso (ronda Guiado) y solo los objetivos (ronda 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 (escala, RustFS en vez de Amazon S3, DVC en vez del orquestador, `corridas/` en vez de MLflow), 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 (`dvc repro`, `pipeline/5_publicar.py`, `pipeline/6_entrenar.py`, `mundo/s3.py borrar-version`, `mundo/s3.py versionado … on|off`, `romper.py`, `mundo/*.py`, `git commit`), dilo. Lo que solo lee (`verificar.py`, `dvc status`, `dvc dag`, `mundo/s3.py ls` y `versiones`, `git status`, `git log`) se puede correr directo.
- Un snapshot publicado nunca se reescribe ni se borra para «arreglarlo». Si el contenido cambió, lleva un id nuevo.
- Sigue el prompt de la ronda que te pegaron: en 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-16 10:42 · Guiado · paso 1 (labels al corte)
- **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-versionado",
"rondas": {
"guiado": { "estado": "en_curso", "inicio": "2026-11-16T10: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-16T10:42:30-06:00", "ronda": "guiado", "paso": "labels", "hice": "…", "medi": "…", "sigue": "…" }
],
"verificaciones": [
{ "fecha": "2026-11-16T10:41:02-06:00", "pasan": ["mundo", "labels"], "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-16T10: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.