Empaqueta una aplicación de entrenamiento

Antes de que puedas ejecutar tu aplicación de entrenamiento con Cloud Machine Learning Engine, debes subir tu código y cualquier dependencia a un depósito de Cloud Storage al que tenga acceso tu proyecto de Google Cloud Platform. En esta página, se muestra cómo empaquetar y llevar a cabo la etapa de pruebas en tu aplicación en la nube.

Obtendrás los mejores resultados si pruebas tu aplicación de entrenamiento de manera local antes de subirla a la nube. El entrenamiento con Cloud ML Engine genera cargos en tu cuenta por los recursos utilizados.

Antes de comenzar

Antes de poder mover tu aplicación de entrenamiento a la nube, debes completar los siguientes pasos:

  1. Configura tu entorno de desarrollo, como se describe en la guía de introducción.
  2. Desarrolla tu aplicación de entrenamiento con scikit-learn o XGBoost.
  3. Sigue la guía para configurar un depósito de Cloud Storage donde puedas almacenar los datos y los archivos de tu aplicación de entrenamiento.

  4. Conoce todas las bibliotecas de Python de las que depende tu aplicación de entrenamiento, ya sea que contengan paquetes personalizados o que estén disponibles de manera gratuita a través de PyPI.

En este documento, se analizan los siguientes factores que influyen en la forma en que empaquetas tu aplicación y la subes a Cloud Storage:

  • Uso de la herramienta de gcloud (recomendado) o codificación de tu propia solución.
  • Compilación manual del paquete, de ser necesario.
  • Forma de incluir dependencias adicionales que el entorno de ejecución de Cloud ML Engine que estás utilizando no haya instalado.
  • Consideraciones para nombrar los archivos de modelo a fin de lograr una predicción en línea después de haber ejecutado tu trabajo de entrenamiento.

Nomenclatura de los archivos de modelo para uso con predicción en línea

Si deseas usar Cloud ML Engine para obtener predicciones en línea después del entrenamiento, debes asignar un nombre a tu archivo de modelo según la biblioteca que usas para exportarlo. Consulta la siguiente información, si deseas obtener detalles sobre los requisitos de nomenclatura para tu archivo de modelo.

Establece el nombre de tu archivo de modelo en el código de entrenamiento principal antes de empaquetar tu aplicación de entrenamiento y enviar el trabajo de entrenamiento a Cloud ML Engine:

scikit-learn

Para exportar tu modelo, puedes usar joblib o la biblioteca pickle de Python:

joblib

# Export the model to a file
joblib.dump(pipeline, 'model.joblib')

pickle

# Export the model to a file
with open('model.pkl', 'wb') as model_file:
  pickle.dump(pipeline, model_file)

XGBoost

Para exportar tu modelo, puedes usar el método save_model del objeto Booster o la biblioteca pickle de Python.

# load data into DMatrix object
dtrain = xgb.DMatrix(train_features, train_labels)
dtest = xgb.DMatrix(test_features)

# train XGBoost model
bst = xgb.train({}, dtrain, 20)
bst.save_model('./model.bst')

Requisitos para nombrar los archivos de modelo

El archivo de modelo guardado que subes a Cloud Storage debe nombrarse model.pkl, model.joblib o model.bst, según la biblioteca que usaste. Esta restricción garantiza que, para reconstruir el modelo en la importación, Cloud ML Engine use el mismo diseño que se usó durante la exportación.

scikit-learn

Biblioteca usada para exportar el modelo Nombre de modelo correcto
pickle model.pkl
joblib model.joblib

XGBoost

Biblioteca usada para exportar el modelo Nombre de modelo correcto
pickle model.pkl
joblib model.joblib
xgboost.Booster model.bst

En futuras iteraciones de tu modelo, organiza tu depósito de Cloud Storage para que cada modelo nuevo tenga un directorio dedicado.

La forma más sencilla de empaquetar tu aplicación y subirla junto con sus dependencias es usar la herramienta de gcloud. Usa el mismo comando (gcloud ml-engine jobs submit training) para empaquetar y subir la aplicación, y enviar tu primer trabajo de entrenamiento.

Para mayor comodidad, se recomienda definir los valores de configuración como variables de entorno. Las siguientes variables contienen valores usados para la etapa de pruebas de tu paquete de aplicación.

TRAINER_PACKAGE_PATH="/path/to/your/application/sources"
MAIN_TRAINER_MODULE="trainer.task"
PACKAGE_STAGING_PATH="gs://your/chosen/staging/path"

Además, las siguientes variables definen los valores usados cuando se ejecuta el trabajo:

