Crear en contenedores y ejecutar código de entrenamiento de forma local

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

  • Puedes crear una imagen de contenedor con conocimientos mínimos de Docker. No es necesario que escribas tu propio Dockerfile. Después, puedes enviar esta imagen a Artifact Registry y usarla para entrenar contenedores personalizados.

    En casos prácticos avanzados, puede que quieras escribir tu propio Dockerfile.

  • Tu 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 que también especifiques una imagen de contenedor base que admita el otro lenguaje).

  • Al ejecutar un contenedor de forma local, el código de entrenamiento se ejecuta de forma similar a como se ejecuta en Vertex AI.

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

Antes de empezar

  1. Configura tu entorno de desarrollo de Vertex AI.

  2. Instala Docker Engine.

  3. Si usas Linux, configura Docker para que puedas ejecutarlo sin sudo.

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

Usar el comando local-run

Ejecuta el siguiente comando para crear una imagen de contenedor basada en tu código de entrenamiento y ejecutar un contenedor de forma 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

Haz los cambios siguientes:

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

    Puedes usar el URI de una imagen de contenedor de entrenamiento prediseñada o cualquier otro valor que sea válido para una instrucción FROM de Dockerfile; por ejemplo, una imagen Docker disponible públicamente o una imagen Docker en Artifact Registry a la que tengas acceso.

  • WORKING_DIRECTORY: El directorio de nivel más bajo de tu sistema de archivos que contiene todo el código de entrenamiento y las dependencias locales que necesitas para el entrenamiento.

    De forma predeterminada, el comando solo copia el directorio principal del archivo especificado por 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 de WORKING_DIRECTORY. Para personalizar los archivos que se incluyen, consulta la sección de este documento sobre cómo incluir dependencias.

    Si omites la marca --local-package-path (y este marcador de posición), el comando local-run usará el directorio de trabajo actual para este valor.

  • SCRIPT_PATH: la ruta, relativa a WORKING_DIRECTORY en tu sistema de archivos local, de la secuencia de comandos que es el punto de entrada de tu código de entrenamiento. Puede ser una secuencia de comandos de Python (que termina en .py) o una secuencia de comandos de Bash.

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

    Si especificas una secuencia de comandos de Python, tu imagen base debe tener Python instalado. Si especificas una secuencia de comandos de Bash, tu imagen base debe tener Bash instalado. Todos los contenedores de entrenamiento prediseñados y muchas otras imágenes de Docker disponibles públicamente incluyen estas dos dependencias.

    Utiliza --python-module en lugar de --script.

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

    En este caso, el contenedor Docker resultante carga el código como un módulo en lugar de como una secuencia de comandos. Probablemente quieras usar esta opción si tu secuencia de comandos del punto de entrada importa otros módulos de Python en WORKING_DIRECTORY.

  • OUTPUT_IMAGE_NAME: nombre de la imagen de Docker resultante creada por el comando. Puede usar cualquier valor que acepte la docker buildmarca -t.

    Si tienes previsto insertar la imagen en Artifact Registry más adelante, te recomendamos que uses un nombre de imagen que cumpla los requisitos de Artifact Registry. También puede 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 etiquetará la imagen con un nombre basado en la hora actual y el nombre de archivo de tu secuencia de comandos del punto de entrada.

El comando crea una imagen de contenedor Docker basada en tu configuración. Después de compilar la imagen, el comando muestra el siguiente resultado:

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

A continuación, el comando usa inmediatamente esta imagen de contenedor para ejecutar un contenedor en tu ordenador local. Cuando el contenedor se cierra, el comando imprime el siguiente resultado:

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

Opciones adicionales

En las siguientes secciones se describen otras opciones que puede usar para personalizar el comportamiento del comando local-run.

Instalar dependencias

Tu código de entrenamiento puede depender de cualquier dependencia instalada en tu imagen base (por ejemplo, las imágenes de contenedor de entrenamiento precompilado incluyen muchas bibliotecas de Python para el aprendizaje automático), así como de cualquier archivo que incluyas en la imagen de Docker creada con el comando local-run.

