kerasnip: Un Puente entre ‘keras’ y ‘tidymodels’

Grupo de Usuarios de R de Madrid | Febrero 2026

kerasnip v0.1.0.900

Docs: davidrsch.github.io/kerasnip · Repo: github.com/davidrsch/kerasnip

Empezar con energia. Preguntar: “¿Quién usa tidymodels?” y “¿Quién ha peleado con arquitecturas Keras?”

Decir: - Keras y tidymodels son como aceite y agua; kerasnip es el emulsionante. - Hoy: resolver el problema del ajuste de arquitectura.

Hoy

• Por qué es difícil ajustar modelos Keras dentro de tidymodels
• Qué genera kerasnip y por qué importa
• Flujo secuencial: ajuste estructural con num_{block}
• Flujo funcional: grafos con ramas y uniones con inp_spec()

Mantener esta diapositiva en 20 segundos. Es orientación, no contenido.

Decir: - Pasamos del problema al código funcional rápidamente. - Primera parte: API secuencial. Segunda parte: grafos funcionales. - Al final hay una herramienta de depuración que vale la pena conocer.

El Panorama y la Brecha

Keras (vía keras3)

• Aprendizaje profundo
• Pensado para tensores, imperativo
• Agnóstico al backend (TF, JAX, Torch)
• Grafos arbitrarios de capas

tidymodels

• Aprendizaje automático
• Pensado para data frames, declarativo
• Interfaz unificada (fit, predict)
• Ajuste de hiperparámetros estandarizado

La brecha: tune_grid() maneja el learning rate sin problema, pero ajustar la estructura es imposible. parsnip espera argumentos fijos; los modelos Keras son grafos arbitrarios.

Analogia: Keras = mesa de arquitecto (papel en blanco); tidymodels = formulario con casillas fijas. kerasnip adapta los formularios a los dibujos.

Decir: - Ya se puede ajustar el learning rate con keras3 + tidymodels. La fricción está en la topología, profundidad y ancho viven en código Keras, no en argumentos con nombre del spec. - kerasnip no reemplaza keras3. Genera nuevas funciones spec de parsnip que usan el engine keras existente. - Una frase sobre por qué no otros paquetes: reticulate es demasiado bajo nivel, luz/brulee son solo Torch, parsnip::mlp() es demasiado fijo para búsqueda arquitectónica.

Transición: Veamos cómo lo resuelve kerasnip, un solo diagrama.

Modelo Mental

flowchart LR
  classDef step fill:#f5f7fa,stroke:#5c6b7a,color:#1b3a57,stroke-width:2px;
  classDef tune fill:#BF281B,stroke:#BF281B,color:#ffffff,stroke-width:2px;

  A["Bloques<br/>(funciones R simples)"] --> B["Función spec<br/>create_keras_*_spec()"]
  B --> C["Workflow<br/>recipe() + workflow()"]
  C --> D["Ajuste<br/>tune_grid()"]
  A -. "args → ajustables<br/>num_{block} repite" .-> B

  class A,B,C step;
  class D tune;

Una regla: si quieres ajustarlo, hazlo argumento de la función.

Dedicar unos 60 segundos aquí. Este diagrama es toda la charla en una imagen.

Decir: - Escribes funciones R simples llamadas bloques. Cada bloque devuelve capas Keras. - create_keras_*spec() lee esas funciones y genera un nuevo modelo parsnip. - A partir de ahí es tidymodels estándar: recipe, workflow, tune_grid. - La flecha punteada es la idea clave: los argumentos de los bloques se convierten automáticamente en argumentos ajustables del spec, prefijados con el nombre del bloque. dense_block(units=128) se convierte en body_units. Y num{block} controla cuántas veces se repite un bloque, eso es la profundidad como hiperparámetro.

Si alguien se pierde: bloques → spec → workflow → ajuste. Todo lo demás es detalle.

Transición: Construyamos uno. Primero el API secuencial, predecir precios de diamantes.

Bloques Secuenciales

input_block <- function(model, input_shape) {
  keras_model_sequential(input_shape = input_shape)
}

