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:
- Configura el entorno de desarrollo, como se describe en la guía de introducción.
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.
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.
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.
Usa gcloud
para empaquetar y subir tu aplicación (recomendado)
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ámetrojob-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 archivosetup.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 unsetup.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 degcloud
y el inicio de losUSER_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:
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).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 directoriotrainer
), incluye el archivo Setuptools denominadosetup.py
que incluye los siguientes elementos:Declaraciones de importación de
setuptools.find_packages
ysetuptools.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 comofind_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 comofrom trainer import util
) dentro del “paquete de distribución” (el archivo `.tar.gz que contiene todo el código)_include_package_data
_ configurado comoTrue
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()
desetuptools
en el archivosetup.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.
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
- Configura y ejecuta un trabajo de entrenamiento.
- Supervisa tu trabajo de entrenamiento mientras se ejecuta.
- Obtén más información sobre cómo funciona el entrenamiento.