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 en un depósito de Cloud Storage al que se pueda acceder con tu proyecto de Google Cloud Platform. 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 Cloud ML Engine 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:

  • Usa la herramienta gcloud (recomendado) o codifica tu propia solución.
  • Compila tu paquete manualmente si es necesario.
  • Incluye dependencias adicionales que no estén instaladas por el entorno de ejecución de Cloud ML Engine que estés usando.

    La forma más sencilla de empaquetar tu aplicación y subirla junto con tus dependencias es usar la herramienta gcloud. Usa el mismo comando (gcloud ml-engine jobs submit training) a fin empaquetar y subir la aplicación y para 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"
    

    El siguiente ejemplo muestra un comando gcloud ml-engine jobs submit training con el que se 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
    
    • Con --staging-bucket se especifica la ubicación de Cloud Storage donde deseas habilitar la etapa tu entrenamiento y 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 Cloud ML Engine. Si no especificas un depósito de etapa de pruebas, en Cloud ML Engine se organizan 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 Cloud ML Engine.

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

    • 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), entonces el nombre del módulo es trainer.task.

    • Si especificas una opción tanto en tu archivo de configuración (config.yaml) como en una marca de la 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 deseas pasar a tu aplicación.
    • Las marcas específicas para Cloud ML Engine, como --module-name, --runtime-version y --job-dir deben aparecer antes de la marca vacía --. El servicio de Cloud ML Engine interpreta estas marcas.
    • La marca --job-dir, si se especifica, debe aparecer antes de la marca vacía --, debido a que Cloud ML Engine usa --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. Cloud ML Engine pasa --user_first_arg, --user_second_arg, y así sucesivamente, mediante 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 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 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. Cloud ML Engine usa pip para instalar tu paquete en las instancias de entrenamiento que asigna a tu trabajo. Se buscan dependencias configuradas y se instalan con el comando pip install.

    Crea un archivo llamado setup.py en el directorio raíz de tu aplicación (un directorio arriba de tu directorio de 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. Se usa pip install en Cloud Engine para instalar dependencias personalizadas, así, estas pueden tener dependencias estándar propias en sus secuencias de comandos setup.py.

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

    • Configura la marca 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.

    • Establece la marca --packages para incluir las dependencias en una lista separada por comas.

    Cada URI que incluyas es la ruta a un paquete, con formato de un archivo comprimido (*.tar.gz) o como una rueda. 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 (uno de cada uno de los tipos de paquetes compatibles) 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 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 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 capacitación con la API de Cloud ML directamente, debes configurar 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 de 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 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 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_ configurados como find_packages().

        • _include_package_data_ configurados como True.

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

    Estructura del proyecto recomendada

    Puedes estructurar tu aplicación de entrenamiento como desees. 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 las muestras.

    • Usa un directorio principal del proyecto con 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 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 Cloud ML Engine, el directorio del trainer generalmente contiene los siguientes archivos de origen:

    • task.py contiene la lógica de la aplicación con la que se 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.

    Si usas la herramienta gcloud para empaquetar tu aplicación, no necesitas crear un setup.py o ningún archivo __init__.py. Cuando ejecutas gcloud ml-engine jobs submit training, puedes establecer la marca --package_path en la ruta de tu directorio principal del proyecto o puedes ejecutar la herramienta desde ese directorio y omitir la marca 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. En el servicio de capacitación, se ejecuta ese módulo cuando se invoca a Python, del mismo modo que lo ejecutarías de forma local.

    Cuando conviertes tu aplicación en un paquete de Python, creas un espacio de nombres. Por ejemplo, si creas un paquete que se llama trainer y tu módulo principal se llama task.py, especificas ese paquete con el nombre trainer.task. Por lo tanto, cuando ejecutes gcloud ml-engine jobs submit training, configura la marca --module-name con 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 compilaste tu paquete, puedes subirlo con la herramienta gcloud. Ejecuta el comando gcloud ml-engine 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), entonces el nombre del módulo es 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 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 gcloud para usar un paquete existente que ya está en la nube

    Si compilaste tu paquete y lo subiste a una ubicación de Cloud Storage, puedes subirlo con gcloud. Ejecuta el comando gcloud ml-engine 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), entonces el nombre del módulo es 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 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 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. La razón más común es que deseas llamar directamente a la API de Cloud Engine 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 a fin de subir tus paquetes como parte 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.

    ¿Qué sigue?

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

Enviar comentarios sobre…

Cloud ML Engine para TensorFlow