dense_block <- function(model, units = 128, dropout = 0.0) {
  model |>
    layer_dense(units = units, activation = "relu") |>
    layer_dropout(rate = dropout)
}

output_block <- function(model) {
  model |> layer_dense(units = 1)
}

Decir: - Estas son funciones R simples. Nada de kerasnip aquí todavía. - La firma de la función es todo: units y dropout se vuelven ajustables porque son argumentos con valores por defecto. - dense_block es el repetible, num_body controlará cuántas veces se apila. - input y output no tienen argumentos ajustables a propósito: la forma de entrada la fija el dato, la salida la fija la tarea.

Señalar el código mientras dices: “body_units viene de units aquí, body_dropout de dropout. El prefijo body viene del nombre que le daremos al bloque en la lista de la siguiente diapositiva.”

Transición: Ahora pasamos estos bloques a create_keras_sequential_spec y obtenemos un modelo parsnip.

Generar Spec + Ajuste Estructural

Registrar el spec

create_keras_sequential_spec(
  model_name = "diamond_mlp",
  layer_blocks = list(
    input  = input_block,
    body   = dense_block,  # repetible
    output = output_block
  ),
  mode = "regression"
)

Esto crea diamond_mlp(), una función de modelo parsnip estándar.

Tratar la topología como hiperparámetro

spec <- diamond_mlp(
  num_body     = tune(),  # profundidad: 1, 2, 3…
  body_units   = tune(),  # ancho: 32, 64, 128…
  body_dropout = tune(),
  fit_epochs   = 20
) |>
  set_engine("keras")

num_body y body_units se generan automáticamente del nombre del bloque y sus argumentos.

Decir: - Izquierda: una llamada, un nuevo modelo parsnip. Eso es todo lo que hace kerasnip estructuralmente. - Derecha: ahora la profundidad es tune() igual que cualquier otro hiperparámetro. Esto es lo que no era posible antes. - Señalar num_body: esto controla cuántas veces se apila dense_block. Con tune() estás buscando en el espacio de arquitecturas. - Señalar body_units: el prefijo body_ viene de llamar “body” al bloque en la lista de la izquierda.

Transición: Ahora lo metemos en un workflow estándar.

Workflow con Diamantes

library(tidymodels)
library(kerasnip)
data(diamonds, package = "ggplot2")

diamonds_split <- initial_split(diamonds, strata = price)
diamonds_train <- training(diamonds_split)

diamonds_rec <- recipe(price ~ ., data = diamonds_train) |>
  step_dummy(all_nominal_predictors()) |>
  step_zv(all_predictors()) |>
  step_normalize(all_numeric_predictors())

wf <- workflow() |> add_recipe(diamonds_rec) |> add_model(spec)

params <- extract_parameter_set_dials(wf) |>
  update(
    num_body     = dials::num_terms(c(1, 4)),
    body_units   = dials::hidden_units(c(32, 256)),
    body_dropout = dials::dropout(c(0, 0.4))
  )

grid  <- grid_latin_hypercube(params, size = 20)
folds <- vfold_cv(diamonds_train, v = 5, strata = price)
res   <- tune_grid(wf, resamples = folds, grid = grid)

Decir: - Esto es idéntico a cualquier otro workflow de tidymodels. Ese es el punto. - La receta debe producir matrices numéricas: step_dummy + step_normalize son obligatorios para Keras. - extract_parameter_set_dials detecta los ajustables automáticamente, solo actualizas los rangos. - Consejo práctico: empieza con size = 8 al probar una arquitectura nueva. Escala una vez que sabes que construye correctamente.

Transición: Veamos qué salió.

Resultados (Diamantes): CV — Tabla

num_body	body_units	body_dropout	mean	std_err
2	62	0.060	767.101	57.202
2	35	0.180	775.932	45.765
2	49	0.030	782.881	51.891
2	98	0.121	783.726	54.377
1	127	0.276	842.246	45.535

Mantener esta diapositiva en 30 segundos y pasar al gráfico.

