Conteneuriser et exécuter du code d'entraînement en local

Vous pouvez exécuter la commande gcloud ai custom-jobs local-run pour créer une image de conteneur Docker à partir de votre code d'entraînement et l'exécuter en tant que conteneur sur votre ordinateur local. Cette fonctionnalité présente plusieurs avantages :

  • Vous pouvez créer une image de conteneur même en n'ayant que des connaissances basiques sur Docker. Vous n'avez pas besoin d'écrire votre propre fichier Dockerfile. Vous pouvez ensuite transférer cette image vers Artifact Registry et l'utiliser pour l'entraînement de conteneurs personnalisés.

    Pour les cas d'utilisation avancés, vous voudrez peut-être tout de même écrire votre propre fichier Dockerfile.

  • Votre image de conteneur peut exécuter une application d'entraînement Python ou un script Bash.

    Vous pouvez utiliser un script Bash pour exécuter du code d'entraînement écrit dans un autre langage de programmation, à condition de spécifier également une image de conteneur de base compatible avec l'autre langage.

  • L'exécution d'un conteneur en local exécute votre code d'entraînement de la même manière que sur Vertex AI.

    L'exécution locale de votre code peut vous aider à résoudre les problèmes liés à votre code avant d'effectuer un entraînement personnalisé sur Vertex AI.

Avant de commencer

  1. Configurez votre environnement de développement Vertex AI.

  2. Installez Docker Engine

  3. Si vous utilisez Linux, configurez Docker pour pouvoir l'exécuter sans sudo.

    La commande local-run nécessite cette configuration pour pouvoir utiliser Docker.

Utiliser la commande local-run

Exécutez la commande suivante pour créer une image de conteneur basée sur votre code d'entraînement et exécuter un conteneur localement :

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

