Antes de producción: tu primer dataset

# Dos servicios para la práctica: un S3 local (RustFS) para guardar las versiones del dataset
# y Label Studio para etiquetar. En C01 real: Amazon S3 y Label Studio o un proveedor.
name: c01-desde-cero
services:
  s3:
    image: rustfs/rustfs:1.0.4
    ports: ["9200:9000", "9201:9001"]   # 9200 = API S3 · 9201 = consola web
    environment:
      RUSTFS_ACCESS_KEY: practica
      RUSTFS_SECRET_KEY: practica-secreto
      RUSTFS_ADDRESS: ":9000"
      RUSTFS_CONSOLE_ADDRESS: ":9001"
      RUSTFS_CONSOLE_ENABLE: "true"
    volumes: ["s3:/data"]
    command: ["/data"]
  labelstudio:
    image: heartexlabs/label-studio:1.23.2
    ports: ["8091:8080"]                 # http://localhost:8091
    environment:
      LABEL_STUDIO_USERNAME: practica@ejemplo.com
      LABEL_STUDIO_PASSWORD: practica-etiquetas
      LABEL_STUDIO_USER_TOKEN: practica-token-local-0001
      LABEL_STUDIO_ENABLE_LEGACY_API_TOKEN: "true"
    volumes: ["ls:/label-studio/data"]
volumes:
  s3: {}
  ls: {}

dvc[s3]==3.67.1
boto3==1.43.117
pillow==13.0.0
numpy==2.5.4
scikit-learn==1.9.1
pyyaml==6.0.3