now=$(date +"%Y%m%d_%H%M%S")
JOB_NAME="your_name_$now"
JOB_DIR="gs://your/chosen/job/output/path"
REGION="us-east1"

En el siguiente ejemplo, se muestra un comando gcloud ml-engine jobs submit training que empaqueta una aplicación y envía el trabajo de entrenamiento:

gcloud ml-engine jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR  \
    --package-path $TRAINER_PACKAGE_PATH \
    --module-name $MAIN_TRAINER_MODULE \
    --region $REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value
  • --staging-bucket especifica la ubicación de Cloud Storage donde deseas realizar la etapa de pruebas de tu entrenamiento y de tus paquetes de dependencia. Tu proyecto de GCP debe tener acceso a este depósito de Cloud Storage. El depósito debe estar en la misma región en la que ejecutas el trabajo. Consulta las regiones disponibles para los servicios de Cloud ML Engine. Si no especificas un depósito de etapa de pruebas, Cloud ML Engine lleva a cabo la etapa de pruebas de tus paquetes en la ubicación especificada en el parámetro job-dir.

  • --job-dir especifica la ubicación de Cloud Storage que deseas usar para los archivos de salida de tu trabajo de entrenamiento. Tu proyecto de GCP debe tener acceso a este depósito de Cloud Storage. El depósito debe estar en la misma región en la que ejecutas el trabajo. Consulta las regiones disponibles para los servicios de Cloud ML Engine.

  • --package-path especifica la ruta local al directorio raíz de tu aplicación. Consulta la estructura de proyecto recomendada.

  • --module-name especifica el nombre del módulo principal de tu aplicación con la notación de puntos del espacio de nombres de tu paquete. Se trata del archivo de Python que ejecutas para iniciar la aplicación. Por ejemplo, si tu módulo principal es .../my_application/trainer/task.py (consulta la estructura de proyecto recomendada), el nombre del módulo será trainer.task.

  • Si especificas una opción tanto en tu archivo de configuración (config.yaml) como en un marcador de línea de comandos, el valor en la línea de comandos anula el valor en el archivo de configuración.
  • El marcador -- vacío indica el final de los marcadores específicos de gcloud y el inicio de los USER_ARGS que deseas pasar a tu aplicación.
  • Los marcadores específicos de Cloud ML Engine, como --module-name, --runtime-version, y --job-dir, deben aparecer antes del marcador -- vacío. El servicio de Cloud ML Engine interpreta estos marcadores.
  • El marcador --job-dir, si se especifica, debe aparecer antes del marcador -- vacío porque Cloud ML Engine usa --job-dir para validar la ruta de acceso.
  • Tu aplicación también debe controlar el marcador --job-dir, si se especifica. Aunque el marcador aparezca antes del marcador -- vacío, --job-dir también se pasa a tu aplicación como un marcador de línea de comandos.
  • Puedes definir tantos USER_ARGS como necesites. Cloud ML Engine pasa --user_first_arg, --user_second_arg, y así sucesivamente, a tu aplicación.

Puedes encontrar más información sobre los marcadores de envío de trabajos en la guía para ejecutar un trabajo de entrenamiento.

Trabaja con dependencias

Las dependencias son paquetes que tú import en tu código. Tu aplicación puede tener muchas dependencias que necesita para funcionar.

Cuando ejecutas un trabajo de entrenamiento en Cloud ML Engine, el trabajo se ejecuta en instancias de entrenamiento (máquinas virtuales especialmente configuradas) que ya tienen instalados muchos paquetes comunes de Python. Verifica los paquetes incluidos en la versión del entorno de ejecución que usas para el entrenamiento y toma nota de las dependencias que aún no estén instaladas.

Hay 2 tipos de dependencias que tal vez necesites agregar:

  • Dependencias estándar, que son paquetes comunes de Python disponibles en PyPI.
  • Paquetes personalizados, como los que tú mismo desarrollaste, o aquellos internos de una organización.

En las siguientes secciones, se describe el procedimiento para cada tipo.

Agrega dependencias (PyPI) estándar

Puedes especificar las dependencias estándar de tu paquete como parte de la secuencia de comandos setup.py. Cloud ML Engine usa pip con el fin de instalar tu paquete en las instancias de entrenamiento que asigna para tu trabajo. El comando pip install busca dependencias configuradas y las instala.

Crea un archivo llamado setup.py en el directorio raíz de tu aplicación (un directorio arriba del directorio trainer si sigues el patrón recomendado).

Ingresa la siguiente secuencia de comandos en setup.py y, luego, inserta tus propios valores:

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application package.'
)

