Empaqueta una aplicación de entrenamiento

Antes de ejecutar tu aplicación de entrenamiento con AI Platform Training, debes subir el código y las dependencias a un bucket de Cloud Storage al que pueda acceder tu proyecto de Google Cloud. En esta página, se muestra cómo empaquetar y configurar tu aplicación en la nube.

Obtendrás los mejores resultados si pruebas la aplicación de entrenamiento de forma local antes de subirla a la nube. El entrenamiento con AI Platform Training genera cargos en tu cuenta por los recursos que se usaron.

Antes de comenzar

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

  1. Configura el entorno de desarrollo, como se describe en la guía de introducción.

  2. Desarrolla la aplicación de entrenamiento con uno de los frameworks de aprendizaje automático alojados de AI Platform Training: TensorFlow, scikit-learn o XGBoost. De manera alternativa, crea un contenedor personalizado para personalizar el entorno de tu aplicación de entrenamiento. Esto te brinda la opción de usar frameworks de aprendizaje automático distintos de los alojados de AI Platform Training.

    Si deseas implementar el modelo entrenado en AI Platform Prediction después del entrenamiento, consulta la guía para exportar el modelo de predicción a fin de asegurarte de que el paquete de entrenamiento exporte los artefactos de modelo que AI Platform Prediction puede usar.

  3. Sigue la guía para configurar un depósito de Cloud Storage en el que puedas almacenar los archivos y datos de la aplicación de entrenamiento.

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

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

  • Uso de la CLI de gcloud (recomendado) o codificación de tu propia solución.
  • Compila tu paquete manualmente si es necesario.
  • Forma de incluir dependencias adicionales que no se instalaron mediante el entorno de ejecución de AI Platform Training que usas.

La forma más sencilla de empaquetar tu aplicación y subirla junto con sus dependencias es usar la CLI de gcloud. Usa un solo comando (gcloud ai-platform jobs submit training) para empaquetar y subir la aplicación, y enviar tu primer trabajo de entrenamiento.

Para mayor comodidad, es útil definir tus valores de configuración como variables de shell.

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

Reemplaza lo siguiente:

  • LOCAL_PACKAGE_PATH: La ruta de acceso al directorio de tu paquete de Python en el entorno local.
  • MODULE_NAME: El nombre completo de tu módulo de entrenamiento.
  • BUCKET_NAME: El nombre de un depósito de Cloud Storage.
  • JOB_NAME: Un nombre para tu trabajo de entrenamiento.
  • JOB_OUTPUT_PATH: El URI de un directorio de Cloud Storage en el que deseas que tu trabajo de entrenamiento guarde su resultado.
  • REGION: La región en la que deseas ejecutar tu trabajo de entrenamiento.

Consulta más detalles sobre los requisitos de estos valores en la lista después del siguiente comando.

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

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

  • --staging-bucket especifica un bucket de Cloud Storage en el que deseas almacenar en etapa intermedia los paquetes de dependencia y entrenamiento. El proyecto de Google Cloud debe tener acceso a este bucket de Cloud Storage, y el bucket debe estar en la misma región en la que ejecutas el trabajo. Consulta las regiones disponibles para los servicios de AI Platform Training. Si no especificas un bucket de etapa de pruebas, AI Platform Training almacena los paquetes en etapa intermedia en la ubicación que se especifica en el parámetro job-dir.

  • --job-dir especifica la ubicación de Cloud Storage que deseas usar para los archivos de salida del trabajo de entrenamiento. El proyecto de Google Cloud debe tener acceso a este bucket de Cloud Storage, y el bucket debe estar en la misma región en la que ejecutas el trabajo. Consulta las regiones disponibles para los servicios de AI Platform Training.

  • --package-path especifica la ruta de acceso local al directorio de la aplicación. La CLI de gcloud compila un paquete de distribución .tar.gz desde tu código según el archivo setup.py en el directorio superior que especifica --package-path. Luego, sube este archivo .tar.gz a Cloud Storage y lo usa para ejecutar el trabajo de entrenamiento.

    Si no hay ningún archivo setup.py en la ubicación esperada, la CLI de gcloud crea un setup.py sencillo y temporal, y agrega solo el directorio que especificó --package-path en el archivo .tar.gz que compila.

  • --module-name especifica el nombre del módulo principal de la aplicación mediante la notación de puntos del espacio de nombres de tu paquete. Este es el archivo de Python que ejecutas para iniciar la aplicación. Por ejemplo, si el 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 en el archivo de configuración (config.yaml) y como una marca de línea de comandos, el valor en la línea de comandos anula el valor en el archivo de configuración.
  • La marca vacía -- indica el final de las marcas específicas de gcloud y el inicio de los USER_ARGS que quieres pasar a la aplicación.
  • Las marcas específicas de AI Platform Training, como --module-name, --runtime-version y --job-dir, deben aparecer antes de la marca vacía --. El servicio AI Platform Training interpreta estas marcas.
  • Si se especifica la marca --job-dir, debe aparecer antes de la marca vacía --, ya que AI Platform Training usa --job-dir para validar la ruta de acceso.
  • La aplicación también debe controlar la marca --job-dir, si se especifica. Aunque la marca aparezca antes de la -- vacía, --job-dir también se pasa a tu aplicación como una marca de línea de comandos.
  • Puedes definir tantos USER_ARGS como necesites. AI Platform Training pasa --user_first_arg, --user_second_arg, etc. a la aplicación.