Decir: - Estas son estimaciones de validación cruzada. Seleccionamos con CV, nunca con el test. - Busca una zona estable: buen RMSE medio y std_err pequeño. Esa es la arquitectura a llevar adelante. - Elige la más simple dentro de 1 std_err del mejor, no necesariamente la primera fila.

Resultados (Diamantes): CV — Gráfico

Decir: - Si las líneas se aplanan al aumentar num_body, más profundidad no aporta, elige el modelo menos profundo. - Cada faceta es un valor de dropout: busca un panel donde la diferencia entre opciones de ancho sea pequeña. Esa es una zona robusta.

Transición: Confirmación final en test.

Resultados (Diamantes): Test — Tabla

.metric	.estimate
rmse	736.1172
mae	349.0455
rsq	0.9660

Decir: - El test es solo para reportar. La arquitectura se eligió con CV, esto es confirmación. - Si el test empeora mucho respecto a CV, sospecha data leakage o una arquitectura inestable.

Resultados (Diamantes): Test — Gráfico

Decir: - Puntos cerca de la diagonal son buenas predicciones. Desviación sistemática hacia abajo en precios altos significa que el modelo subestima diamantes caros, esperable, ya que son raros en el entrenamiento.

Transición: Antes de pasar al API funcional, una herramienta que ahorra mucho tiempo de depuración.

Depuración: compile_keras_grid()

prep_rec <- prep(diamonds_rec, training = diamonds_train)
juiced <- juice(prep_rec)
x <- juiced |> select(-price)
y <- juiced$price
modified_grid <- tibble(
    num_body = c(3, 6),
    body_units = c(-10, 128),
    body_dropout = c(0.2, 0.2)
)

dbg <- compile_keras_grid(spec, modified_grid, x, y)
dbg

# A tibble: 2 × 5
  num_body body_units body_dropout compiled_model                          
     <dbl>      <dbl>        <dbl> <list>                                  
1        3        -10          0.2 <NULL>                                  
2        6        128          0.2 <keras.src.models.sequential.Sequential>
# ℹ 1 more variable: error <chr>

Decir: - Antes de lanzar tune_grid con 20 configuraciones, ejecuta esto con una para confirmar que el modelo construye correctamente. - La columna error indica qué filas del grid fallaron y por qué, detecta esto antes de gastar cómputo. - extract_valid_grid() filtra los builds correctos; inform_errors() resume los fallos en todo el grid. - Regla: siempre compila antes de ajustar.

Transición: El mismo patrón de workflow, ahora con un grafo no lineal. API funcional.

API Funcional: Bloques + Grafo

Los bloques reciben tensores, no modelos

input_block <- function(input_shape) {
  layer_input(shape = input_shape,
              name = "features")
}

dense_block <- function(tensor,
                        units = 64,
                        dropout = 0.0) {
  tensor |>
    layer_dense(units = units,
                activation = "relu") |>
    layer_dropout(rate = dropout)
}

concat_block <- function(input_a, input_b) {
  layer_concatenate(list(input_a, input_b))
}

output_block <- function(tensor, num_classes) {
  tensor |>
    layer_dense(units = num_classes,
                activation = "softmax")
}

inp_spec() conecta salidas con entradas por nombre

create_keras_functional_spec(
  model_name = "attrition_towers",
  layer_blocks = list(
    main_input = input_block,
    tower_a    = inp_spec(
                   dense_block,
                   "main_input"),
    tower_b    = inp_spec(
                   dense_block,
                   "main_input"),
    joined     = inp_spec(
                   concat_block,
                   c(input_a = "tower_a",
                     input_b = "tower_b")),
    output     = inp_spec(
                   output_block,
                   "joined")
  ),
  mode = "classification"
)

Decir: - Secuencial: los bloques reciben un modelo y apilan capas. Funcional: los bloques reciben tensores y devuelven tensores. Esa es la única diferencia estructural. - inp_spec(func, inputs) solo etiqueta qué salida upstream alimenta qué argumento, como cables de parcheo en un sintetizador modular. - Este grafo: una entrada se divide en dos torres en paralelo, se concatenan, luego la salida. No lineal, pero el workflow es completamente idéntico. - Usa secuencial para una cadena recta. Usa funcional cuando necesites ramas, uniones o skip connections. - tower_a_units y tower_b_units se generan automáticamente con la misma convención de prefijos que antes.

