OsteoLab: 2. Entrenamiento¶
Segundo cuaderno de la serie. En el anterior llegamos a una tabla de números (una fila por imagen, columnas con medidas geométricas) y etiquetas de grupo morfológico. Aquí respondemos: ¿cómo convertimos esa tabla en un modelo que generaliza?
Como en el cuaderno 1, versión simplificada y didáctica: no reproduce toda la infraestructura de producción (MLflow, múltiples semillas, DVC...), solo las ideas y el código mínimo para entenderlas.
import os, sys
from pathlib import Path
def find_repo_root():
start = Path.cwd()
for candidate in (start, *start.parents):
if (candidate / "params.yaml").exists() and (candidate / "training").is_dir():
return candidate
raise RuntimeError("Abre el notebook desde dentro del repo.")
REPO_ROOT = find_repo_root()
os.chdir(REPO_ROOT)
sys.path.insert(0, str(REPO_ROOT))
BONE_DB = REPO_ROOT / "base_datos_osea"
PROCESSED = REPO_ROOT / "data/processed"
MODELS = REPO_ROOT / "models"
print("Raíz del proyecto:", REPO_ROOT)
1. El modelo geométrico: Random Forest¶
Un Random Forest es un conjunto ("forest") de muchos árboles de decisión simples, cada uno entrenado con una muestra algo distinta de los datos. Un árbol solo hace preguntas tipo "¿elongation > 0.7?" y, según la respuesta, sigue por una rama hasta llegar a una predicción. Un solo árbol se sobreajusta fácilmente, promediar cientos de árboles corrige eso. Es un modelo clásico (nada de redes neuronales), rápido de entrenar y fácil de interpretar: podemos preguntarle qué features usó más.
Entrena directamente sobre las columnas numéricas del cuaderno 1.
import pandas as pd
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import GroupKFold, cross_val_score
df = pd.read_csv(PROCESSED / "bone_geometric_features_combined_lab.csv")
cols = ["area_ratio", "aspect_ratio", "solidity", "elongation", "circularity", "mean_width", "std_width"]
datos = df.dropna(subset=cols + ["bone_group"])
X, y, grupos = datos[cols], datos["bone_group"], datos.get("specimen", datos["bone_group"])
rf = RandomForestClassifier(n_estimators=200, random_state=0, n_jobs=-1)
rf.fit(X, y)
importancia = pd.Series(rf.feature_importances_, index=cols, name="importancia") \
.sort_values(ascending=False).to_frame()
importancia.style.bar(color="#c89b2b", vmin=0).format("{:.3f}")
Dos evaluaciones, no una¶
El entrenamiento real evalúa dos veces, y la diferencia importa:
- Split aleatorio por fila, optimista: como cada espécimen tiene varias vistas, es casi seguro que vistas del mismo objeto caen una en train y otra en test, así que el modelo "reconoce" el objeto, no la forma general.
GroupKFold, con especímenes completos fuera, la honesta: ningún espécimen aparece a la vez en train y test, mide si el modelo generaliza a huesos que nunca vio.
cv = GroupKFold(n_splits=5)
acc_honesto = cross_val_score(rf, X, y, cv=cv, groups=grupos).mean()
print(f"accuracy honesto (especímenes fuera): {acc_honesto:.3f}")
2. El modelo CNN / híbrido¶
¿Qué añade una CNN que el Random Forest no tiene?¶
El Random Forest solo ve los números que ya calculamos con OpenCV, nunca la imagen en sí. Una CNN (red neuronal convolucional) mira directamente el recorte de píxeles y aprende sus propias features visuales (texturas, patrones locales) que no se nos ocurrió medir a mano. El coste: necesita muchos más datos y cómputo.
El proyecto no entrena la CNN desde cero: usa transferencia de aprendizaje, partiendo de un backbone ya entrenado sobre millones de fotos genéricas, y le enseña a adaptar eso a distinguir grupos de huesos.
La variante que gana en producción es la híbrida: la red recibe el recorte de imagen y el
vector de features geométricas del cuaderno 1 a la vez. Combina lo visual (la CNN) con una señal
ya probada y estable (elongation y compañía) que no depende de que la red la descubra por sí
sola con pocos datos.
La CNN ve recortes, no fotos enteras¶
Esto es literalmente lo que entra en la red: el hueso recortado del fondo, redimensionado a
tamaño fijo. Tres ejemplos de especies distintas, mismo grupo (cranio), para ver qué tiene que
distinguir la red más allá de la forma general.
import numpy as np
import matplotlib.pyplot as plt
from shared.cv_extractor.extract import extract_features
especies = ["homo_sapiens", "equus_caballus", "canis_familiaris"]
fig, axes = plt.subplots(1, 3, figsize=(12, 4))
for ax, especie in zip(axes, especies):
carpeta = BONE_DB / "renders_lab" / especie / "cranium"
img_path = sorted(p for p in carpeta.rglob("*.png") if "_mask" not in p.name)[0]
with open(img_path, "rb") as fh:
f = extract_features(fh, backend="classic", include_crop=True)
crop = f.get("crop_image")
if crop is not None:
arr = np.asarray(crop)
ax.imshow(arr[:, :, ::-1] if arr.ndim == 3 else arr)
ax.set_title(especie)
ax.axis("off")
plt.suptitle("Lo que ve la CNN: el recorte, no la foto completa", y=1.02)
plt.tight_layout()
plt.show()
Cómo se entrena, en corto¶
Dos fases: primero se entrena solo una cabeza nueva sobre el backbone congelado (aprende rápido, parte de cero), luego se descongela también el backbone pero con una tasa de aprendizaje mucho más baja (solo afinar, sin destrozar lo que ya sabía).
Dos ajustes pensados para este problema concreto:
- Las fotos reales, al ser tan pocas frente a las sintéticas, cuentan varias veces en la pérdida de entrenamiento. Si no, el modelo casi las ignoraría.
- De todas las épocas entrenadas, se elige como modelo final la que mejor puntúa en el banco de fotos reales, no en validación sintética. Son métricas que pueden discrepar y la que cuenta es la segunda.
Entrenar de verdad tarda minutos (Random Forest) o decenas de minutos con GPU (CNN), por eso esta celda está desactivada por defecto.
RUN_TRAIN_CNN = False # True para reproducir de verdad (tarda, necesita GPU idealmente)
if RUN_TRAIN_CNN:
import subprocess
subprocess.run([sys.executable, "-m", "training.train_cnn",
"--model-type", "hybrid",
"--dataset-path", "data/processed/bone_geometric_features_combined_lab.csv",
"--run-name", "hybrid_lab",
"--epochs-frozen", "5", "--epochs-finetune", "10",
"--real-photo-boost", "4.0", "--select-by-real-bench"], cwd=REPO_ROOT)
else:
print("[desactivado] python -m training.train_cnn --model-type hybrid --run-name hybrid_lab ...")
¿Aporta algo el vector geométrico? (ablation)¶
Se entrenaron dos modelos idénticos en todo excepto una pieza: uno recibe solo la imagen
(cnn_only), el otro recibe imagen + geometría (hybrid). Comparados contra el banco de 117
fotos reales:
ablation = pd.DataFrame({
"banco sintético": [0.482, 0.597],
"fotos reales (n=117)": [0.709, 0.812],
}, index=["cnn_only (sin geometría)", "hybrid (con geometría)"])
ablation.style.bar(color="#c89b2b", vmin=0, vmax=1).format("{:.3f}")
+10 puntos en fotos reales, de forma consistente. El vector geométrico aporta de verdad, no
es ruido de muestra pequeña. Por eso hybrid es la variante en producción.
Por qué tres semillas, no una¶
Con un dataset de este tamaño, una sola corrida no dice si una mejora es real o suerte de
inicialización. Regla: un cambio solo se acepta si se mantiene en 3 semillas distintas. Así se
confirmó que la receta hybrid_lab es mejor que las alternativas: ~0.87 en sintético, ~0.83 en
fotos reales, de forma consistente en las tres corridas.
3. Evaluación honesta: tres bancos, de fácil a difícil¶
- Validación interna (split por filas): solo detecta roturas obvias.
- Banco sintético excluido: especímenes completos nunca vistos, pero sigue siendo render.
- Banco de fotos reales: otro dominio entero. Es la prueba que de verdad dice si el proyecto sirve para algo fuera del laboratorio.
Si un cambio mejora el banco 2 pero empeora el 3, mala señal: el modelo se está ajustando a particularidades del render sintético, no a la forma real del hueso.
Ejemplo real: el piloto de taxón en cráneo¶
Dentro del grupo cranio, un segundo modelo decide el taxón (humano / carnívoro / ungulado /
roedor). Examen honesto contra 52 fotos reales reservadas, filtra por taxón para ver el detalle.
from ipywidgets import interact, Dropdown
from IPython.display import display
taxon_cranio = pd.DataFrame({
"taxón": ["humano", "roedor", "ungulado", "carnívoro"],
"recall": [1.000, 1.000, 0.833, 0.636],
"precisión": [0.929, 0.444, 0.952, 0.875],
"n": [13, 4, 24, 11],
}).set_index("taxón")
def ver_taxon(taxon="todos"):
tabla = taxon_cranio if taxon == "todos" else taxon_cranio.loc[[taxon]]
display(tabla.style.bar(subset=["recall", "precisión"], color="#c89b2b", vmin=0, vmax=1).format({"recall": "{:.3f}", "precisión": "{:.3f}"}))
interact(ver_taxon, taxon=Dropdown(options=["todos"] + list(taxon_cranio.index), description="Taxón:"));
Accuracy global: 0.846. Antes de añadir fotos reales de ungulado, su recall era 0.0: un
puñado de fotos reales del dominio correcto movió más la métrica que cualquier cambio de
arquitectura. carnívoro es hoy el punto débil (se confunde con roedor), mismo patrón: pocas
fotos reales de ese taxón concreto, no un problema de red.
Lo que viene después¶
Ya tenemos modelos entrenados y evaluados con honestidad. El siguiente cuaderno
(pycon26_03_inferencia.ipynb) los pone a trabajar juntos: una regla rápida antes de la CNN
("cascada"), un segundo nivel que afina hueso concreto o taxón, y la API que expone todo esto a
una aplicación real.