Crea contenedores y ejecuta código de entrenamiento de manera local

Puedes usar el comando gcloud ai custom-jobs local-run para compilar una imagen de contenedor de Docker basada en tu código de entrenamiento y ejecutar la imagen como un contenedor en tu computadora local. Esta función ofrece varios beneficios:

Puedes compilar una imagen de contenedor con un conocimiento mínimo de Docker. No es necesario que escribas tu propio Dockerfile. Luego, puedes enviar esta imagen a Artifact Registry y usarla para el entrenamiento de contenedores personalizado.

Para casos de uso avanzados, es posible que aún quieras escribir tu propio Dockerfile.
La imagen de contenedor puede ejecutar una aplicación de entrenamiento de Python o una secuencia de comandos de Bash.

Puedes usar una secuencia de comandos de Bash para ejecutar código de entrenamiento escrito en otro lenguaje de programación (siempre y cuando también especifiques una imagen de contenedor base que admita el otro lenguaje).
La ejecución local de un contenedor ejecuta tu código de entrenamiento de manera similar a la que se ejecuta en Vertex AI.

Ejecutar el código de manera local puede ayudarte a depurar problemas antes de realizar un entrenamiento personalizado en Vertex AI.

Antes de comenzar

Configura tu entorno de desarrollo de Vertex AI.
Instala Docker Engine
Si usas Linux, configura Docker para que puedas ejecutarlo sin sudo.

El comando local-run requiere esta configuración para usar Docker.

Usa el comando `local-run`

Ejecuta el siguiente comando para compilar una imagen de contenedor basada en el código de entrenamiento y ejecuta un contenedor de manera local:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

Reemplaza lo siguiente:

BASE_IMAGE_URI: El URI de una imagen de Docker que se usará como base del contenedor. Elige una imagen base que incluya las dependencias necesarias para el código de entrenamiento.

Puedes usar el URI para uncontenedor de entrenamiento compilado previamente o cualquier otro valor que sea válido por unaDockerfileFROM instrucción ; por ejemplo, una imagen de Docker disponible de forma pública o una imagen de Docker en Artifact Registry a los que tienes acceso.
WORKING_DIRECTORY: El directorio de nivel más bajo en el sistema de archivos que contiene todo el código de entrenamiento y las dependencias locales que necesitas usar para el entrenamiento.

De forma predeterminada, el comando solo copia el directorio superior del archivo que especifica la marca --script (consulta el siguiente elemento de la lista) en la imagen de Docker resultante. La imagen de Docker no incluye necesariamente todos los archivos dentro de WORKING_DIRECTORY. Para personalizar qué archivos se incluyen, consulta la sección de este documento sobre incluidas las dependencias.

Si omites la marca --local-package-path (y este marcador de posición), el comando local-run usa el directorio de trabajo actual para este valor.
SCRIPT_PATH: La ruta de acceso (en relación con WORKING_DIRECTORY en el sistema de archivos local) a la secuencia de comandos que es el punto de entrada del código de entrenamiento Puede ser una secuencia de comandos de Python (que termina en .py) o una de Bash.

Por ejemplo, si deseas ejecutar /hello-world/trainer/task.py y WORKING_DIRECTORY es /hello-world, usa trainer/task.py para este valor.

Si especificas una secuencia de comandos de Python, la imagen base debe tener instalado Python. Si especificas una secuencia de comandos bash, la imagen base debe tener instalado Bash. Todos los contenedores de entrenamiento compilados con anterioridad y muchas otras imágenes de Docker disponibles a nivel público incluyen estas dos dependencias.

Usa --python-module en lugar de --script

Si omites la marca --script (y SCRIPT_PATH), debes usar la marca --python-module a fin de especificar el nombre de un módulo de Python en WORKING_DIRECTORY para que se ejecute. el punto de entrada al entrenamiento. Por ejemplo, en lugar de --script=trainer/task.py, puedes especificar --python-module=trainer.task.