Transición: El workflow, reconocerás cada línea.

Workflow de Rotación

library(tidymodels)
library(modeldata)
data(attrition)

attr_split <- initial_split(attrition, strata = Attrition)
attr_train <- training(attr_split)

attr_rec <- recipe(Attrition ~ ., data = attr_train) |>
  step_zv(all_predictors()) |>
  step_dummy(all_nominal_predictors()) |>
  step_normalize(all_numeric_predictors())

attr_spec <- attrition_towers(
  tower_a_units = tune(),
  tower_b_units = tune(),
  fit_epochs    = 20
) |> set_engine("keras")

attr_wf <- workflow() |> add_recipe(attr_rec) |> add_model(attr_spec)

params <- extract_parameter_set_dials(attr_wf) |>
  update(tower_a_units = dials::hidden_units(c(16, 128)),
         tower_b_units = dials::hidden_units(c(16, 128)))

res <- tune_grid(attr_wf,
                 resamples = vfold_cv(attr_train, v = 3, strata = Attrition),
                 grid      = grid_latin_hypercube(params, size = 12))

Decir: - Patrón idéntico al ejemplo secuencial. Ese es el punto de kerasnip, la complejidad del grafo queda completamente oculta. - Asegúrate de que el outcome sea factor con niveles estables.

Transición: Resultados.

Resultados (Rotación): CV — Tabla

tower_a_units	tower_b_units	mean	std_err
70	64	0.8048	0.0218
41	33	0.8017	0.0239
47	24	0.7974	0.0185
21	105	0.7955	0.0278
80	95	0.7926	0.0219

Mantener en 30 segundos y pasar al mapa de calor.

Decir: - Misma lectura que antes: ROC AUC medio más std_err. Seleccionamos con CV. - Elige la arquitectura más simple dentro de 1 std_err del mejor.

Resultados (Rotación): CV — Gráfico

Decir: - Un mapa plano significa que la arquitectura es robusta, el tamaño de las torres no importa mucho, elige el más pequeño. - Un pico claro significa que el modelo es sensible, vale la pena acotar la búsqueda alrededor de esa zona en una segunda pasada.

Transición: Confirmación final en test.

Resultados (Rotación): Test — Tabla

.metric	.estimate
accuracy	0.8699
roc_auc	0.8232

Decir: - En conjuntos desbalanceados como attrition, el ROC AUC es más informativo que el accuracy, el accuracy puede verse bien simplemente prediciendo la clase mayoritaria. - De nuevo: el test es para reportar, no para decidir.

Resultados (Rotación): Test — Gráfico

Decir: - Cuanto más lejos de la diagonal, mejor la discriminación. - Cuando dos arquitecturas dan curvas similares, elige siempre la más simple.

Transición: Cerramos con el resumen práctico.

Consejos Prácticos y Valoración

Para evitar problemas

• Ejecuta siempre compile_keras_grid() antes de ajustar
• Bloques pequeños y testeables, aísla errores con 2–3 bloques
• Ajusta estructura (profundidad/ancho) primero; hiperparámetros de entrenamiento después
• Mantén el espacio de búsqueda razonable

Por qué vale la pena

1. Paridad de workflow — recipes, workflows, tune funcionan igual que con glmnet
2. Reproducibilidad — la topología es código; controla tu arquitectura con git
3. Extensibilidad — envuelve cualquier capa Keras (Transformers, RNNs) en un bloque

Objetivo: que la gente salga con una respuesta clara a “¿debería probar esto?”

Decir: - La curva de aprendizaje está en escribir buenos bloques. Después de eso, todo es tidymodels estándar. - Si ya usas tidymodels, lo único nuevo es definir bloques y llamar a create_keras_*_spec(). - El paquete está en GitHub, contribuciones y feedback bienvenidos.

Dejar de compartir pantalla y abrir turno de preguntas.

Recursos

• 📦 github.com/davidrsch/kerasnip
• 📑 davidrsch.github.io/kerasnip
• 📑 Presentación