Obtén más información sobre las marcas de envío de trabajos en la guía para ejecutar un trabajo de entrenamiento.

Trabaja con dependencias

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

Cuando ejecutas un trabajo de entrenamiento en AI Platform Training, este se ejecuta en instancias de entrenamiento (máquinas virtuales configuradas de forma especial) 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, también, si alguna de tus dependencias aún no está instalada.

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 paquetes que tú mismo desarrollaste o aquellos internos de una organización.

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

Agrega dependencias estándar (PyPI)

Puedes especificar las dependencias estándar de tu paquete como parte de su secuencia de comandos setup.py. AI Platform Training usa pip a fin de instalar el 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 la aplicación (si sigues el patrón recomendado, debe estar un nivel arriba del directorio trainer).

Ingresa la siguiente secuencia de comandos en setup.py y agrega 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 Google Cloud CLI para enviar el trabajo de entrenamiento, estas herramientas usarán de forma automática el archivo setup.py a fin de crear el paquete.

Si envías el trabajo de entrenamiento sin usar gcloud, emplea 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 la aplicación de entrenamiento.

Agrega dependencias personalizadas

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

Si usas la CLI de gcloud para ejecutar tu trabajo de entrenamiento, puedes especificar dependencias en tu máquina local y en Cloud Storage. La herramienta las almacenará en etapa intermedia en la nube por ti. Si ejecutas el comando gcloud ai-platform jobs submit training, configura la marca --packages para incluir las dependencias en una lista separada por comas.

Cada URI que incluyas es la ruta de acceso a un paquete de distribución, con formato de archivo tarball (.tar.gz) o como una rueda (.whl). AI Platform Training instala cada paquete con pip install en cada máquina virtual que asigna a tu trabajo de entrenamiento.

En el siguiente ejemplo, se especifican las dependencias empaquetadas llamadas dep1.tar.gz y dep2.whl (una de cada uno de los tipos de paquetes compatibles) junto con una ruta de acceso a las fuentes de la aplicación:

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

De forma similar, el ejemplo que se encuentra a continuación especifica las dependencias empaquetadas llamadas dep1.tar.gz y dep2.whl (una de cada uno de los tipos de paquetes compatibles), pero con una aplicación de entrenamiento compilada:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --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 mediante la API de AI Platform Training y la de Prediction directamente, debes almacenar en etapa intermedia los paquetes de dependencia en una ubicación de Cloud Storage y, luego, usar las rutas de acceso 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 a fin de compilar tu paquete. Existen otras bibliotecas que puedes usar para hacer lo mismo.