.venv
__pycache__/
prod/
modelos/*.joblib

mkdir -p ~/dojo/c01-desde-cero && cd ~/dojo/c01-desde-cero
git init -b main
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

docker compose up -d
docker compose ps --format '{{.Service}}  {{.Status}}  {{.Ports}}'

"""Paso 2 · Recolectar: 10 fotos sin etiqueta en data/crudo/.

Toma 5 playeras y 5 tenis del set de prueba de Fashion-MNIST, las agranda a 112 px
para verlas bien en Label Studio y les pone nombres que no delatan la clase.
"""
import gzip
import urllib.request
from pathlib import Path

import numpy as np
from PIL import Image

URL = "https://github.com/zalandoresearch/fashion-mnist/raw/master/data/fashion/{}.gz"
CACHE = Path.home() / ".cache" / "fashion-mnist"
SALIDA = Path("data/crudo")


def bajar(nombre: str) -> bytes:
    CACHE.mkdir(parents=True, exist_ok=True)
    p = CACHE / f"{nombre}.gz"
    if not p.exists():
        urllib.request.urlretrieve(URL.format(nombre), p)
    return gzip.decompress(p.read_bytes())


imgs = np.frombuffer(bajar("t10k-images-idx3-ubyte"), np.uint8, offset=16).reshape(-1, 28, 28)
etq = np.frombuffer(bajar("t10k-labels-idx1-ubyte"), np.uint8, offset=8)

rng = np.random.default_rng(1)
elegidas = np.concatenate([rng.choice(np.where(etq == c)[0], 5, replace=False) for c in (0, 7)])  # 0 = playera, 7 = tenis
rng.shuffle(elegidas)

SALIDA.mkdir(parents=True, exist_ok=True)
for i, idx in enumerate(elegidas, 1):
    Image.fromarray(255 - imgs[idx]).resize((112, 112), Image.NEAREST).save(SALIDA / f"foto_{i:02d}.png")
print(f"{len(elegidas)} fotos en {SALIDA}/")

python scripts/recolectar.py

shasum -a 256 data/crudo/foto_01.png data/crudo/foto_02.png

# Guía de etiquetado · v1

**Para qué:** decidir la categoría de una foto de producto del marketplace. Una foto, una categoría.

## Categorías

| Categoría | Es | No es |
|---|---|---|
| `playera` | Prenda para el torso, de manga corta, larga o sin manga, con o sin estampado. | Vestidos, abrigos. |
| `tenis` | Calzado deportivo con agujetas o cierre, bajo o de bota. | Sandalias, zapatos de vestir. |

## Casos límite

- **Manga larga:** sigue siendo `playera` si es de tela delgada y sin botones al frente.
- **Tenis de bota (cubre el tobillo):** es `tenis`.
- **No se ve bien o no es ninguna:** no adivines; usa *Skip* y anótalo en la bitácora.

## Cambios

- v1 (inicial): dos categorías.

<View>
  <Image name="foto" value="$image" zoom="true"/>
  <Choices name="clase" toName="foto" choice="single" showInline="true" required="true">
    <Choice value="playera"/>
    <Choice value="tenis"/>
  </Choices>
</View>

open data/crudo

mkdir -p data/etiquetado
curl -s "http://localhost:8091/api/projects/1/export?exportType=JSON_MIN" \
  -H "Authorization: Token practica-token-local-0001" -o data/etiquetado/export-v1.json
python -m json.tool data/etiquetado/export-v1.json | head -11

"""Paso 5 · De la exportación de Label Studio a data/labels.csv.

Una fila por foto: el archivo, su sha256 (la llave que no cambia aunque renombres el archivo),
la clase, quién la etiquetó, con qué guía y en qué lote llegó.
Uso: python scripts/etiquetas.py <export.json> <guia> <lote>
"""
import csv
import hashlib
import json
import sys
from pathlib import Path

export, guia, lote = Path(sys.argv[1]), sys.argv[2], sys.argv[3]
CRUDO = Path("data/crudo")
LABELS = Path("data/labels.csv")
CAMPOS = ["sha256", "archivo", "clase", "anotador", "guia", "lote"]

previas = list(csv.DictReader(LABELS.open())) if LABELS.exists() else []
vistas = {f["sha256"] for f in previas}

nuevas = []
for t in json.loads(export.read_text()):
    archivo = t["image"].rsplit("/", 1)[1].split("-", 1)[1]   # /data/upload/1/d942189a-foto_01.png -> foto_01.png
    sha = hashlib.sha256((CRUDO / archivo).read_bytes()).hexdigest()
    if sha in vistas:
        continue                                               # ya tenía label: no se pisa en silencio
    nuevas.append({"sha256": sha, "archivo": archivo, "clase": t["clase"],
                   "anotador": t["annotator"], "guia": guia, "lote": lote})

with LABELS.open("w", newline="") as f:
    w = csv.DictWriter(f, CAMPOS)
    w.writeheader()
    w.writerows(sorted(previas + nuevas, key=lambda f: f["archivo"]))
print(f"{len(nuevas)} labels nuevos · {len(previas) + len(nuevas)} en total")

python scripts/etiquetas.py data/etiquetado/export-v1.json v1 inicial

cut -d, -f2- data/labels.csv | head -4

{"clases": ["playera", "tenis"], "cupo": {"train": 3, "val": 1, "test": 1}}

"""Paso 6 · Dividir en train / val / test, por clase y sin depender del orden de los archivos.

Una foto que ya tiene split lo conserva: el test de una versión no se mueve en la siguiente.
Las nuevas se reparten por clase con el cupo de config (por hash, así sale igual cada vez).
"""
import csv
import json
from collections import defaultdict
from pathlib import Path

CUPO = json.loads(Path("config.json").read_text())["cupo"]   # p. ej. {"train": 3, "val": 1, "test": 1}
LABELS, SPLITS = Path("data/labels.csv"), Path("data/splits.csv")

labels = list(csv.DictReader(LABELS.open()))
splits = {f["sha256"]: f["split"] for f in csv.DictReader(SPLITS.open())} if SPLITS.exists() else {}

por_clase = defaultdict(list)
for f in labels:
    por_clase[f["clase"]].append(f["sha256"])

for clase, shas in sorted(por_clase.items()):
    ya = defaultdict(int)
    for s in shas:
        if s in splits:
            ya[splits[s]] += 1
    for s in sorted(x for x in shas if x not in splits):          # orden por hash: estable y sin sesgo de nombre
        falta = [n for n in ("test", "val") if ya[n] < CUPO[n]]
        splits[s] = falta[0] if falta else "train"
        ya[splits[s]] += 1

with SPLITS.open("w", newline="") as f:
    w = csv.writer(f)
    w.writerow(["sha256", "split"])
    w.writerows(sorted(splits.items()))

cuenta = defaultdict(lambda: defaultdict(int))
clase_de = {f["sha256"]: f["clase"] for f in labels}
for s, sp in splits.items():
    cuenta[clase_de[s]][sp] += 1
for c in sorted(cuenta):
    print(f"{c:8} train {cuenta[c]['train']} · val {cuenta[c]['val']} · test {cuenta[c]['test']}")

python scripts/dividir.py

"""Paso 7 · El contrato del dataset. Si algo falla, no se versiona ni se entrena.

Sale con código 1 si falla una regla: así lo puede usar un CI o el orquestador.
"""
import csv
import hashlib
import json
import sys
from collections import Counter
from pathlib import Path

cfg = json.loads(Path("config.json").read_text())
labels = list(csv.DictReader(Path("data/labels.csv").open()))
splits = {f["sha256"]: f["split"] for f in csv.DictReader(Path("data/splits.csv").open())}
en_disco = {hashlib.sha256(p.read_bytes()).hexdigest(): p.name for p in Path("data/crudo").glob("*.png")}

reglas = []
def regla(nombre, ok, detalle):
    reglas.append(ok)
    print(f"{'✓' if ok else '✗'} {nombre:25} {detalle}")

shas = [f["sha256"] for f in labels]
regla("una fila por foto", len(shas) == len(set(shas)), f"{len(shas)} filas, {len(set(shas))} fotos distintas")
faltan = [f["archivo"] for f in labels if f["sha256"] not in en_disco]
regla("cada label tiene foto", not faltan, "todas en data/crudo/" if not faltan else f"faltan: {faltan}")
sin_label = sorted(n for s, n in en_disco.items() if s not in set(shas))
regla("cada foto tiene label", not sin_label, "ninguna sin etiquetar" if not sin_label else f"sin label: {sin_label}")
raras = sorted({f["clase"] for f in labels} - set(cfg["clases"]))
regla("clases conocidas", not raras, ", ".join(cfg["clases"]) if not raras else f"desconocidas: {raras}")
sin_split = [s for s in shas if s not in splits]
regla("cada foto en un split", not sin_split, "train, val o test" if not sin_split else f"{len(sin_split)} sin split")
clase_de = {f["sha256"]: f["clase"] for f in labels}
huecos = [(sp, c) for sp in ("train", "val", "test") for c in cfg["clases"]
          if not any(splits.get(s) == sp and clase_de[s] == c for s in shas)]
regla("cada clase en cada split", not huecos, "sí" if not huecos else f"faltan: {huecos}")
n = Counter(splits[s] for s in shas if s in splits)
print(f"\ntrain {n['train']} · val {n['val']} · test {n['test']}")
sys.exit(0 if all(reglas) else 1)

python scripts/validar.py

# Ficha del dataset · c01-categorias

| | |
|---|---|
| **Versión** | `dataset-v1` |
| **Para qué** | Entrenar y evaluar el clasificador de categorías de las fotos del marketplace. |
| **Fotos** | 10 PNG de 112 × 112 px, en `data/crudo/` (DVC, remoto `s3://datasets/c01`). |
| **Clases** | `playera` 5 · `tenis` 5 |
| **Splits** | train 6 · val 2 · test 2, por clase y por hash (`data/splits.csv`). El test no se mueve en versiones futuras. |
| **Labels** | `data/labels.csv`: una persona, con la guía v1 (`guia/guia-v1.md`), en Label Studio. |
| **Fuente** | Fashion-MNIST (set de prueba), © 2017 Zalando SE, licencia MIT. |
| **Datos personales** | Ninguno: fotos de producto sin personas ni metadatos. |

## Límites conocidos

- Con 1 foto de test por clase, cada foto vale 50 puntos de exactitud: el test solo dice si el pipeline funciona, no qué tan bueno es el modelo.
- Un solo anotador: no hay medida de acuerdo.

## Cambios

- `dataset-v1`: versión inicial.

python -c "
import boto3
s3 = boto3.client('s3', endpoint_url='http://localhost:9200', aws_access_key_id='practica', aws_secret_access_key='practica-secreto', region_name='us-east-1')
s3.create_bucket(Bucket='datasets')
print([b['Name'] for b in s3.list_buckets()['Buckets']])"

dvc init -q
dvc remote add -d s3 s3://datasets/c01
dvc remote modify s3 endpointurl http://localhost:9200
dvc remote modify --local s3 access_key_id practica
dvc remote modify --local s3 secret_access_key practica-secreto
cat .dvc/config

dvc add data/crudo
cat data/crudo.dvc

git add -A && git status --short

git commit -m "dataset v1: 10 fotos, playera/tenis, guía v1"
git tag -a dataset-v1 -m "10 fotos · 2 clases · 6/2/2"

dvc push

git log --oneline --decorate

rm -rf data/crudo .dvc/cache && ls data

dvc pull

dvc status && python scripts/validar.py | tail -1

"""Lo que comparten entrenar.py y evaluar.py: leer una versión del dataset por su tag.

dvc.api lee de git (labels.csv, splits.csv) y del caché o del remoto de DVC (las fotos)
tal como estaban en ese tag, sin tocar tu carpeta de trabajo.
"""
import csv
import io

import dvc.api
import numpy as np
from PIL import Image


def cargar(tag: str, split: str):
    labels = list(csv.DictReader(io.StringIO(dvc.api.read("data/labels.csv", rev=tag))))
    splits = {f["sha256"]: f["split"] for f in csv.DictReader(io.StringIO(dvc.api.read("data/splits.csv", rev=tag)))}
    filas = [f for f in labels if splits[f["sha256"]] == split]
    X = np.array([vector(dvc.api.read(f"data/crudo/{f['archivo']}", rev=tag, mode="rb")) for f in filas])
    return X, np.array([f["clase"] for f in filas])


def vector(png: bytes) -> np.ndarray:
    """La foto como 784 números entre 0 y 1 (28 × 28 px), igual en entrenamiento y en producción."""
    return np.asarray(Image.open(io.BytesIO(png)).resize((28, 28)), float).ravel() / 255

"""Entrenar con una versión del dataset (por su tag) y dejar anotado cuál fue.

Uso: python scripts/entrenar.py <modelo> <tag>     p. ej. modelo-v1 dataset-v1
Lee la versión con dvc.api: si el tag no existe o sus fotos no están en el remoto, falla.
"""
import json
import subprocess
import sys
from pathlib import Path

import joblib
from sklearn.linear_model import LogisticRegression

from comun import cargar

nombre, tag = sys.argv[1], sys.argv[2]
Xtr, ytr = cargar(tag, "train")
modelo = LogisticRegression(max_iter=1000).fit(Xtr, ytr)

metricas, n = {}, {"train": len(ytr)}
for split in ("val", "test"):
    X, y = cargar(tag, split)
    n[split] = len(y)
    metricas[split] = f"{int((modelo.predict(X) == y).sum())}/{len(y)}"

ficha = {
    "modelo": nombre,
    "dataset": tag,
    "commit": subprocess.run(["git", "rev-list", "-n1", "--abbrev-commit", tag], capture_output=True, text=True, check=True).stdout.strip(),
    "clases": [str(c) for c in modelo.classes_],
    "n": n,
    "aciertos": metricas,
}
Path("modelos").mkdir(exist_ok=True)
joblib.dump(modelo, f"modelos/{nombre}.joblib")
Path(f"modelos/{nombre}.json").write_text(json.dumps(ficha, ensure_ascii=False, indent=2) + "\n")
print(json.dumps(ficha, ensure_ascii=False, indent=2))

python scripts/entrenar.py modelo-v1 dataset-v1

git add -A && git commit -m "modelo-v1 entrenado con dataset-v1"