Si usas la herramienta de línea de comandos de gcloud con el fin de enviar tu trabajo de entrenamiento, se utiliza tu archivo setup.py de forma automática para crear el paquete.

Si envías el trabajo de entrenamiento sin usar gcloud, usa el siguiente comando para ejecutar la secuencia de comandos:

python setup.py sdist

Para obtener más información, consulta la sección sobre el empaquetado manual de tu aplicación de entrenamiento.

Agrega dependencias personalizadas

Puedes especificar las dependencias personalizadas de tu aplicación pasando sus rutas como parte de la configuración de tu trabajo. Necesitas el URI del paquete de cada dependencia. Las dependencias personalizadas deben estar en una ubicación de Cloud Storage. Cloud ML Engine usa pip install para instalar dependencias personalizadas, por lo tanto, estas pueden tener dependencias estándar propias en sus secuencias de comandos setup.py.

Si usas la herramienta de gcloud para ejecutar tu trabajo de entrenamiento, puedes especificar directorios locales y la herramienta realizará la etapa de pruebas en la nube por ti. Ejecuta el comando gcloud ml-engine jobs submit training:

  • Configura el marcador package-path para especificar tu aplicación de entrenamiento, ya sea como una ruta al directorio en el que se almacena tu código fuente o como la ruta a un paquete compilado.

  • Configura el marcador --packages para incluir las dependencias en una lista separada por comas.

Cada URI que incluyas es la ruta a un paquete, formateado como tarball (*.tar.gz) o wheel. Cloud ML Engine instala cada paquete con pip install en cada máquina virtual que asigna para tu trabajo de entrenamiento.

En el ejemplo a continuación, se especifican las dependencias empaquetadas llamadas dep1.tar.gz y dep2.whl (una de cada tipo de paquete compatible) junto con una ruta a las fuentes de la aplicación:

gcloud ml-engine jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mlguy/models/faces/trainer \
    --module-name $MAIN_TRAINER_MODULE \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

De manera similar, en el ejemplo a continuación se especifican las dependencias empaquetadas llamadas dep1.tar.gz y dep2.whl (una de cada tipo de paquete compatible), pero con una aplicación de entrenamiento compilada:

gcloud ml-engine jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MAIN_TRAINER_MODULE \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Si ejecutas trabajos de entrenamiento con la API de Cloud ML Engine directamente, debes realizar la etapa de pruebas de tus paquetes de dependencia en una ubicación de Cloud Storage y, luego, usar las rutas a los paquetes en esa ubicación.

Compila tu paquete manualmente

Empaquetar el código de Python es un tema extenso que está más allá del alcance de esta documentación. Para mayor comodidad, en esta sección se proporciona una descripción general del uso de Setuptools con el fin de compilar tu paquete. Hay otras bibliotecas que puedes usar para hacer lo mismo.

Sigue estos pasos para compilar tu paquete manualmente:

  1. En cada directorio de tu paquete de aplicación, incluye un archivo llamado __init__.py, que puede estar vacío o puede contener código que se ejecuta cuando se importa ese paquete (cualquier módulo en ese directorio).

  2. En el directorio raíz de tu paquete (un directorio arriba de tu directorio trainer, si sigues el patrón recomendado), incluye el archivo Setuptools llamado setup.py que tiene estos elementos:

    • Declaraciones de importación para setuptools.find_packages y setuptools.setup.

    • Una llamada a setuptools.setup con (como mínimo) los siguientes parámetros configurados:

      • _name_, configurado con el nombre del espacio de nombres de tu paquete.

      • _version_, configurado con el número de versión de esta compilación de tu paquete.

      • _install_requires_, configurado con una lista de paquetes que tu aplicación necesita y con requisitos de versión, como ‘docutils>=0.3'.

      • _packages_, configurado en find_packages().

      • _include_package_data_, configurado en True.

  3. Ejecuta python setup.py sdist para crear tu paquete.

Estructura de proyecto recomendada

Puedes estructurar tu aplicación de entrenamiento como gustes. Sin embargo, la siguiente estructura se usa comúnmente en las muestras de Cloud ML Engine; y el hecho de que la organización de tu proyecto sea similar a las muestras puede facilitar el seguimiento de estas.

  • Usa un directorio principal del proyecto que contenga tu archivo setup.py.

  • Usa un subdirectorio llamado trainer para almacenar tu módulo de aplicación principal.

  • Nombra tu módulo de aplicación principal task.py.

  • Crea, en el directorio principal de tu proyecto, otros subdirectorios que necesites para implementar tu aplicación.

  • Crea un archivo __init__.py en cada subdirectorio. Setuptools usa estos archivos con el objetivo de identificar directorios con código para empaquetar, y podrían estar vacíos.

