# Documentación Pipeline Training-Serving
---

# Resumen de la solución
Se tiene un proceso (Pipeline) capaz de cargar desde un repositorio el código (Python) necesario para entrenar y guardar el modelo resultante. Este modelo luego es usado por otros componentes de la pipeline encargados de disponibilizarlo.

Por tanto, basta con ejecutar esta pipeline (un clic en la plataforma de Kubeflow), dando como input el repositorio y el nombre del modelo, para que de manera automática se disponga de un modelo entrenado y listo para ser consumido vía API en AI Platform de Google.

## Contexto: Demostración a cliente
Se describe una solución implementada en Google Cloud Platform (GCP) que busca dar respuestas a las necesidades de:
- Monitoreo: métricas de modelo a nivel operacional
- Automatizacion: CI/CD training-testing deployment reentrenamiento de acuerdo a monitoreo de data y métricas

Para dar respuesta a modo de demostración a estas necesidades, se usó la herramienta Kubeflow como orquestador de una serie de otras herramientas que provee GCP para los propósitos mencionados anteriormente:

- **Monitoreo**:

- ![](https://i.imgur.com/sP2iQD6.png "AI Platform" =300x70)

Se usaron Jobs para realizar el entrenamiento, la creación del modelo y el versionado (disponibilización) del modelo.

> Los Jobs son una solución auto-administrada en GCP, por lo que se puede dar el escalado de maquinas, en caso de no ser usadas los nodos pueden ir a 0.

- ![](https://i.imgur.com/PGkBbrE.png "Logging" =270x70)

- ![](https://i.imgur.com/mjevpPT.png "Monitoring" =280x70)

Al generarse Jobs, estos quedan vinculados automáticamente a la plataforma de Logging de GCP, donde se lleva un registro exhaustivo de log de aplicaciones. Estos logs pueden ser personalizados.

Los Jobs son automáticamente leídos por la plataforma de Monitoring de GCP, donde se pueden generar métricas y gráficos personalizados. Sin embargo, los logs que provee por defecto entregan información detallada del uso de recursos como CPU, storage, o GPU si se usaran en algún proceso.

- **Automatizacion**:

- ![](https://i.imgur.com/QzhSV50.png "GIT" =210x70)

- ![](https://i.imgur.com/sP2iQD6.png "AI Platform" =300x70)

Elemento fundamental del desarrollo de aplicaciones es generar procesos de CI/CD amigables. GIT se ha vuelto de uso universal como parte de esos procesos en complemento con otras herramientas. Existen variadas plataformas para gestionar proyectos Git (Github, GitLab, bitbucket, etc), en particular para esta demostración se utilizó Bitbucket.

Para proyectos de Machine Learning el enfoque de ocupar prácticas DevOps e integrarlas dentro del desarrollo de estos proyectos se llama MLOps. Estos proyectos presentan particularidades como la necesidad de versionar no solo el código sino también los datos que en conjunto generan un modelo determinado.

A los procesos tradicionales de CI/CD se debe incorporar un proceso de CT (Continuous Training) el cual debe ser orquestado para facilitar la puesta en producción de nuevos modelos en la medida que el equipo considere situaciones como: versiones mejores del modelo, se tengan nuevos datos, caída en la performace del modelo actual, uso excesivo de recursos, etc.

Para tomar estas decisiones es fundamental el monitoreo tanto del performance del modelo como de los recursos de la solución.

En esta demostración se utilizó [Kubeflow](https://www.kubeflow.org/) como herramienta de orquestación para generar procesos de CI/CD+CT, donde GIT en conjunto con las herramientas de AI Platform (Training, Models, Jobs, Jupyter notebooks) logran generar un proceso de entrenamiento y deploy __automatizado__.

Los ciclos de re-entrenamiento, es decir, dada una métrica o un trigger tomar decisiones si entrenar nuevamente y generar nuevos modelos, pueden ser fácilmente implementados a partir de lo construido en esta demostración. Sin embargo, dependerá de las necesidades del equipo encargado de mantener los modelos y del problema tratado si es correcto automatizar el proceso de CT, para ello se debe construir un sistema robusto que tome la decisión de re-entrenar.

# Kubeflow
Kubeflow es una herramienta que permite manejar el end-to-end de proyectos de Machine Learning. Esta herramienta deja llevar a cabo prácticas de MLOps, donde es importante versionar datos y código.
Los procesos o pasos que deben considerarse en esta práctica son los siguientes:

fuente: [Componentes de un proyecto de ML](https://cloud.google.com/solutions/machine-learning/mlops-continuous-delivery-and-automation-pipelines-in-machine-learning?hl=es-419)

Kubeflow es open-source y agnóstico al entorno de ejecución. Su único requisito es Kubernetes, por lo cual en donde esté instalado podrá ejecutarse sin problemas. Debido a que las nubes tienen soporte para kubernetes, Kubeflow puede alojarse en cualquiera de ellas (Google, AWS, Azure, IBM, etc).

Esta herramienta trabaja en base a componentes, que a grandes rasgos son cajas en las cuales se pueden definir entradas y salidas. Cada componente puede quedar enlazado a otro dependiendo de los requerimientos del problema/solución.

Es importante notar que no es posible crear ciclos realimentados y sólo es posible definir el paso a paso en orden secuencial. Sin embargo, pueden existir tareas que sean activadas de un mismo componente y sin problema trabajar en paralelo.

fuente: [Ejemplo de Pipeline](https://www.kubeflow.org/docs/pipelines/overview/pipelines-overview/)

Kubeflow dispone de un SDK en Python que permite definir componentes con toda su lógica en el mismo lenguaje. También dispone de comandos por CLI, pero estos son un subconjunto del anterior. Se recomienda utilizar el SDK en Python para sacar el mayor provecho a esta herramienta.

# Descripción de componentes
Se diseñan cuatro (4) componentes que permiten realizar la pipeline de training-serving. Estos son:
- Authorization
- Training
- Create model
- Create version

La interconexión entre los componentes es la siguiente:


Es importante destacar que esta pipeline se diseñó con la finalidad de que funcione en cualquier entorno. Es decir, que al exportar la pipeline y entregársela a otra persona para que la ejecute en su entorno (GCP) funcione de manera correcta y efectiva aunque el proyecto no sea el mismo.

El proceso diseñado permite obtener valores del entorno en donde se está ejecutando, ya sea token, id de proyecto, nombre de los buckets en donde se encuentra o se guarda información, entre otras cosas.
Luego, nos permite entrenar un modelo en el entorno de AI Platform con los parámetros de entrenamiento que se diseñaron. El código de entrenamiento es totalmente personalizado pudiendo ser usadas bibliotecas como Scikit-Learn, Tensorflow, OpenCV, etc. Fue creado en Python y subido a un repositorio GIT. De aquí además se obtienen algunas configuraciones necesarias para el correcto funcionamiento del componente. El componente finaliza su ejecución al enviar el job hasta AI Platform sin verificar su correcto despliegue.
En paralelo, se ejecuta el componente "Create model" el cual verifica la existencia del "encapsulamiento" de un modelo con el mismo nombre, de lo contrario lo crea, y de asignar un código de versión al modelo cuando este sea cargado.
Una vez que hayan concluido de manera exitosa los tres componentes anteriores, comienza a ejecutarse el componentes "Create version", el cual espera la existencia del modelo en la dirección del bucket en donde fue configurado. Una vez que existe el modelo, se procede a subir una versión del mismo.

La pipeline finaliza al momento de enviar de manera correcta el modelo hacia AI Platform sin verificar el correcto despliegue del mismo. Para revisar que todo el proceso se llevó a cabo de manera correcta se puede revisar "Logging" de GCP el cual contiene el detalle de las procesos que fueron ocurriendo.

# Requerimientos de la solución
Para poder ejecutar esta solución que permite el entrenamiento y despliegue automático del modelo es necesario contar con lo siguiente:
- Cuenta en GCP con facturación activada
- Kubeflow Pipelines instalado en el proyecto en cuestión
- Repositorio git con la siguiente estructura:
- \_\_init\_\_.py
- <script de entrenamiento>.py
- training_input.json
- Acceso al repositorio en modo lectura con "Access key"

El archivo de configuración training_input.json necesita tener la siguiente estructura:

{
"PYTHON_TRAIN" : "<script de entrenamiento>.py",
"JOB_NAME" : "<nombre del job>",
"WAITING_TIME_MIN" : <tiempo de espera máximo en minutos>,
"MACHINE" : "<tipo de máquina>",
"FRAMEWORK" : "<nombre del framework>"
"args": [
"<argumento 1>",
"<argumento 2>",
...
"<argumento n>",
]
}

En donde:
- <script de entrenamiento>: Nombre del archivo de entrenamiento
- <nombre del job>: prefijo que se le asignará al trabajo de entrenamiento. El sufijo es la fecha de creación de dicho trabajo.
- <tiempo de espera máximo en minutos>: Tiempo en minutos en el cual el componentes "Create version" espera a que el modelo sea subido a cloud storage
- <tipo de máquina>: Nombre del tipo de máquina en la cual se realizará el trabajo de entrenamiento. Ej: n1-standard-4. Para más detalles dirigirse [aquí](https://cloud.google.com/ai-platform/training/docs/machine-types?hl=es)
- <nombre del framework>: estas pueden ser tres opciones escritas de la siguiente manera: scikit_learn, tensorflow, xgboost. Tener en cuenta que este parámetro hace alusión al framework con el cual se entrena el modelo, por lo que soportará modelos con extensión de cada biblioteca. Para scikit_learn el modelo __se debe llamar__ model.joblib o model.pkl. Para tensorflow el modelo __se debe llamar__ saved_model.pb o saved_model.pbtxt. Para xgboost el modelo __se debe llamar__ model.bst. Documentación de los nombres de modelos: [1](https://cloud.google.com/ai-platform/prediction/docs/exporting-for-prediction?hl=es-419#xgboost.booster), [2](https://cloud.google.com/ai-platform/prediction/docs/exporting-savedmodel-for-prediction?hl=es-419).
- <argumento n>: parámetros de entrada del <script de entrenamiento>

Por ejemplo, algunos argumentos podrían ser los siguientes

"--n-estimators=500",
"--n-jobs=8",
"--bucket-name=gs://<nombre del bucket>/",
"--data-path=<nombre del archivo de datos de entrenamiento>"

Para definir parámetros de entrada al script de Python tomar en cuenta lo siguiente:

    import argparse
    
    def train(arg_1, arg_2):
        # Definir funciones que permitan hacer el entrenamiento
        pass
    
    if __name__ == "__main__":
        # Obtener los argumentos pasados por consola al script de python
        parser = argparse.ArgumentParser()
        parser.add_argument('--arg-1', type=int, required=True,
                            help='Primer argumento de la función train...'
                                 'artifacts (integer, required)')  
        parser.add_argument('--arg-2', type=str, required=True,
                            help='Segundo argumento de la función train...'
                                 'artifacts (string, required)') 
        
        # Parse arguments
        args = parser.parse_args()
        
        # Ejecutar tareas necesarias para entrenamiento
        train(args.arg_1, args.arg_2)
        ...

# Descripción authorization

El despliegue automático de modelos de machine learning en GCP requiere conocer algunos parámetros de ejecución del entorno: el id del proyecto, token de acceso, nombre del bucket en donde se alojan los datos.
Para obtener esta información es necesario disponer de un entorno que tenga instalado ciertas herramientas de Google. Es por ello que se monta este componente sobre un contenedor que proporciona Google que contiene pre-instalado sus SDK y CLI sin necesidad de tener que instalar de manera manual cada una de estas herramientas.

El componente Authorization se encarga de obtener los tres (3) parámetros de ejecución los cuales fueron nombrados como: TOKEN, PROJECT_ID, BUCKET_NAME.

# Descripción Training

Este componente es el encargado de clonar un repositorio, leer el archivo de configuración que contiene el repositorio y el archivo de entrenamiento train.py, en conjunto permiten generar un una tarea (job) en AI Platfom de entrenamiento:

gcloud ai-platform jobs submit training {JOB_NAME} \
         --module-name={PYTHON_MODULE} \
         --package-path=./{PACKAGE_PATH} \
         --staging-bucket={BUCKET_NAME} \
         --region={REGION} \
         --scale-tier={TIER} \
         --master-machine-type={training_input["MACHINE"]} \
         --python-version={PYTHON_VERSION} \
         --runtime-version={RUNTIME_VERSION} \
         -- \
         --storage-path={BUCKET_NAME}{JOB_NAME} \
         {TRAINING_ARGS} 

Este componente luego comenzar la ejecución de ese job, retorna los siguientes datos:

* gs_bucket_model : Corresponde a la ubicación del Google storge donde quedará alojado el modelo, es equivalente a --storage-path.
* framework : Corresponde al framework usado para entrenar el modelo, solo puede tomar valores acotados.
* WAITING_TIME_MIN : Corresponde al tiempo en minutos que espera el módulo de versionado para subir el modelo, debe esperar a que el modelo haya sido entrenado y subido al bucket de storage por el job de entrenamiento.

El componente entero es ejecutado dentro de un docker [cloud-sdk:alpine](https://gcr.io/google.com/cloudsdktool/cloud-sdk:alpine) el cual tiene instalado el SDK Cloud de GCP, esto permite utilizar el comando gcloud para mandar a ejecutar el Job.

En esta versión de la demostración, es necesario que el archivo de entrenamiento train.py, se encargue de traer los datos necesarios para entrenar y luego de subir el modelo al storage pasado como parámetro, esto se debe a que el entorno de ejecución del entrenamiento (el Job) es un entorno totalmente independiente, por tanto, lo datos de entrenamiento deben ser traídos al entorno local del Job para poder entrenar y generar el modelo que luego es subido.

## Git integration

La integración con repositorios de código nos permite separar la parte de ciencia de datos con la parte de operación.

El componente "Training" genera esta integración la cual permite, con la misma pipeline, dispinibilizar distintos tipos de modelos tan sólo con pasar este repositorio en GIT en modo sólo lectura.

El código presente en el repositorio debe generar el entrenamiento con uno de los siguientes frameworks:
- Tensorflow (sin keras)
- Scikit-learn
- xgboost

Respecto al requerimiento de que el entrenamiento con Tensorflow se genere sin keras es por el tipo de modelo que genera (con extensión.h5). GCP actualmente (noviembre, 2020) sólo soporta modelos de los tres (3) frameworks mencionados anteriormente.

Si se requiere entrenar con algún otro framework, es necesario construir también la función de predicción y decirle a Google cómo proceder. Eso se escapa de los alcances de este documento y el diseño de esta pipeline en kubeflow pero es necesario tenerlo en cuenta en caso de que se requiera algo de ese estilo.

# Descripción Serving

Luego que el modelo ha sido entrenado de manera exitosa y subido a cloud storage, es necesario dejarlo disponible para su consumo. AI Platform dispone de una sección en donde se pueden implementar estos modelos y se encarga de su correcto versionamiento.

Para realizar la acción del serving se crearon dos componentes:

* Create Model
* Create Version

## Descripción Create Model

Con el componente "Create model" se permite preparar el entorno en dónde estará alojado el modelo que permite generar una predicción, en caso del que el entorno no exista, y luego definir la versión del modelo. Para definir cuál es la versión del modelo que se debe crear, primero lista las versiones del modelo que hay actualmente creados y le suma 1 a la siguiente versión.

Las entradas al componente son las siguientes:

| Nombre Dato | Tipo | Origen |
| -------------- | ------------- | ----------------------- |
| model_name | str | Arg. de la Pipeline |
| TOKEN | InputPath | Comp. Authorization |
| PROJECT_ID | InputPath | Comp. Authorization |

## Descripción Version Model

Este componente recibe como entrada los siguientes parámetros:

| Nombre Dato | Tipo | Origen |
| -------- | -------- | -------- |
| model_name | str | Arg. de la Pipeline |
| waiting_time_min | int | Comp. Training |
| model_version | str | Comp. Create Model |
| framework | str | Comp. Training |
| gs_bucket_model | str | Comp. Training |
| TOKEN | InputPath(str) | Comp. Authorization |
| PROJECT_ID | InputPath(str) | Comp. Authorization |

Lo primero que hace es verificar la existencia en el bucket de alguno de estos archivos:
* **model.joblib**

En caso de no existir continúa esperando y consultado la existencia por *waiting_time_min* minutos, cuando el archivo existen en el bucket se leen las credenciales (Token) de autentificación y se envía un job de creación de versión de modelo, al versionar un modelo queda disponible para ser luego consultado vía API.

# API Request

Para poder hacer una petición a la API es necesario conocer cuáles son los atributos del modelo. Estos son:
- id del proyecto
- región en donde se ubica el modelo
- nombre del modelo
- nombre de la versión de modelo
- arreglo de _features_

El arreglo de _features_ debe tener la siguiente estructura:

{
    "instances": [
        [<arreglo 1>],
        [<arreglo 2>],
        ...,
        [<arreglo n>]
    ]
}

La API retornará la siguiente estructura:

{
  "predictions": [
    <response 1>,
    <response 1>,
    ...,
    <response n>
  ]
}

## Por ejemplo:

{
    "instances": [
        [57, "technician", "married", "high.school", "no", 
        "no", "yes", "cellular", "may", "mon", 371, 1, 999, 1, 
        "failure", -1.8, 92.893, -46.2, 1.2990000000000002, 
        5099.1],
        [21, "technician", "married", "high.school", "no", 
        "no", "yes", "cellular", "may", "mon", 371, 1, 5, 1, 
        "failure", -6.8, 12.893, -4.2, 5.2990000000000002, 
        53.1]
    ]
}

Para el modelo que ha sido desplegado la respuesta es la siguiente

{
  "predictions": [
    1,
    1
  ]
}

GCP nos provee de pruebas rápidas para su API. Estos valores fueron rescatado de la sección de "probar y usar" que tiene cada versión del modelo


# Resumen final

Esta solución es un primer paso en el uso y orquestación de herramientas de AI Platform junto con herramientas como GIT y Kubeflow, que buscan automatizar trabajo característico y frecuente de los equipos de Machine Learning, como lo es el entrenamiento y despliegue de modelos.

La incorporación de prácticas de estandarización de los procesos, en este caso del entrenamiento y despliegue, buscan facilitar y mejorar los tiempos de delivery de los equipos ligados al área de Machine Learning o Data Science, trayendo consigo una disminución en el re-trabajo, al utilizar componentes prefabricados de uso común en todos los proyectos de este tipo.

Uno de los grandes desafíos que debe ser superado en el área de ML, es lograr llevar modelos a entornos productivos (más allá de la PoC), en este sentido poder iterar rápido en el entrenamiento y despliegue de modelos, usando buenas prácticas de MLOps, como el versionado de los datos en conjunto con el código, son piezas fundamentales en cualquier equipo de Machine Learning.

# Pasos a seguir

- **Personalizar predicción**: Hay modelos que requieres de un tratamiento distinto de su predicción. Un caso podría ser redes neuronales con keras, para la cual la plataforma no da soporte actualmente de manera nativa, [Custom prediction routines](https://cloud.google.com/ai-platform/prediction/docs/custom-prediction-routines#deploy_your_custom_prediction_routine).
- **Obtener métricas dentro de kubeflow**: al hacer entrenamientos dentro de kubeflow es posible graficar métricas entre un componente y otro. Queda pendiente poder replicar algo similar a lo que se puede obtener con Tensorboard, [Visualize Results in the Pipelines UI](https://www.kubeflow.org/docs/pipelines/sdk/output-viewer/).

# Fuentes

- [Training a model on Google’s AI Platform](https://towardsdatascience.com/training-a-model-on-google-ai-platform-84ceff87b5f3)

- [Running a training job](https://cloud.google.com/ai-platform/training/docs/training-jobs#gcloud)

- [Kubeflow on GCP](https://www.kubeflow.org/docs/gke/)

- [Distributed Machine Learning with Google Cloud ML](https://www.qwiklabs.com/focuses/3389?parent=catalog) or [Source](https://matematika.org/clouds/google/qwiklabs/data-science-on-google-cloud-platform-machine-learning/distributed-machine-learning-with-google-cloud-ml/)

- [Deploying models](https://cloud.google.com/ai-platform/prediction/docs/deploying-models)

- [MLOps: Continuous delivery and automation pipelines in machine learning](https://cloud.google.com/solutions/machine-learning/mlops-continuous-delivery-and-automation-pipelines-in-machine-learning?hl=es-419)

---

# Contacto

#### everis centers Temuco - Chile:

- [e-mail] :surfer: :sunglasses:

##### Autores:

- [e-mail] :musical_score: :microphone:
- [e-mail] :male-scientist: :medal:

---