Cuando trabajamos con modelos de machine learning en producción, muchas veces nos enfocamos en servir predicciones en tiempo real. Pero, ¿qué pasa cuando tenemos que procesar grandes volúmenes de datos de forma offline? En estos casos usamos inferencia en batch.
En la nube de AWS, el servicio pensado para realizar este tipo de operaciones es SageMaker Batch Transform, una solución que nos permite aplicar modelos sobre datasets completos, sin necesidad de montar un endpoint de inferencia.
Ahora bien, Amazon SageMaker soporta de forma nativa varios frameworks como XGBoost, TensorFlow o PyTorch, pero hay modelos como LightGBM (un modelo bastante típico en la disciplina) que no están incluidos entre los contenedores preconstruidos de AWS. Por eso, si queremos usarlo para inferencia batch, tenemos que construir nuestro propio container.
Explicar la metodología para proceder en esos casos es el objetivo de este tutorial. En esta guía paso a paso mostraremos cómo:
- Armar un código local para predecir con un modelo de LightGBM.
- Empaquetarlo dentro de una imagen Docker compatible con SageMaker.
- Subir esa imagen a Amazon ECR y usar Batch Transform para correr inferencia sobre archivos almacenados en S3.
Todo esto sin magia, y con explicaciones claras pensadas para que puedas adaptarlo a tus propios proyectos.
¿Qué es AWS SageMaker AI?
Amazon SageMaker es una plataforma integral de machine learning (ML) en AWS que simplifica y acelera el flujo de trabajo para científicos de datos y profesionales de MLOps. Abstrae la complejidad de la infraestructura, permitiendo enfocarse en el despliegue de operaciones con IA en lugar de la gestión de recursos.
Soporta cada etapa del ciclo de vida de un modelo de machine learning, desde la preparación de datos con integración a servicios de AWS como S3 y Glue, hasta el entrenamiento flexible y escalable con frameworks populares (TensorFlow, PyTorch, etc.) en instancias CPU/GPU gestionadas automáticamente. Ofrece entrenamiento distribuido, optimización de hiperparámetros y gestión de experimentos.
Facilita el despliegue en producción con hosting en tiempo real para baja latencia y procesamiento batch para grandes conjuntos de datos. Además, proporciona monitoreo continuo para detectar problemas como la desviación de datos y la degradación del rendimiento.
SageMaker incluye herramientas integradas como notebooks basados en Jupyter y SageMaker Pipelines para automatizar y orquestar flujos de trabajo, mejorando la productividad.
¿Qué es SageMaker Batch Transform y cómo se diferencia de la inferencia en tiempo real?
Cuando se pone un modelo en producción, se tienen dos formas principales de servir predicciones: inferencia en tiempo real o inferencia batch.
- La inferencia en tiempo real implica exponer el modelo a través de un endpoint HTTPS (como una API). Cada vez que llega una solicitud, SageMaker procesa los datos y devuelve una predicción instantánea. Este enfoque es ideal para aplicaciones interactivas, como sistemas de recomendación o detección de fraude en tiempo real, donde la latencia es crítica.
- Por otro lado, SageMaker Batch Transform está diseñado para escenarios donde no necesitamos respuestas inmediatas, sino aplicar el modelo a grandes volúmenes de datos de forma masiva y offline. En lugar de enviar registros uno por uno, Batch Transform toma archivos completos desde S3 (por ejemplo, un CSV con miles o millones de filas), ejecuta las predicciones en paralelo, y guarda los resultados también en S3. No necesitás dejar un endpoint activo ni preocuparte por la disponibilidad del modelo.
Resumiendo todo esto en una sencilla tabla lo que dijimos arriba:
| Característica | Inferencia en Tiempo Real | Batch Transform |
| Latencia | Baja | Alta (procesamiento por lotes) |
| Costos | Continuos (endpoint activo) | Por uso (según job ejecutado) |
| Ideal para | APIs, aplicaciones en vivo | Jobs periódicos o masivos |
| Input/Output | JSON por request | Archivos en S3 |
¡Manos a la obra!
Este es un tutorial un poco más intermedio, pero tranqui que no te vamos a dejar a pata. Te vamos a dejar también algunos links por si hay algún tema que necesites repasar.
Todo el código que necesitás para ir siguiendo el tutorial lo encontrás en el repo que está por acá.
Requisitos previos
Antes de meternos de lleno en este tutorial, conviene que tengas:
- Conocimientos de Python y AWS. Conocimientos de entornos virtuales de Python.
- Conocimientos básicos de ejecución de scripts de Bash.
- Conocimientos básicos de Machine Learning, puntualmente de clasificación con modelos de ensambles de árboles de decisión.
- Conocimientos básicos de Docker: vamos a crear una imagen personalizada para correr nuestro modelo.
Recursos necesarios
- Cuenta de AWS con permisos para usar SageMaker y ECR (puede haber un costo asociado de 1 o 2 USD, principalmente por las imágenes de docker que almacenaremos en AWS ECR)
- Instalación local de Docker
- Instalación local de Python
- Instalación local de Poetry
- Instalación local de aws cli
- Instalación local de VScode (opcional)
Entorno de Python
Instalamos las dependencias en un ambiente de Poetry. Abriendo una terminal en el directorio de trabajo que vayamos a utilizar para este tutorial, usamos los comandos:
poetry init
poetry add numpy lightgbm scikit-learn pandas kagglehub
Para trabajar con jupyter notebooks en VScode, vamos a necesitar instalar también el paquete ipykernel. VScode nos ofrecerá hacerlo al correr la notebook por primera vez.
Otra opción es tomar el project.toml del repositorio, pegarlo en nuestro directorio de trabajo, y correr en el shell poetry install. Esto creará el ambiente con las dependencias necesarias automáticamente.
Preparación del dataset
- Elegimos el dataset. En nuestro caso, fraud detection dataset. Podemos descargarlo instalando kagglehub en nuestro entorno de Python local.
- Es un dataset para un problema de clasificación, en el que se trata de predecir, a partir de features resultantes de PCA, además de una variable temporal y el monto de transacción, si la transacción fue o no fraudulenta.
- Descargamos el dataset localmente, nos aseguramos de separar las features del target y a partir de ahí, se hace el split de train y test, y se guardan los dos datasets en formato csv.
- Todo esto está realizado en la notebook dataset/prepare_data.ipynb.
Paso 1: Código local para inferencia con LightGBM
1.1 Entrenar el modelo
El punto de partida es una notebook que haga el training y testing (sagemaker-batch-transform-tutorial/local_code/01_train_and_test.ipynb). Esta notebook simplemente carga el dataset, hace el split en train data y test data, entrena el modelo y guarda el modelo entrenado.
Pero necesitamos separarlo en dos partes: el script de training y el de testing. De esta forma, ya guardamos el modelo en un lugar aparte, y ya podemos acercarnos a parametrizar las carpetas de los datasets y la carpeta donde se guarda el modelo.
El script de training carga la data de entrenamiento, separa las features del modelo y el target, define y entrena el modelo, y guarda localmente el modelo entrenado en un archivo pickle en la carpeta especificada.
El script de test carga la data de testeo, separa las features del modelo y el target, carga el modelo ya entrenado, realiza predicciones e imprime por pantalla la precisión del modelo.
Los scripts locales son la base funcional (rápido de iterar y depurar). En el Paso 2 los vamos a adaptar para que tomen datos/modelo desde S3 y corran dentro de un contenedor Docker compatible con SageMaker, para pasar de “prueba local” a jobs reproducibles (Training/Batch Transform) sin reescribir lógica. Veamos cómo:
Paso 2: Crear un Docker container para inferencia con LightGBM
En esta sección, tomamos los scripts desarrollados anteriormente, los parametrizamos para que tomen las rutas de los archivos desde S3, y construimos los dockerfile y los scripts que serán los entrypoints para train y test.
Tenemos la siguiente estructura de carpetas:
- Creamos carpetas para train, test y models. La carpeta “dataset” va a quedar más arriba.
- Hay que subir a S3 los archivos CSV usados para entrenar y testear el modelo. Tenés que crear un bucket y reemplazar el nombre donde corresponda: a lo largo del tutorial lo vas a ver como <bucket-propio>. Dentro, una carpeta datasets, y carpetas train_data y test_data, a donde subimos los archivos csv generados.
- La estructura tiene que quedarte así:
s3://<bucket-propio>/datasets/train_data/train.csv
2.1 Construir la imagen
Desde el directorio containers, ejecutamos el comando para construir la imagen, según las instrucciones del Dockerfile (es muy estándar, no tiene ninguna indicación fuera de lo normal).
docker build -t lightgbm-train ./train
Para correrlo, armamos un shell script que cargue las access keys de AWS y pase como parámetros las direcciones de S3 necesarias para obtener datos y guardar el modelo.
Ahora viene lo divertido. Este script está diseñado para ejecutarse dentro de un contenedor en SageMaker: toma los datos de entrenamiento desde S3, entrena el modelo LightGBM y sube el resultado nuevamente a S3. Es nada menos que la base para poder integrarlo en un SageMaker Training Job reproducible.
Para correr el entrenamiento, simplemente corremos el shell script de entrenamiento:
$./train.sh
2.2. Correr la inferencia
Para correr el container de inferencia, armamos un shell script que cargue las access keys de AWS configuradas localmente, y pase como parámetro la dirección de S3 necesaria para obtener el modelo.
Con esto listo, podemos buildear la imagen usando:
docker build -t lightgbm-test ./test
¿Y qué es lo que tiene el script de test?
Esto lo que hace es:
- Descarga el dataset de test y el modelo entrenado desde S3.
- Carga ambos en memoria.
- Corre predicciones usando
predict_proba()de LightGBM. - Imprime las probabilidades de la clase positiva.
Paso 3: Subir las imágenes a ECR y ejecutar en SageMaker
En líneas generales, en esta sección veremos:
- Cómo construir containers para entrenar nuestro modelo con un Sagemaker Training Job,
- Cómo registrarlo en el Sagemaker Model Registry,
- Cómo utilizarlo para hacer inferencia en Batch sobre datos en S3.
Para los Jobs de entrenamiento e inferencia, haremos pequeños ajustes sobre nuestros containers, y para disparar los trabajos y registrar los modelos, utilizaremos funciones Lambda. Pero primero debemos estar autenticados con la propia cuenta de AWS y tener el AWS CLI instalado y configurado.
De forma gráfica, los pasos a realizar para poder desarrollar el entrenamiento con un Sagemaker Training Job y la inferencia con un Sagemaker Batch Transform Job son los que se describen en las siguientes figuras:
3.1. Login a ECR y crear repos
El primer paso es crear el repo, que lo hacemos sólo una vez. Acá también vas a tener que reemplazar algunos caracteres e IDs con lo propio de tu cuenta:
aws ecr create-repository --repository-name lightgbm-testing-container
Guardá el URI que devuelve el comando, que a partir de ahora lo vamos a denominar <repo-uri>. Debería lucir así:
<id-de-nuestra-cuenta>.dkr.ecr.us-east-2.amazonaws.com/lightgbm-testing-container
Ahora logeamos con Docker:
aws ecr get-login-password | docker login --username AWS --password-stdin <id-de-nuestra-cuenta>.dkr.ecr.<region>.amazonaws.com
3.2. Build & Push
Vamos a ubicarnos en la carpeta containers_sagemaker/ y desde ahí ejecutamos:
docker build -t lightgbm-test-sm ./test
Con esto listo, taggeamos y pusheamos la imagen:
docker tag lightgbm-test-sm:latest <repo-uri>
docker push <repo-uri>
3.3. Alojar la data
Por último, tenemos que dejar la data en un bucket de S3, idealmente en una ruta de este estilo:
s3://<bucket-propio>/datasets/train_data/train.csv
3.4. Función Lambda: Training Job
Ahora vamos a usar una Lambda para que se encargue de disparar el job de entrenamiento.
Importante: tenemos que tener un rol IAM con la capacidad de poder acceder y ejecutar en S3 y Sagemaker. Para el ejemplo, creamos uno llamado free-tier-sagemaker-full-access-role con política de AmazonS3FullAccess y SagemakerFullAccess.
Ahora hay que crear la Lambda lgbm_sm_launch_training_job. Esta Lambda tiene una layer de Sagemaker (acá te dejamos un artículo nuestro en el que también te contamos cómo usarlas, por si te sirve), por lo que hay que instalar los requerimientos localmente y crear un package que se va a subir junto con la función. Como al crear el package, el mismo pesa más de 50MB, hay que subirlo a cualquier ubicación de S3 y cargarlo en el servicio Lambda desde S3.
Un detalle importante del requirements.txt de esta Lambda: necesitamos usar la versión de sagemaker==2.215, de lo contrario obtendremos el error: “No module named ‘rpds.rpds’”. Esta clase de errores y advertencias son muy comunes cuando instalás paquetes de distintas fuentes.
Fijate cómo estamos instalando las dependencias: el -t package/ al final lo que hace es en vez de instalar las librerías en el entorno global o virtual (site-packages), las instala dentro de la carpeta local package/. Esto es común en proyectos como este, donde necesitamos empaquetar dependencias junto con tu código (como muchas veces es necesario en una Lambda).
Para que la función pueda usar las dependencias empaquetadas, necesitamos asociarlas como Lambda Layer. Esto se hace desde la consola de AWS Lambda, en la pestaña Layers, creando una nueva layer y subiendo allí el archivo lambda_package.zip (o bien indicando la ubicación en S3).
Una vez creada, la layer queda disponible y podemos adosarla a nuestra función lgbm_sm_launch_training_job desde la misma consola o vía AWS CLI. De esta forma, la Lambda tendrá acceso a las librerías necesarias (en este caso, sagemaker==2.215) sin superar el límite de tamaño del deployment package.
Otro detalle importante es que hay que hacer coincidir la versión de Python de la Lambda local con la versión de Python seteada al crear la Lambda en la consola (UI) de AWS.
Luego de que la Lambda corra exitosamente, podremos ver que se ha disparado un Sagemaker Traning Job, y al finalizar éste, nuestro modelo recién entrenado estará ubicado en el directorio que especificamos en la Lambda (en nuestro caso, s3://<bucket-propio>/models_sm/).
3.5. Función Lambda para registrar el modelo
Acá lo que buscamos es registrar el modelo en el Sagemaker Model Registry, para que quede vinculada la imagen de Docker que está alojada en ECR, con el ARN del modelo que se entrenó con el Sagemaker Training Job. De esta forma, en adelante, al invocar la imagen, se utilizará el modelo ya especificado.
El punto central es el llamado a create_model para registrar un nuevo SageMaker Model, vinculando:
- El contenedor de inferencia (Docker image en ECR).
- El artefacto entrenado (modelo en S3).
- El rol IAM que autoriza la ejecución.
Con esto, el modelo queda registrado en SageMaker y disponible para usarse en endpoints o en Batch Transform Jobs.
3.6. Función Lambda para lanzar el Batch Transform Job
En este caso, vamos a crear un transformer que recibirá como parámetro más importante el nombre del modelo tal cual se registró en el Sagemaker Model Registry en el paso anterior. Notemos que no se hace referencia a ningún otro dato o ubicación del modelo entrenado: todo se obtendrá desde el Registry de Sagemaker.
El Batch Transform Job se creará utilizando el método transform() del Transformer. Este método permite especificar qué columnas del dataset de entrada se enviarán al modelo para realizar la inferencia, y cómo se va a componer el archivo con las predicciones: puede elegirse entregar sólo las predicciones, o incorporar también las features utilizadas para la inferencia, y la columna de ID que identifica cada record de entrada (si la hubiera).
Después del job, los resultados estarán en nuestro bucket de S3. Si queremos, siguiendo la nomenclatura del bucket que usamos, podemos descargarlos con:
aws s3 cp s3://<bucket-propio>/predictions/test.csv.out .
En conclusión…
Hemos creado una solución personalizada y escalable para hacer inferencia en batch con modelos LightGBM en SageMaker. Esta arquitectura permite reutilizar modelos entrenados y mantener pipelines reproducibles en un entorno MLOps profesional.
En entregas siguientes podemos ver operaciones complementarias a la propia inferencia, necesarias para conseguir un modelo productivo robusto.
¡Gracias por haber llegado hasta acá! ¿Tenés dudas o sugerencias? Podés escribirme a fernando@deployr.ai o dejar tu comentario en el blog.
Referencias adicionales:
- Fraud detection dataset – https://www.kaggle.com/datasets/whenamancodes/fraud-detection/data
- Batch transform for inference with Amazon SageMaker AI – https://docs.aws.amazon.com/sagemaker/latest/dg/batch-transform.html
- Ejemplo: Customer Churn Prediction with XGBoost – https://amazon-sagemaker-examples-anve.readthedocs.io/en/latest/introduction_to_applying_machine_learning/xgboost_customer_churn/xgboost_customer_churn_outputs.html
- Batch Transform Input and Output Filters – https://docs.aws.amazon.com/sagemaker/latest/dg/batch-transform-data-processing.html
- Tabular classification with Amazon SageMaker LightGBM and CatBoost algorithm – https://sagemaker-examples.readthedocs.io/en/latest/introduction_to_amazon_algorithms/lightgbm_catboost_tabular/Amazon_Tabular_Classification_LightGBM_CatBoost.html
- Sagemaker Batch Transform – Emily Webber from AWS – https://www.youtube.com/watch?v=Z9FtrRq0rc0
- Containers para Batch transform y para inferencia, documentación importante – https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-batch-code.html
- Amazon | Adapt your own inference container – https://docs.aws.amazon.com/sagemaker/latest/dg/adapt-inference-container.html
- Sagemaker| Bring your own container – https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-debugger/build_your_own_container_with_debugger/debugger_byoc.html