En las muestras de Cloud ML Engine, el directorio trainer generalmente contiene los siguientes archivos de origen:

  • task.py, que contiene la lógica de la aplicación que administra el trabajo de entrenamiento.

  • model.py, que contiene el código de grafo de scikit-learn y XGBoost, la lógica del modelo.

  • util.py, si está presente, que contiene código para ejecutar la aplicación de entrenamiento.

Estructura recomendada de un proyecto de aplicación de entrenamiento.

Si usas la herramienta de gcloud para empaquetar tu aplicación, no necesitas crear un setup.py ni ningún archivo __init__.py. Cuando ejecutas gcloud ml-engine jobs submit training, puedes establecer el marcador --package_path en la ruta de tu directorio principal del proyecto, o puedes ejecutar la herramienta desde ese directorio y omitir el marcador por completo.

Módulos de Python

El paquete de tu aplicación puede contener varios módulos (archivos de Python). Debes identificar el módulo que contiene el punto de entrada de tu aplicación. El servicio de entrenamiento ejecuta ese módulo invocando Python, del mismo modo en que lo ejecutarías de manera local.

Cuando conviertes tu aplicación en un paquete de Python, creas un espacio de nombres. Por ejemplo, si creas un paquete denominado trainer, y tu módulo principal se denomina task.py, especificas ese paquete con el nombre trainer.task. Por lo tanto, cuando ejecutas gcloud ml-engine jobs submit training, configura el marcador --module-name en trainer.task.

Consulta la guía de paquetes de Python para obtener más información sobre los módulos.

Usa la herramienta de gcloud para subir un paquete existente

Si tú mismo compilas el paquete, puedes subirlo con la herramienta de gcloud. Ejecuta el comando gcloud ml-engine jobs submit training:

  • Configura el marcador --packages en la ruta de tu aplicación empaquetada.

  • Configura el marcador --module-name en el nombre del módulo principal de tu aplicación con la notación de puntos del espacio de nombres de tu paquete. Se trata del archivo de Python que ejecutas para iniciar la aplicación. Por ejemplo, si tu módulo principal es .../my_application/trainer/task.py (consulta la estructura de proyecto recomendada), el nombre del módulo será trainer.task.

En el ejemplo a continuación, se muestra cómo usar un paquete tarball comprimido (aquí llamado trainer-0.0.1.tar.gz) que se encuentra en el mismo directorio donde ejecutas el comando. La función principal está en un módulo llamado task.py:

gcloud ml-engine jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Usa la herramienta de gcloud para utilizar un paquete existente que ya esté en la nube

Si tú mismo compilas el paquete y lo subes a una ubicación de Cloud Storage, puedes subirlo con gcloud. Ejecuta el comando gcloud ml-engine jobs submit training:

  • Configura el marcador --packages en la ruta de tu aplicación empaquetada.

  • Configura el marcador --module-name en el nombre del módulo principal de tu aplicación con la notación de puntos del espacio de nombres de tu paquete. Se trata del archivo de Python que ejecutas para iniciar la aplicación. Por ejemplo, si tu módulo principal es .../my_application/trainer/task.py (consulta la estructura de proyecto recomendada), el nombre del módulo será trainer.task.

En el siguiente ejemplo, se muestra cómo usar un paquete tarball comprimido que se encuentra en un depósito de Cloud Storage:

gcloud ml-engine jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Donde $PATH_TO_PACKAGED_TRAINER es una variable de entorno que representa la ruta a un paquete existente que ya se encuentra en la nube. Por ejemplo, la ruta podría apuntar a la siguiente ubicación de Cloud Storage que contiene un paquete tarball comprimido llamado trainer-0.0.1.tar.gz:

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

Sube paquetes manualmente

Puedes subir tus paquetes de forma manual si tienes una razón para hacerlo. El motivo más común es que desees llamar a la API de Cloud ML Engine de forma directa para comenzar tu trabajo de entrenamiento. La manera más sencilla de subir manualmente tu paquete y las dependencias personalizadas a tu depósito de Cloud Storage es usar la herramienta gsutil:

gsutil cp /local/path/to/package.tar.gz  gs://bucket/path/

Sin embargo, si puedes usar la línea de comandos para esta operación, solo debes usar gcloud ml-engine jobs submit training con el fin de subir tus paquetes como parte de la configuración de un trabajo de entrenamiento. Si no puedes usar la línea de comandos, puedes usar la biblioteca cliente de Cloud Storage para subir paquetes de manera programática.

¿Qué sigue?

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Cloud ML Engine para XGBoost y scikit-learn