OsteoLab: 3. Inferencia¶
Tercer y último cuaderno. Teníamos datos (cuaderno 1) y modelos entrenados y evaluados con honestidad (cuaderno 2). Aquí cerramos el círculo: ¿qué pasa cuando alguien sube una foto nueva y pide una respuesta?
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"
def primera_imagen(especie, hueso):
carpeta = BONE_DB / "renders_lab" / especie / hueso
vistas = sorted(p for p in carpeta.rglob("*.png") if "_mask" not in p.name)
return vistas[0] if vistas else None
# Cráneo de caballo: buen ejemplo para el piloto de taxón que vemos más abajo (debe salir "ungulado").
sample = primera_imagen("equus_caballus", "cranium")
print("Imagen de ejemplo:", sample.relative_to(REPO_ROOT))
1. Primer nivel: una regla barata antes de gastar la CNN¶
No todo necesita un modelo caro. Para el grupo hueso_largo, la feature elongation del
cuaderno 1 separa tan limpio que no hace falta ejecutar la CNN: si supera un umbral, la respuesta
ya es hueso_largo, calculado con geometría clásica en milisegundos.
¿Por qué justo elongation? Se probaron varias reglas candidatas y todas parecían igual de
buenas en el banco sintético (88-92% de acierto). La diferencia apareció en fotos reales:
elongation se mantuvo en 93% de acierto, las otras se desplomaron a 16%. Mismo patrón sim2real
de siempre: una medida puede parecer perfecta en sintético y fallar en el mundo real.
from shared.inference.predict_cascade import ELONGATION_THRESHOLD, classify_image as cascade_classify
print("Umbral de elongación:", ELONGATION_THRESHOLD)
with open(sample, "rb") as fh:
resultado = cascade_classify(fh, model_type="cnn_only", backend="classic")
# "gate" dice qué camino se tomó: "elongation_rule" (barata) o "cnn" (modelo entero).
print({k: v for k, v in resultado.items() if k != "cv_features"})
2. Segundo nivel: afinar hueso concreto o taxón¶
Una vez que sabemos el grupo morfológico, a veces interesa afinar más: ¿qué hueso largo exactamente? ¿de qué taxón es este cráneo?
Un único modelo gigante para todas las clases finas de golpe no funcionaba bien: ramas sin relación entre sí se interferían durante el entrenamiento. Solución: una cascada de dos etapas. La etapa 1 decide el grupo; según qué grupo salió, se invoca un modelo especializado solo en ese grupo, mucho más fácil de entrenar bien.
import pandas as pd
cascada = pd.DataFrame({
"grupo de etapa 1": ["hueso_largo", "vertebra", "cranio", "mandibula_maxilar"],
"qué afina la etapa 2": ["fémur / húmero / tibia / ...", "cervical / torácica / lumbar",
"taxón: humano / carnívoro / ungulado / roedor", "taxón"],
}).set_index("grupo de etapa 1")
cascada
Los grupos sin etapa 2 todavía devuelven stage2_pending: true explícito, para no confundir
"aquí no aplica" con "falta entrenar".
from shared.inference.predict_two_stage import classify_image_two_stage
with open(sample, "rb") as fh:
resultado = classify_image_two_stage(fh, backend="classic")
print({k: v for k, v in resultado.items() if k != "cv_features"})
La cascada completa, sobre tres especies¶
Mismo flujo, tres cráneos de especies distintas. La etapa 1 siempre dice cranio; lo
interesante es ver si la etapa 2 acierta el taxón de cada uno.
import matplotlib.pyplot as plt
import matplotlib.image as mpimg
especies = {"homo_sapiens": "humano", "equus_caballus": "ungulado", "canis_familiaris": "carnívoro"}
filas = []
fig, axes = plt.subplots(1, 3, figsize=(12, 4.5))
for ax, (especie, taxon_esperado) in zip(axes, especies.items()):
img_path = primera_imagen(especie, "cranium")
with open(img_path, "rb") as fh:
r = classify_image_two_stage(fh, backend="classic")
taxon = r.get("taxon") or {}
prediccion = taxon.get("prediction", "?")
probs = taxon.get("probabilities") or {}
confianza = probs.get(prediccion) if prediccion in probs else (max(probs.values()) if probs else None)
ax.imshow(mpimg.imread(img_path))
ax.set_title(f"{especie}\npredicho: {prediccion}", fontsize=9)
ax.axis("off")
filas.append({"especie": especie, "taxón esperado": taxon_esperado,
"taxón predicho": prediccion,
"confianza": confianza})
plt.tight_layout()
plt.show()
tabla_especies = pd.DataFrame(filas).set_index("especie")
tabla_especies["confianza"] = tabla_especies["confianza"].fillna(0.0)
tabla_especies.style.bar(subset=["confianza"], color="#c89b2b", vmin=0, vmax=1).format({"confianza": "{:.3f}"})
Resultado real: taxón de cráneo¶
Examen honesto contra 52 fotos reales reservadas que el modelo nunca vio en entrenamiento. Filtra por umbral de recall con el desplegable.
from ipywidgets import interact, FloatSlider
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 filtrar_por_recall(recall_min=0.0):
tabla = taxon_cranio[taxon_cranio["recall"] >= recall_min]
display(tabla.style.bar(subset=["recall", "precisión"], color="#c89b2b", vmin=0, vmax=1).format({"recall": "{:.3f}", "precisión": "{:.3f}"}))
interact(filtrar_por_recall, recall_min=FloatSlider(min=0, max=1, step=0.1, value=0, description="recall ≥"));
Accuracy global: 0.846. roedor tiene solo 4 ejemplos de test, ese recall perfecto no es
representativo. carnívoro es el punto débil real: más fotos reales de ese taxón mueven la
métrica más que cualquier cambio de arquitectura.
3. Cómo llega esto a una aplicación real: la API¶
Lo que acabamos de llamar como funciones de Python es, también, lo que expone la API en
producción (serving/backend/main.py), a la que llaman tanto la web como otras apps. Flujo
típico al subir una foto:
POST /filter/clip: ¿esto es un hueso? (cuaderno 1). Si no, fin.POST /classify: geométrico, Random Forest + punto en un mapa PCA.POST /hybrid/classify: la cascada de dos etapas sobre el modelo híbrido.GET /pca/reference: el fondo del scatter que dibuja la interfaz.
Detalle de diseño: cada módulo de inferencia carga sus modelos una sola vez al importarse, no en cada petición HTTP. Y si el modelo no está entrenado en ese entorno, falla con un mensaje explícito en vez de devolver un resultado vacío silencioso.
print('''
curl http://localhost:8000/health
curl -X POST http://localhost:8000/classify -F "[email protected]"
curl -X POST http://localhost:8000/hybrid/classify -F "[email protected]"
curl http://localhost:8000/pca/reference
'''.strip())
Resumen de la serie¶
- Cuaderno 1: de mallas 3D y fotos reales curadas a tablas de features geométricas, sin fuga de especímenes entre train y test.
- Cuaderno 2: dos modelos sobre esos datos (Random Forest y CNN híbrida), evaluados contra bancos cada vez más exigentes.
- Cuaderno 3 (este): cómo esos modelos se combinan en una cascada de decisiones y se exponen como una API real.
El hilo que atraviesa los tres: con pocos datos reales disponibles, casi toda decisión importante se validó contra fotos reales, nunca solo contra el banco sintético, porque ese es el único resultado que cuenta al final.