Crear una aplicación de entrenamiento de Python para un contenedor previamente compilado

Antes de realizar el entrenamiento personalizado con un contenedor compilado previamente, debes crear una distribución de fuente de Python que contenga tu aplicación de entrenamiento y subirla a un bucket de Cloud Storage al que pueda acceder tu proyecto de Google Cloud.

Alternativas a la creación de una distribución de origen

En esta guía, se explica cómo crear de forma manual una distribución de fuente y subirla a Cloud Storage. Antes de seguir la guía, considera los siguientes flujos de trabajo alternativos, que podrían ser más convenientes para algunos casos:

Si deseas entrenar con código en tu computadora local y reducir la cantidad de trabajo de empaquetado manual lo más posible, te recomendamos que uses la función empaquetado automático de la CLI de Google Console. Esta función te permite compilar una imagen de contenedor de Docker, enviarla a Artifact Registry y crear un recurso CustomJob basado en la imagen del contenedor, todo con un solo comando. Obtén más información en la guía para crear un CustomJob.

Para usar el empaquetado automático, debes instalar Docker en tu computadora local. Esta opción solo te permite crear un CustomJob, no un recurso TrainingPipeline o HyperparameterTuningJob. (Obtén más información sobre las diferencias entre los recursos de entrenamiento personalizados).
Para personalizar aún más la imagen de contenedor y ejecutar el código en un contenedor de forma local antes de ejecutarlo en Vertex AI, puedes usar el comando local-run de la CLI de gcloud a fin de alojar el código en contenedores y ejecutarlo de forma local. Luego, puedes enviar la imagen a Artifact Registry de forma manual.

Para usar el comando local-run, debes instalar Docker en tu computadora local.
Si puedes escribir el código de entrenamiento en una sola secuencia de comandos de Python, puedes usar la clase CustomJob del SDK de Vertex AI para Python para crear un trabajo personalizado o la clase CustomTrainingJob para crear un TrainingPipeline personalizado. El código de entrenamiento se empaqueta automáticamente como una distribución de fuente y se sube a Cloud Storage.
Para obtener la mayor flexibilidad, puedes crear una imagen de contenedor personalizada de forma manual y enviarla a Artifact Registry.

Si ninguna de las opciones anteriores se ajusta a tu caso de uso o si prefieres empaquetar tu aplicación de entrenamiento de forma manual como una distribución de origen, sigue el resto de esta guía.

Antes de comenzar

Antes de preparar tu aplicación de entrenamiento para que se ejecute en la nube, realiza los pasos que se indican a continuación:

Desarrolla la aplicación de entrenamiento con un framework de aprendizaje automático (AA) disponible en uno de los contenedores previamente compilados para el entrenamiento de Vertex AI. Asegúrate de que tu aplicación de entrenamiento cumpla con los requisitos de código de entrenamiento.

Si escribes la aplicación de entrenamiento desde cero, te recomendamos que organices el código según la estructura de la aplicación que se describe en la siguiente sección de este documento.
Crea un bucket de Cloud Storage en el mismo proyecto de Google Cloud en el que planeas usar Vertex AI. Almacenarás tu aplicación de entrenamiento en este bucket. (Aunque es posible usar un bucket en un bucket de Google Cloud diferente, esto requiere una configuración adicional que queda fuera del alcance de esta guía).

Para obtener el mejor rendimiento, asegúrate de que el bucket de Cloud Storage esté en la ubicación donde planeas usar Vertex AI.
Conoce todas las bibliotecas de Python de las que depende tu aplicación de entrenamiento, ya sean dependencias personalizados o disponibles de forma gratuita a través de PyPI.

Estructura de la aplicación

Cuando realizas un entrenamiento personalizado con un contenedor compilado previamente, debes especificar el código de entrenamiento de acuerdo con los siguientes requisitos:

Proporciona el código como una o más distribuciones de origen de Python.

Si usas la API de Vertex AI para comenzar el entrenamiento personalizado, especifícalos en el campo packageUris.
Crea un módulo en una de estas distribuciones de origen que actúa como punto de entrada para el entrenamiento.

Si usas la API de Vertex AI para iniciar el entrenamiento personalizado, especifícalo en el campo pythonModule.

Siempre que cumplas con estos requisitos, puedes estructurar tu aplicación de entrenamiento de la forma que desees. Sin embargo, recomendamos que compiles tu código fuente en la siguiente estructura (que se usa con frecuencia en las muestras de Vertex AI) para compilar una sola distribución de fuente de Python:

