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?

In [1]:
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))
Imagen de ejemplo: base_datos_osea/renders_lab/equus_caballus/cranium/stock_sinfuente_horse_equus_ferus_caballus/equus_caballus_cranium_stock_sinfuente_horse_equus_ferus_caballus_drop00_view000.png

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.

In [2]:
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"})
Umbral de elongación: 0.9
{'found': True, 'prediction': 'cranio', 'probabilities': {'costilla': 0.011998, 'cranio': 0.320152, 'hueso_largo': 0.002678, 'hueso_pequeno': 0.003951, 'hueso_plano': 0.110067, 'mandibula_maxilar': 0.178607, 'pelvis': 0.248163, 'sacro': 0.015428, 'vertebra': 0.108956}, 'modality_weights': None, 'gate': 'cnn'}

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.

In [3]:
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
Out[3]:
qué afina la etapa 2
grupo de etapa 1
hueso_largo fémur / húmero / tibia / ...
vertebra cervical / torácica / lumbar
cranio taxón: humano / carnívoro / ungulado / roedor
mandibula_maxilar taxón

Los grupos sin etapa 2 todavía devuelven stage2_pending: true explícito, para no confundir "aquí no aplica" con "falta entrenar".

In [4]:
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"})
{'found': True, 'prediction': 'cranio', 'probabilities': {'costilla': 0.0, 'cranio': 0.999098, 'hueso_largo': 0.0, 'hueso_pequeno': 0.0, 'hueso_plano': 9e-06, 'mandibula_maxilar': 0.00089, 'pelvis': 1e-06, 'sacro': 2e-06, 'vertebra': 0.0}, 'modality_weights': None, 'fine_bone': None, 'taxon': {'prediction': 'ungulado', 'probabilities': {'carnivoro': 0.151041, 'humano': 0.00743, 'roedor': 0.08309, 'ungulado': 0.758439}}, 'stage2_pending': False}

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.

In [5]:
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}"})
No description has been provided for this image
Out[5]:
  taxón esperado taxón predicho confianza
especie      
homo_sapiens humano humano 0.676
equus_caballus ungulado ungulado 0.758
canis_familiaris carnívoro carnivoro 0.692

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.

In [6]:
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:

  1. POST /filter/clip: ¿esto es un hueso? (cuaderno 1). Si no, fin.
  2. POST /classify: geométrico, Random Forest + punto en un mapa PCA.
  3. POST /hybrid/classify: la cascada de dos etapas sobre el modelo híbrido.
  4. 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.

In [7]:
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())
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

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.