Empaqueta una aplicación de entrenamiento

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

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

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. Sigue la guía para configurar un depósito de Cloud Storage donde puedas almacenar los datos y archivos de tu aplicación de entrenamiento.

  3. 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 tu aplicación y la subes a Cloud Storage:

  • Uso de la herramienta gcloud (recomendado) o codificación de tu propia solución.
  • Compilación manual de tu paquete, si es necesario.
  • Cómo incluir dependencias adicionales que no se instalan con el entorno de ejecución de AI Platform que estás utilizando.

La forma más sencilla de empaquetar tu aplicación y subirla junto con tus dependencias es usar la herramienta gcloud. Utiliza un solo comando (gcloud ai-platform jobs submit training) a fin de 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 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, con las siguientes variables se definen los valores usados cuando ejecutas 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 ai-platform jobs submit training que empaqueta una aplicación y envía el trabajo de entrenamiento:

gcloud ai-platform 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
  • Con --staging-bucket, se especifica la ubicación de Cloud Storage donde deseas habilitar a etapa tu entrenamiento y los paquetes de dependencia. Tu proyecto de GCP debe tener acceso a este depósito de Cloud Storage y el depósito debe estar en la misma región en la que ejecutas el trabajo. Consulta las regiones disponibles para los servicios de AI Platform. Si no especificas un depósito de etapa de pruebas, AI Platform organiza tus paquetes en la ubicación especificada en el parámetro job-dir.

  • Con --job-dir, se 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 y el depósito debe estar en la misma región en la que ejecutas el trabajo. Consulta las regiones disponibles para los servicios de AI Platform.

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

    Si no hay un archivo setup.py en la ubicación esperada, la herramienta gcloud crea un sencillo archivo setup.py temporal y solo incluye el directorio que especifica --package-path en el archivo .tar.gz que compila.

  • Con --module-name, se especifica el nombre del módulo principal de tu aplicación con la notación de puntos del espacio de nombres de tu paquete. Este es el archivo de Python que ejecutas para iniciar tu 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 una marca de línea de comandos, el valor en la línea de comandos anula el valor del 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 deseas pasar a tu aplicación.
  • Las marcas específicas de AI Platform, como --module-name, --runtime-version y --job-dir, deben aparecer antes de la marca -- vacía. El servicio de AI Platform interpreta estas marcas.
  • La marca --job-dir, si se especifica, debe ir antes que la marca -- vacía, ya que AI Platform usa el --job-dir para validar la ruta.
  • Tu aplicación también debe controlar la marca --job-dir, si se especifica. Aunque la marca aparece antes del -- vacío, el --job-dir también se pasa a tu aplicación como marca de la línea de comandos.
  • Puedes definir tantos USER_ARGS como necesites. AI Platform le pasa --user_first_arg, --user_second_arg, y así sucesivamente, a tu aplicación.

Puedes encontrar 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, este 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 de entorno de ejecución que usas para el entrenamiento y verifica 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 tu secuencia de comandos setup.py. AI Platform usa pip para instalar tu paquete en las instancias de entrenamiento que asigna a 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 cuando insertes 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 a fin de enviar tu trabajo de entrenamiento, automáticamente se usa tu archivo setup.py para crear el paquete.

Si envías el trabajo de entrenamiento sin usar gcloud, utiliza 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 cuando pases sus rutas como parte de la configuración de tu trabajo. Necesitas la URI para el paquete de cada dependencia. Las dependencias personalizadas deben estar en una ubicación de Cloud Storage. AI Platform 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 dependencias en tu máquina local, así como en Cloud Storage, y la herramienta las ubicará en la nube para ti: cuando 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 instala cada paquete con pip install en cada máquina virtual que asigna a tu trabajo de entrenamiento.

En el ejemplo a continuación, se especifican las dependencias empaquetadas llamadas dep1.tar.gz y dep2.whl (uno de cada uno de los tipos de paquetes compatibles) junto con una ruta 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 $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 forma similar, el ejemplo a continuación especifica las dependencias empaquetadas llamadas dep1.tar.gz y dep2.whl (uno de cada uno de los tipos de paquetes admitidos), pero con una aplicación de entrenamiento compilada:

gcloud ai-platform 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 AI Platform Training and Prediction directamente, debes configurar tus 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. 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, se incluye un archivo llamado __init__.py, que puede estar vacío o puede contener un 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 tu paquete de distribución .tar.gz (un directorio por encima de tu directorio trainer, si sigues el patrón recomendado), incluye el archivo de Setuptools llamado setup.py que incluye los siguientes elementos:

    • Importa declaraciones para setuptools.find_packages y setuptools.setup.

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

      • _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 tu aplicación requiere, 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 similares a from trainer import util) dentro de tu "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 comúnmente en las muestras de AI Platform, y el hecho de que la organización de tu proyecto sea similar a las muestras puede facilitar el seguimiento de las muestras.

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

    Utiliza la función find_packages() desde setuptools en tu 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.

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

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

  • Crea un archivo __init__.py en cada subdirectorio. Estos archivos se usan en Setuptools a fin de identificar directorios con código para empaquetar y podrían estar vacíos.

En las muestras de AI Platform, el directorio del 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 contiene el código de grafo TensorFlow: 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 en trainer. Esto hace que la herramienta de gcloud busque un archivo setup.py en el directorio superior de trainer, el directorio de tu proyecto principal.

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, tu módulo principal es task.py. Dado que se encuentra dentro de un paquete de importación (directorio con un archivo __init__.py) llamado trainer, el nombre completo de este módulo es trainer.task. Por lo tanto, si envías tu trabajo con gcloud ai-platform jobs submit training, configura tu 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 la herramienta gcloud para subir un paquete existente

Si compilas el paquete por tu cuenta, puedes subirlo con la herramienta gcloud. Ejecute el comando gcloud ai-platform jobs submit training:

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

  • Configura la marca --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. Este es el archivo de Python que ejecutas para iniciar tu 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 comprimido tarball (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 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 $MAIN_TRAINER_MODULE \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Usa la herramienta gcloud 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. Ejecute el comando gcloud ai-platform jobs submit training:

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

  • Configura la marca --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. Este es el archivo de Python que ejecutas para iniciar tu 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 de tarball comprimido que se encuentra en un depósito de Cloud Storage:

gcloud ai-platform 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 está en la nube. Por ejemplo, la ruta podría apuntar a la siguiente ubicación de Cloud Storage que contiene un paquete comprimido de tarball 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 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 and Prediction para iniciar el 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 ai-platform jobs submit training a 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 de manera programática.

Pasos siguientes

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

Enviar comentarios sobre…

Cloud ML Engine para TensorFlow