Sigue estos pasos para compilar el paquete de forma manual:

  1. En cada directorio del paquete de aplicación, se 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 superior que contiene el código completo que deseas incluir en el paquete de distribución .tar.gz (si sigues el patrón recomendado, debe estar un nivel arriba del directorio trainer), incluye el archivo Setuptools denominado setup.py que incluye los siguientes elementos:

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

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

      • _name_ configurado como el nombre del espacio de nombres de tu paquete

      • _version_ configurado como el número de versión de esta compilación de tu paquete

      • _install_requires_ configurado como una lista de paquetes que requiere la aplicación, con requisitos de versión, como 'docutils>=0.3'

      • _packages_ configurado como find_packages() Esto le indica a Setuptools que incluya todos los subdirectorios del directorio superior que contengan un archivo __init__.py como “paquetes de importación” (los módulos se importan desde estos paquetes en Python con declaraciones como from trainer import util) dentro del “paquete de distribución” (el archivo `.tar.gz que contiene todo el código)

      • _include_package_data_ configurado como True

  3. Ejecuta python setup.py sdist para crear tu paquete de distribución .tar.gz.

Estructura de proyecto recomendada

Puedes estructurar tu aplicación de entrenamiento como desees. Sin embargo, la siguiente estructura se usa con frecuencia en las muestras de AI Platform Training, y el hecho de que la organización del proyecto sea similar a las muestras puede facilitar el seguimiento de las muestras.

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

    Usa la función find_packages() de setuptools en el archivo setup.py para garantizar que todos los subdirectorios se incluyan en el paquete de distribución .tar.gz que compiles.

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

  • Asigna el nombre task.py al módulo de aplicación principal.

  • Crea cualquier otro subdirectorio en el directorio principal del proyecto que necesites para implementar la aplicación.

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

En las muestras de AI Platform Training, el directorio trainer, por lo general, contiene los siguientes archivos de origen:

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

  • model.py contiene la lógica del modelo.

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

Estructura recomendada de un proyecto de aplicación de entrenamiento

Cuando ejecutes gcloud ai-platform jobs submit training, configura --package-path como trainer. Esto hace que la CLI de gcloud busque un archivo setup.py en el superior de trainer, el directorio principal del proyecto.

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 mediante una invocación a Python, del mismo modo que cuando se lo ejecuta de forma local.

Por ejemplo, si sigues la estructura recomendada de la sección anterior, el módulo principal será task.py. Dado que se encuentra dentro de un paquete de importación (directorio con un archivo __init__.py) llamado trainer, el nombre completamente calificado de este módulo será trainer.task. Por lo tanto, si envías el trabajo mediante gcloud ai-platform jobs submit training, configura la marca --module-name como trainer.task.

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

Usa gcloud CLI para subir un paquete existente

Si compilas el paquete por tu cuenta, puedes subirlo con la CLI de gcloud. Ejecuta el comando gcloud ai-platform jobs submit training.

  • Configura la marca --packages en la ruta a tu aplicación empaquetada.

  • Establece la marca --module-name en el nombre del módulo principal de la aplicación mediante la notación de puntos del espacio de nombres del paquete. Este es el archivo de Python que ejecutas para iniciar la aplicación. Por ejemplo, si el 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 de archivo comprimido (aquí llamado trainer-0.0.1.tar.gz) que se encuentra en el mismo directorio en el que ejecutas el comando. La función principal se encuentra en un módulo llamado task.py:

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

Usa gcloud CLI para usar un paquete existente que ya está en la nube

Si compilas el paquete por tu cuenta y lo subes a una ubicación de Cloud Storage, puedes subirlo con gcloud. Ejecuta el comando gcloud ai-platform jobs submit training:

  • Configura la marca --packages en la ruta a tu aplicación empaquetada.

  • Establece la marca --module-name en el nombre del módulo principal de la aplicación mediante la notación de puntos del espacio de nombres del paquete. Este es el archivo de Python que ejecutas para iniciar la aplicación. Por ejemplo, si el 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 de archivo comprimido que se encuentra en un bucket de Cloud Storage:

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

En el ejemplo anterior, $PATH_TO_PACKAGED_TRAINER es una variable de entorno que representa la ruta de acceso 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 de archivo 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 de forma manual

Puedes subir tus paquetes manualmente si tienes una razón para hacerlo. A menudo, esto se hace cuando se desea llamar directamente a la API de AI Platform Training y a la de Prediction para iniciar el trabajo de entrenamiento. La manera más sencilla de subir de forma manual el paquete y las dependencias personalizadas al bucket de Cloud Storage es usar la herramienta de comandos gcloud storage:

gcloud storage 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 ai-platform jobs submit training a fin de subir los 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 de manera programática.

Pasos siguientes

Siguiente
Ejecuta un trabajo de entrenamiento