En este caso, el contenedor resultante de Docker carga el código como un módulo en lugar de como una secuencia de comandos. Es probable que desees usar esta opción si la secuencia de comandos del punto de entrada importa otros módulos de Python en WORKING_DIRECTORY.
OUTPUT_IMAGE_NAME: Un nombre para la imagen resultante de Docker que compiló el comando. Puedes usar cualquier valor que acepte la marca docker build de -t.

Si planeas enviar la imagen a Artifact Registry más adelante, te recomendamos usar un nombre de imagen que cumpla con los requisitos de Artifact Registry. (Como alternativa, puedes etiquetar la imagen con nombres adicionales más adelante).

Si omites la marca --output-image-uri (y este marcador de posición), el comando local-run etiqueta la imagen con un nombre basado en la hora actual y el nombre de archivo de la secuencia de comandos de punto de entrada.

El comando compila una imagen de contenedor de Docker según tu configuración. Después de compilar la imagen, el comando muestra el siguiente resultado:

A training image is built.
Starting to run ...

El comando usa esta imagen de contenedor de inmediato para ejecutar un contenedor en tu computadora local. Cuando el contenedor se cierra, el comando muestra el siguiente resultado:

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

Opciones adicionales

En las siguientes secciones, se describen opciones adicionales que puedes usar para personalizar el comportamiento del comando local-run.

Instala dependencias

Tu código de entrenamiento puede depender de cualquier dependencia instalada en tu imagen base (por ejemplo, las imágenes de contenedores de entrenamiento ya compiladas, que incluyen muchas bibliotecas de Python para el aprendizaje automático) y cualquier archivo que incluyes en la imagen de Docker creada por el comando local-run.

Cuando especificas una secuencia de comandos con la marca --script o la marca --python-module, el comando copia el directorio superior de la secuencia de comandos (y sus subdirectorios) en la imagen de Docker. Por ejemplo, si especificas --local-package-path=/hello-world y --script=trainer/task.py, el comando copia /hello-world/trainer/ en la imagen de Docker.

También puedes incluir dependencias adicionales de Python o archivos arbitrarios de tu sistema de archivos si completas los pasos adicionales descritos en una de las siguientes secciones:

Usa un archivo requirements.txt para dependencias de Python
Usa un archivo setup.py para dependencias de Python
Especifica dependencias individuales de PyPI
Especifica dependencias locales de Python
Incluye otros archivos

Instala dependencias adicionales de Python

Puedes incluir dependencias adicionales de Python en la imagen de Docker de varias maneras:

Usa un archivo `requirements.txt`

Si hay un archivo llamado requirements.txt en el directorio de trabajo, el comando local-run lo trata como un archivo de requisitos pip y lo usa para instalar dependencias de Python en la imagen de Docker.

Usa un archivo `setup.py`

Si hay un archivo llamado setup.py en el directorio de trabajo, el comando local-run lo trata como un archivo setup.py de Python, lo copia en la imagen de Docker y ejecuta pip install en el directorio de la imagen de Docker que contiene este archivo.

Por ejemplo, puedes agregar un argumento install_requires a setup.py para instalar dependencias de Python en la imagen de Docker.

Especifica dependencias de PyPI individuales

Puedes usar la marca --requirements para instalar dependencias específicas de PyPI en la imagen de Docker. Por ejemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

Reemplaza REQUIREMENTS por una lista separada por comas de especificadores de requisitos de Python.

Especifica dependencias locales adicionales de Python

Puedes usar la marca --extra-packages para instalar dependencias específicas de Python locales. Estas dependencias de Python deben estar en el directorio de trabajo y cada dependencia debe tener un formato compatible con pip install. Por ejemplo, un archivo de rueda o una distribución de origen de Python.

Por ejemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

Reemplaza LOCAL_DEPENDENCIES por una lista separada por comas de las rutas de los archivos locales, expresadas en relación con el directorio de trabajo.

Incluye otros archivos

Para copiar directorios adicionales en la imagen de Docker (sin instalarlos como dependencias de Python), puedes usar la marca --extra-dirs. Solo puedes especificar directorios en el directorio de trabajo. Por ejemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

Reemplaza EXTRA_DIRECTORIES por una lista de directorios locales separados por comas, expresados en relación con el directorio de trabajo.