Usa un directorio principal del proyecto que contenga tu archivo setup.py. Consulta la siguiente sección para obtener orientación sobre el contenido de este archivo.
Dentro del directorio principal del proyecto, crea un subdirectorio llamado trainer/ que sirva como paquete principal para tu código de entrenamiento.
Dentro de trainer/, crea un módulo con el nombre task.py que sirva como punto de entrada para tu código de entrenamiento.
Para admitir trainer/task.py, crea los módulos de Python adicionales que desees en el paquete trainer/ y crea los subdirectorios adicionales con ese código adicional que desees en el directorio del proyecto principal.
Crea un archivo __init__.py en cada subdirectorio para convertirlo en un paquete.

En el resto de esta guía, se supone que tu código está organizado de acuerdo con esta estructura.

Crea una distribución de origen

Compilar distribuciones de fuentes de Python es un tema extenso que está fuera 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 una distribución de fuente para usar con Vertex AI. Existen otras bibliotecas que puedes usar para hacer lo mismo.

Crea un archivo setup.py que indique a Setuptools cómo crear la distribución de origen. Un setup.py básico incluye lo siguiente:
- 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 de la distribución de origen.
  - version configurado como el número de versión de esta compilación de tu distribución de origen.
  - install_requires configurado como una lista de dependencias que requiere la aplicación, con requisitos de versión, como 'docutils>=0.3'
  - packages está establecido en find_packages(). Esto le indica a Setuptools que incluya todos los subdirectorios del directorio superior que contengan un archivo __init__.py como paquetes.
  - include_package_data está establecido en True.
En el siguiente ejemplo, se muestra un archivo setup.py básico para una aplicación de entrenamiento:
```
from setuptools import find_packages
from setuptools import setup

setup(
    name='trainer',
    version='0.1',
    packages=find_packages(),
    include_package_data=True,
    description='My training application.'
)
```
Para crear una distribución de fuente, dist/trainer-0.1.tar.gz, debes ejecutar el siguiente comando:
```
python setup.py sdist --formats=gztar
```

Dependencias de aplicaciones de Python

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

Para cada réplica en tu trabajo de entrenamiento personalizado, tu código se ejecuta en un contenedor con muchas dependencias comunes de Python ya instaladas. Verifica las dependencias incluidas en el contenedor compilado previamente que planeas usar para el entrenamiento y verifica si alguna de tus dependencias aún no está instalada. Solo debes completar los siguientes pasos para las dependencias que aún no están instaladas en el contenedor compilado previamente.

Hay 2 tipos de dependencias que tal vez necesites agregar:

Dependencias estándar, que son paquetes comunes de distribución disponibles en PyPI.
Dependencias personalizadas, 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.

Dependencias (PyPI) estándar

Puedes especificar las dependencias estándar de tu aplicación como parte de su secuencia de comandos setup.py. Vertex AI usa pip a fin de instalar tu aplicación de entrenamiento en las réplicas que asigna para tu trabajo. El comando pip install busca dependencias configuradas y las instala.

En el siguiente ejemplo, se muestra un setup.py similar al de una sección anterior. Sin embargo, este setup.py le indica a Vertex AI que instale some_PyPI_package cuando instala la aplicación de entrenamiento:

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.'
)

Dependencias personalizadas

Puedes especificar las dependencias personalizadas de la aplicación si pasas sus rutas como parte de la configuración de tu trabajo. Necesitas la URI de la distribución de fuente de cada dependencia. Las dependencias personalizadas deben estar en una ubicación de Cloud Storage. Vertex AI usa pip install para instalar dependencias personalizadas, de modo que puedan tener dependencias estándar propias en sus secuencias de comandos setup.py.

Cada URI que incluyas es la ruta de acceso a una distribución de fuente, con formato de archivo tarball (.tar.gz) o como una rueda (.whl). Vertex AI instala cada dependencia con pip install en cada réplica que asigna a tu trabajo de entrenamiento.

Si usas la API de Vertex AI para iniciar el entrenamiento personalizado, especifica los URI de Cloud Storage para estas dependencias junto con tu aplicación de entrenamiento en el campo packageUris.

Módulos de Python

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 una sección anterior, tu 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 usas la API de Vertex AI para iniciar un entrenamiento personalizado, establece el campo moduleName en trainer.task.

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

Sube tu distribución de fuente a Cloud Storage

Puedes usar la herramienta de gsutil para subir tu distribución de fuente y cualquier dependencia personalizada a un bucket de Cloud Storage. Por ejemplo:

gsutil cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

Reemplaza CLOUD_STORAGE_DIRECTORY por el URI (empeza con gs:// y termina con /) de un directorio de Cloud Storage en un bucket al que tu proyecto de Google Cloud puede acceder.

Para obtener más información sobre otras maneras de subir tu distribución de fuente a Cloud Storage, lee Sube objetos en la documentación de Cloud Storage.

¿Qué sigue?

Obtén más información sobre los requisitos de código de entrenamiento adicionales para el entrenamiento personalizado.
Obtén más información para crear un trabajo de entrenamiento personalizado o una canalización de entrenamiento personalizada que use tu aplicación de entrenamiento.