Cuando especificas una secuencia de comandos con la marca --script o la marca --python-module, el comando copia el directorio principal 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 copiará /hello-world/trainer/ en la imagen de Docker.

También puedes incluir dependencias de Python adicionales o archivos arbitrarios de tu sistema de archivos siguiendo los pasos adicionales que se describen en una de las siguientes secciones:

Instalar dependencias de Python adicionales

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

Usar 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 de pip y lo usa para instalar dependencias de Python en la imagen de Docker.

Usar 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 de Python setup.py, copia el archivo en la imagen de Docker y ejecuta pip install en el directorio de la imagen de Docker que contiene este archivo.

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

Especificar dependencias de PyPI individuales

Puedes usar la marca --requirements para instalar dependencias específicas de PyPI en la imagen 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

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

Especificar dependencias de Python locales adicionales

Puedes usar la marca --extra-packages para instalar dependencias locales específicas de Python. Estas dependencias de Python deben estar en el directorio de trabajo y cada una de ellas debe tener un formato que pip install admita. Por ejemplo, un archivo wheel 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

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

Incluir 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 del 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

Sustituye EXTRA_DIRECTORIES por una lista separada por comas de directorios locales, expresada en relación con el directorio de trabajo.

Argumentos de la aplicación de entrenamiento

Si la secuencia de comandos del punto de entrada de tu aplicación de entrenamiento espera argumentos de línea de comandos, puedes especificarlos al ejecutar el comando local-run. Estos argumentos no se guardan en la imagen de Docker, sino que se transfieren como argumentos cuando la imagen se ejecuta como un contenedor.

Para transferir argumentos a tu secuencia de comandos de punto de entrada, transfiere el argumento -- seguido de los argumentos de tu secuencia de comandos al comando local-run después de todas las demás marcas del comando.

Por ejemplo, imagina un script 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/

Acelerar el entrenamiento de modelos con GPUs

Si quieres desplegar la imagen de Docker creada con el comando local-run en Vertex AI y usar GPUs para el entrenamiento, asegúrate de escribir código de entrenamiento que aproveche las GPUs y usa una imagen de Docker habilitada para GPUs como valor de la marca --executor-image-uri. Por ejemplo, puedes usar una de las imágenes de contenedor de entrenamiento prediseñadas que admiten GPUs.

Si tu ordenador local ejecuta Linux y tiene GPUs, también puedes configurar el comando local-run para que use tus GPUs cuando ejecute un contenedor de forma local. Este paso es opcional, pero puede ser útil si quieres probar cómo funciona tu código de entrenamiento con GPUs. Sigue estos pasos:

  1. Instala el kit de herramientas de contenedor de NVIDIA (nvidia-docker) en tu ordenador local, si aún no lo has hecho.

  2. Especifica la marca --gpu al ejecutar 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

Especificar una cuenta de servicio personalizada

De forma predeterminada, cuando el comando local-run ejecuta tu código de entrenamiento en un contenedor local, monta las Google Cloud credenciales disponibles en tu entorno local Google Cloud mediante las credenciales predeterminadas de la aplicación (ADC) en el contenedor, de forma que tu código de entrenamiento pueda usar las ADC para autenticarse con las mismas credenciales. Es decir, las credenciales disponibles mediante ADC en tu shell local también están disponibles mediante ADC para tu código cuando ejecutas el comando local-run.

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

Si quieres que el contenedor se ejecute con Google Cloud credenciales distintas de las disponibles mediante ADC en tu shell local, haz lo siguiente:

  1. Crea o selecciona una cuenta de servicio con los permisos a los que quieras que acceda tu código de entrenamiento.

  2. Descarga una clave de cuenta de servicio en tu ordenador local.

  3. 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

    Sustituye 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, tu código de entrenamiento puede usar ADC para autenticarse con las credenciales de cuenta de servicio especificadas.

Comparación con el entrenamiento en Vertex AI

Cuando realizas un entrenamiento personalizado en Vertex AI, Vertex AI usa de forma predeterminada el agente de servicio de código personalizado de Vertex AI para tu proyecto para ejecutar tu código. También puedes adjuntar otra cuenta de servicio para el entrenamiento personalizado.

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

Siguientes pasos