Argumentos de la aplicación de entrenamiento

Si la secuencia de comandos de punto de entrada para la aplicación de entrenamiento espera argumentos de la línea de comandos, puedes especificarlos cuando ejecutes el comando local-run. Estos argumentos no se guardan en la imagen de Docker. En su lugar, se pasan como argumentos cuando la imagen se ejecuta como un contenedor.

Para pasar los argumentos a la secuencia de comandos de punto de entrada, pasa el argumento -- seguido de los argumentos de la secuencia de comandos al comando local-run después de todas las otras marcas del comando.

Por ejemplo, imagina una secuencia de comandos que ejecutas de forma local con el siguiente comando:

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Cuando usas el comando local-run, puedes usar las siguientes marcas para ejecutar la secuencia de comandos en el contenedor con los mismos argumentos:

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

Acelera el entrenamiento de modelos con GPU

Si finalmente desea implementar la imagen de Docker creada por el comando local-run para Vertex AI yUsa GPU para el entrenamiento y, luego, asegúrate deescribir un código de entrenamiento que aproveche las GPU y usar una imagen de Docker habilitada en GPU para el valor de la marca--executor-image-uri. Por ejemplo, puedes usar una de las imágenes de contenedor de entrenamiento compiladas previamente que admiten GPU.

Si tu computadora local ejecuta Linux y tiene GPU, también puedes configurar el comando local-run para usar tus GPU cuando se ejecuta un contenedor de manera local. Esto es opcional, pero puede ser útil si deseas probar cómo funciona el código de entrenamiento con GPU. Haz lo siguiente:

Si aún no lo hiciste, instala NVIDIA Container Toolkit (nvidia-docker) en tu computadora local.

Usa la marca --gpu cuando ejecutes el comando local-run: Por ejemplo:

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

Especifica una cuenta de servicio personalizada

De forma predeterminada, cuandolocal-run ejecuta tu código de entrenamiento en un contenedor local, activa las credenciales de Google Cloud disponibles en tu entorno local a través deCredenciales predeterminadas de la aplicación (ADC) en el contenedor, de modo que tu código de entrenamiento pueda usar ADC para la autenticación con las mismas credenciales. En otras palabras, las credenciales que está disponible en ADC en tu shell local también están disponibles para tu código cuando ejecutas el comando local-run.

Puedes usar el comando gcloud auth application-default login a fin de usar tu cuenta de usuario para ADC o establecer una variable de entorno en tu shell para usar una cuenta de servicio para ADC.

Si deseas que el contenedor se ejecute con credenciales de Google Cloud que no sean las disponibles por ADC en tu shell local, haz lo siguiente:

Crea o selecciona una cuenta de servicio con los permisos a los que deseas que tu código de entrenamiento tenga acceso.
Descarga una clave de cuenta de servicio para esta cuenta de servicio a tu computadora local.
Cuando ejecutes el comando local-run, especifica la marca --service-account-key-file. Por ejemplo:
```
gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH
```
Reemplaza KEY_PATH por la ruta a la clave de la cuenta de servicio en tu sistema de archivos local. Debe ser absoluto o relativo al directorio de trabajo actual de tu shell, no relativo al directorio especificado por la marca --local-package-path.

En el contenedor resultante, el código de entrenamiento puede usar ADC para autenticarse con las credenciales de la cuenta de servicio especificada.

Comparación con el entrenamiento en Vertex AI

Si realizas un entrenamiento personalizado en Vertex AI, Vertex AI usa el agente de servicio de Vertex AI personalizado para tu proyecto de forma predeterminada a fin de ejecutar tu código. También puedes vincular una cuenta de servicio diferente para el entrenamiento personalizado.

Cuando usas el comando local-run, no puedes autenticarte como el agente de servicio del código personalizado de Vertex AI, pero puedes crear una cuenta de servicio con permisos similares y usarla de forma local.

¿Qué sigue?

Obtén más información sobre los requisitos para el código de entrenamiento.
Obtén información sobre cómo enviar la imagen de Docker a Artifact Registry y usarla como un contenedor personalizado para el entrenamiento en Vertex AI.