Remplacez l'élément suivant :

  • BASE_IMAGE_URI : URI d'une image Docker à utiliser comme base du conteneur. Choisissez une image de base incluant les dépendances requises par votre code d'entraînement.

    Vous pouvez utiliser l'URI d'une image de conteneur d'entraînement prédéfini ou toute autre valeur valide pour une instruction Dockerfile FROM (par exemple, une image Docker accessible au public ou une image Docker à laquelle vous avez accès dans Artifact Registry).

  • WORKING_DIRECTORY : répertoire de niveau inférieur de votre système de fichiers contenant tous le code d'entraînement et les dépendances locales à utiliser pour l'entraînement.

    Par défaut, la commande ne copie que le répertoire parent du fichier spécifié par l'option --script (consultez l'élément de liste suivant) dans l'image Docker obtenue. L'image Docker n'inclut pas nécessairement tous les fichiers de WORKING_DIRECTORY. Pour personnaliser les fichiers à inclure, consultez la section de ce document sur l'inclusion des dépendances.

    Si vous omettez l'option --local-package-path (et cet espace réservé), la commande local-run utilise le répertoire de travail actuel pour cette valeur.

  • SCRIPT_PATH : chemin d'accès, par rapport à WORKING_DIRECTORY sur votre système de fichiers local, vers le script qui est le point d'entrée de votre code d'entraînement. Il peut s'agir d'un script Python (se terminant par .py) ou d'un script Bash.

    Par exemple, si vous souhaitez exécuter /hello-world/trainer/task.py et que WORKING_DIRECTORY est défini sur /hello-world, utilisez trainer/task.py pour cette valeur.

    Si vous spécifiez un script Python, Python doit être installé sur votre image de base. Si vous spécifiez un script bash, Bash doit être installé sur votre image de base. (Tous les conteneurs d'entraînement prédéfinis et de nombreuses autres images Docker accessibles publiquement incluent ces deux dépendances.)

    Utilisez --python-module à la place de --script.

    Si vous omettez l'option --script (et SCRIPT_PATH), vous devez utiliser l'option --python-module pour spécifier le nom d'un module Python dans WORKING_DIRECTORY, qui sera exécuté comme point d'entrée de l'entraînement. Par exemple, au lieu de --script=trainer/task.py, vous pouvez spécifier --python-module=trainer.task.

    Dans ce cas, le conteneur Docker obtenu charge votre code en tant que module plutôt que sous forme de script. Vous souhaiterez probablement utiliser cette option si votre script de point d'entrée importe d'autres modules Python dans WORKING_DIRECTORY.

  • OUTPUT_IMAGE_NAME : nom de l'image Docker résultante créée par la commande. Vous pouvez utiliser n'importe quelle valeur acceptée par l'option -t de docker build.

    Si vous envisagez de transférer ultérieurement l'image vers Artifact Registry, vous pouvez utiliser un nom d'image conforme aux exigences d'Artifact Registry. Vous pouvez aussi taguer l'image avec d'autres noms ultérieurement.

    Si vous omettez l'option --output-image-uri (et cet espace réservé), la commande local-run ajoute à l'image un nom basé sur l'heure actuelle et le nom de fichier de votre script de point d'entrée.

La commande crée une image de conteneur Docker basée sur votre configuration. Une fois l'image créée, la commande affiche le résultat suivant :

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

La commande utilise immédiatement cette image de conteneur pour exécuter un conteneur sur votre ordinateur local. La commande affiche le résultat suivant à la fermeture du conteneur :

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

Options supplémentaires

Les sections suivantes décrivent des options supplémentaires que vous pouvez utiliser pour personnaliser le comportement de la commande local-run.

Installer des dépendances

Votre code d'entraînement peut s'appuyer sur toutes les dépendances installées sur votre image de base (par exemple, les images de conteneurs d'entraînement prédéfinis incluent de nombreuses bibliothèques Python pour le machine learning), ainsi que sur tous les fichiers que vous incluez dans l'image Docker créée par la commande local-run.

Lorsque vous spécifiez un script avec l'option --script ou --python-module, la commande copie le répertoire parent du script (et ses sous-répertoires) dans l'image Docker. Par exemple, si vous spécifiez --local-package-path=/hello-world et --script=trainer/task.py, la commande copie /hello-world/trainer/ dans l'image Docker.

Vous pouvez également inclure des dépendances Python supplémentaires ou des fichiers arbitraires à partir de votre système de fichiers en effectuant les étapes supplémentaires décrites dans l'une des sections suivantes :

Installer des dépendances Python supplémentaires

Vous pouvez inclure des dépendances Python supplémentaires dans l'image Docker de plusieurs manières :

Utiliser un fichier requirements.txt

Si le répertoire de travail contient un fichier nommé requirements.txt, la commande local-run traite ce fichier comme un fichier d'exigences pip et l'utilise pour installer les dépendances Python dans l'image Docker.

Utiliser un fichier setup.py

Si le répertoire de travail contient un fichier nommé setup.py, la commande local-run traite ce fichier comme unfichier Python setup.py, copie le fichier dans l'image Docker et exécute pip install dans le répertoire de l'image Docker qui contient ce fichier.

Vous pouvez, par exemple, ajouter un argument install_requires à setup.py afin d'installer des dépendances Python dans l'image Docker.

Spécifier les dépendances PyPI individuelles

Vous pouvez utiliser l'option --requirements pour installer des dépendances spécifiques à partir de PyPI dans l'image Docker. Exemple :

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

Remplacez REQUIREMENTS par une liste de spécificateurs d'exigences Python séparés par des virgules.

Spécifier des dépendances Python locales supplémentaires

Vous pouvez utiliser l'option --extra-packages pour installer des dépendances Python locales spécifiques. Ces dépendances Python doivent se trouver dans le répertoire de travail et chaque dépendance doit être dans un format compatible avec pip install (par exemple, un fichier wheel ou une distribution source Python).

Exemple :

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

Remplacez LOCAL_DEPENDENCIES par une liste de chemins d'accès locaux aux fichiers séparés par des virgules, exprimée par rapport au répertoire de travail.

Inclure d'autres fichiers

Pour copier des répertoires supplémentaires dans l'image Docker (sans les installer en tant que dépendances Python), vous pouvez utiliser l'option --extra-dirs. Vous ne pouvez spécifier des répertoires qu'à l'intérieur du répertoire de travail. Exemple :

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

Remplacez EXTRA_DIRECTORIES par une liste de répertoires locaux séparés par une virgule, exprimés par rapport au répertoire de travail.

Arguments de l'application d'entraînement

Si le script de point d'entrée de votre application d'entraînement attend des arguments de ligne de commande, vous pouvez les spécifier lorsque vous exécutez la commande local-run. Ces arguments ne sont pas enregistrés dans l'image Docker et sont transmis en tant qu'arguments lorsque l'image s'exécute en tant que conteneur.

Pour transmettre des arguments à votre script de point d'entrée, transmettez à la commande local-run l'argument -- suivi de ceux de votre script, après tous les autres options de la commande.

Par exemple, imaginez un script que vous exécutez en local à l'aide de la commande suivante :

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

Lorsque vous utilisez la commande local-run, vous pouvez utiliser les options suivantes pour exécuter le script dans le conteneur avec les mêmes arguments :

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/

Accélérer l'entraînement de modèle avec les GPU

Si vous souhaitez à un moment donné déployer l'image Docker créée par la commande local-run sur Vertex AI et utiliser des GPU pour l'entraînement, assurez-vous d'écrire un code d'entraînement qui exploite les GPU et utilise une image Docker compatible avec les GPU pour la valeur de l'option --executor-image-uri. Par exemple, vous pouvez utiliser l'une des images du conteneur d'entraînement préconfiguré compatible avec les GPU.

Si votre ordinateur local exécute Linux et dispose de GPU, vous pouvez également configurer la commande local-run pour qu'elle utilise vos GPU lorsqu'elle exécute un conteneur localement. Cette option est facultative, mais elle peut être utile si vous souhaitez tester le fonctionnement de votre code d'entraînement avec des GPU. Procédez comme suit :

  1. Installez le NVIDIA Container Toolkit (nvidia-docker) sur votre ordinateur local, si ce n'est pas déjà fait.

  2. Utilisez l'indicateur --gpu lorsque vous exécutez la commande local-run : Exemple :

    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

Spécifier un compte de service personnalisé

Par défaut, lorsque la commande local-run exécute votre code d'entraînement dans un conteneur local, elle installe les identifiants Google Cloud disponibles dans votre environnement local via des Identifiants par défaut de l'application (ADC) dans le conteneur, de sorte que votre code d'entraînement puisse utiliser l'ADC pour l'authentification avec les mêmes identifiants. En d'autres termes, les identifiants disponibles via le service ADC dans votre interface système locale sont également disponibles via ADC pour votre code lorsque vous exécutez la commande local-run.

Vous pouvez utiliser la commande gcloud auth application-default login afin d'utiliser votre compte utilisateur pour l'ADC, ou vous pouvez définir une variable d'environnement dans votre interface système pour utiliser un compte de service pour l'ADC.

Si vous souhaitez que le conteneur s'exécute avec des identifiants Google Cloud autres que ceux disponibles par ADC dans votre interface système locale, procédez comme suit :

  1. Créez ou sélectionnez un compte de service avec les autorisations auxquelles vous souhaitez que votre code d'entraînement ait accès.

  2. Téléchargez une clé de compte de service associée à ce compte sur votre ordinateur local.

  3. Lorsque vous exécutez la commande local-run, spécifiez l'option --service-account-key-file. Exemple :

    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

    Remplacez KEY_PATH par le chemin d'accès à la clé de compte de service dans votre système de fichiers local. Ce chemin d'accès doit être absolu ou relatif au répertoire de travail actuel de votre interface système, et non au répertoire spécifié par l'option --local-package-path.

Dans le conteneur obtenu, votre code d'entraînement peut utiliser ADC pour s'authentifier avec les identifiants du compte de service spécifiés.

Comparaison avec l'entraînement sur Vertex AI

Lorsque vous effectuez un entraînement personnalisé sur Vertex AI, celui-ci utilise par défaut l'agent de service de code personnalisé Vertex AI pour votre projet pour exécuter le code. Vous pouvez également associer un autre compte de service pour l'entraînement personnalisé.

Lorsque vous utilisez la commande local-run, vous ne pouvez pas vous authentifier en tant qu'agent de service de code personnalisé Vertex AI, mais vous pouvez créer un compte de service avec des autorisations similaires et l'utiliser localement.

Étapes suivantes