Empaqueter une application d'entraînement

Avant de pouvoir exécuter votre application d'entraînement avec AI Platform Training, vous devez importer le code et toutes les dépendances dans un bucket Cloud Storage auquel votre projet Google Cloud peut accéder. Cette page montre comment empaqueter et préproduire l'application dans le cloud.

Vous obtiendrez les meilleurs résultats en testant l'application d'entraînement en local avant de la transférer vers le cloud. L'entraînement avec AI Platform Training entraîne la facturation de frais sur votre compte en fonction des ressources utilisées.

Avant de commencer

Avant de pouvoir migrer l'application d'entraînement vers le cloud, vous devez accomplir les étapes suivantes :

  1. Configurez votre environnement de développement, tel que décrit dans le guide de démarrage.

  2. Développez l'application d'entraînement avec l'un des frameworks de machine learning hébergés d'AI Platform Training : TensorFlow, scikit-learn ou XGBoost. Vous pouvez également créer un conteneur personnalisé pour adapter l'environnement de votre application d'entraînement. Vous aurez ainsi la possibilité d'utiliser des frameworks de machine learning autres que les frameworks hébergés d'AI Platform Training.

    Si, au terme de l'entraînement, vous souhaitez déployer votre modèle entraîné sur AI Platform Prediction, lisez le guide expliquant comment exporter votre modèle à des fins de prédiction. Cela vous permettra de confirmer que les artefacts de modèle exportés par votre package d'entraînement peuvent être utilisés par AI Platform Prediction.

  3. Suivez le guide afin de configurer un bucket Cloud Storage dans lequel vous pouvez stocker les données et les fichiers de l'application d'entraînement.

  4. Veillez à connaître toutes les bibliothèques Python dont l'application d'entraînement dépend, qu'elles soient sous forme de packages personnalisés ou disponibles gratuitement via PyPI.

Ce document traite des facteurs suivants qui influencent la façon dont vous empaquetez l'application et la transférez vers Cloud Storage :

  • Utilisation de la CLI gcloud (recommandée) ou codage de votre propre solution
  • Création manuelle du package, si nécessaire
  • Inclusion de dépendances supplémentaires qui ne sont pas installées par l'environnement d'exécution AI Platform Training que vous utilisez

Le moyen le plus simple d'empaqueter votre application et de la transférer avec ses dépendances est d'utiliser la CLI gcloud. Elle permet d'empaqueter et d'importer l'application ainsi que d'envoyer votre première tâche d'entraînement à l'aide d'une seule commande (gcloud ai-platform jobs submit training).

Pour plus de commodité, il est utile de définir les valeurs de configuration en tant que variables d'interface système :

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

Remplacez les éléments suivants :

  • LOCAL_PACKAGE_PATH : chemin d'accès au répertoire de votre package Python dans votre environnement local.
  • MODULE_NAME : nom complet de votre module d'entraînement.
  • BUCKET_NAME : nom d'un bucket Cloud Storage.
  • JOB_NAME : nom de votre tâche d'entraînement.
  • JOB_OUTPUT_PATH : URI d'un répertoire Cloud Storage dans lequel vous souhaitez que votre tâche d'entraînement enregistre son résultat.
  • REGION : région dans laquelle vous souhaitez exécuter votre tâche d'entraînement.

Consultez la liste après la commande suivante pour en savoir plus sur les exigences applicables à ces valeurs.

L'exemple suivant présente une commande gcloud ai-platform jobs submit training qui empaquette une application et envoie la tâche d'entraînement :

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

  • --staging-bucket spécifie un bucket Cloud Storage dans lequel vous souhaitez préproduire vos packages d'entraînement et de dépendances. Votre projet Google Cloud doit avoir accès à ce bucket Cloud Storage, lequel doit se trouver dans la région dans laquelle vous exécutez la tâche. Consultez les régions disponibles pour les services AI Platform Training. Si vous ne spécifiez aucun bucket de préproduction, Cloud ML Engine préproduit les packages à l'emplacement indiqué dans le paramètre job-dir.

  • --job-dir spécifie l'emplacement Cloud Storage à utiliser pour les fichiers de sortie de la tâche d'entraînement. Le projet Google Cloud doit avoir accès à ce bucket Cloud Storage, qui doit se trouver dans la région dans laquelle vous exécutez la tâche. Consultez les régions disponibles pour les services AI Platform Training.

  • --package-path spécifie le chemin d'accès local au répertoire de l'application. La CLI gcloud crée un package de distribution .tar.gz à partir de votre code en fonction du fichier setup.py qui se trouve dans le répertoire parent du répertoire spécifié par l'indicateur --package-path. Il importe ensuite ce fichier .tar.gz dans Cloud Storage pour exécuter la tâche d'entraînement.

    Si aucun fichier setup.py n'est disponible à l'emplacement prévu, la CLI gcloud crée un fichier setup.py simple et temporaire qui ne comprend que le répertoire spécifié par l'indicateur --package-path dans le fichier .tar.gz créé.

  • --module-name spécifie le nom du module principal de l'application, en utilisant la notation par points de l'espace de noms du package. Il s'agit du fichier Python que vous exécutez pour démarrer l'application. Par exemple, si le module principal est .../my_application/trainer/task.py (reportez-vous à la structure de projet recommandée), le nom du module est trainer.task.

  • Si vous spécifiez une option à la fois dans le fichier de configuration (config.yaml) et en tant qu'indicateur de ligne de commande, c'est la valeur de la ligne de commande qui est retenue, celle du fichier de configuration étant ignorée.
  • L'indicateur vide -- marque la fin des indicateurs propres à gcloud et le début des arguments USER_ARGS que vous souhaitez transmettre à l'application.
  • Les options spécifiques à AI Platform Training, telles que --module-name, --runtime-version et --job-dir, doivent figurer avant l'option vide --. Le service AI Platform Training interprète ces options.
  • L'option --job-dir, si elle est spécifiée, doit précéder l'option -- vide, car AI Platform Training utilise l'option --job-dir pour valider le chemin.
  • L'application doit également gérer l'indicateur --job-dir, s'il est spécifié. Même s'il est placé avant l'indicateur vide --, l'indicateur --job-dir est également transmis à l'application comme indicateur de ligne de commande.
  • Vous pouvez définir autant d'arguments USER_ARGS que nécessaire. AI Platform Training transmet les options --user_first_arg, --user_second_arg, etc. à votre application.

Vous pouvez en savoir plus sur les indicateurs d'envoi de tâches dans le guide sur l'exécution d'une tâche d'entraînement.

Travailler avec les dépendances

Les dépendances sont des packages que vous importez (import) dans le code. Votre application peut nécessiter de nombreuses dépendances pour fonctionner.

Lorsque vous exécutez une tâche d'entraînement sur AI Platform Training, la tâche est exécutée sur des instances d'entraînement (machines virtuelles spécialement configurées) sur lesquelles de nombreux packages Python courants sont déjà installés. Vérifiez les packages inclus dans la version d'exécution que vous utilisez pour l'entraînement et notez toutes les dépendances qui ne sont pas déjà installées.

Il existe deux types de dépendances potentiellement à ajouter :

  • Dépendances standards : packages Python communs disponibles sur PyPI.
  • Packages personnalisés : par exemple, packages que vous avez développés vous-même ou packages internes d'une organisation.

Les sections ci-dessous décrivent la procédure associée à chaque type.

Ajouter des dépendances standards (PyPI)

Vous pouvez indiquer les dépendances standards de votre package dans son script setup.py. AI Platform Training utilise pip pour installer votre package sur les instances d'entraînement qu'il alloue à votre tâche. La commande pip install recherche les dépendances configurées et les installe.

Créez un fichier nommé setup.py dans le répertoire racine de l'application (répertoire parent du répertoire trainer, si vous suivez le modèle recommandé).

Entrez le script suivant dans setup.py, en insérant vos propres valeurs :

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 vous utilisez Google Cloud CLI pour envoyer votre tâche d'entraînement, elle utilise automatiquement votre fichier setup.py pour créer le package.

Si vous envoyez la tâche d'entraînement sans gcloud, utilisez la commande suivante pour exécuter le script :

python setup.py sdist

Pour plus d'informations, consultez la section sur l'empaquetage manuel de l'application d'entraînement.

Ajouter des dépendances personnalisées

Vous pouvez indiquer les dépendances personnalisées de l'application en transmettant leurs chemins d'accès dans la configuration de votre tâche. Vous avez besoin de l'URI du package de chaque dépendance. Les dépendances personnalisées doivent se trouver dans un emplacement Cloud Storage. AI Platform Training utilise pip install pour installer des dépendances personnalisées. Elles peuvent ainsi avoir leurs propres dépendances standards dans leurs scripts setup.py.

Si vous utilisez la CLI gcloud pour exécuter votre tâche d'entraînement, vous pouvez spécifier des dépendances sur votre ordinateur local et sur Cloud Storage. L'outil les mettra en place dans le cloud comme suit : lorsque vous exécutez la commande gcloud ai-platform jobs submit training, définissez l'indicateur --packages afin d'inclure les dépendances dans une liste séparée par des virgules.

Chaque URI inclus correspond au chemin d'accès à un package de distribution au format "tarball"(.tar.gz) ou "wheel" (.whl). AI Platform Training installe chaque package à l'aide de pip install sur chaque machine virtuelle allouée à la tâche d'entraînement.

L'exemple ci-dessous spécifie les dépendances empaquetées nommées dep1.tar.gz et dep2.whl (une pour chaque type de package compatible) avec un chemin d'accès aux sources de l'application :

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

De même, l'exemple ci-dessous spécifie les dépendances empaquetées nommées dep1.tar.gz et dep2.whl (une pour chaque type de package compatible), mais avec une application d'entraînement déjà créée :

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --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 vous exécutez des tâches d'entraînement directement à l'aide de l'API AI Platform Training and Prediction, vous devez préproduire les packages des dépendances dans un emplacement Cloud Storage, puis en préciser les chemins d'accès.

Créer le package manuellement

La création de package de code Python dépasse largement le cadre de cette documentation. Pour plus de commodité, cette section fournit une présentation de l'utilisation de Setuptools pour créer le package. Vous pouvez utiliser d'autres bibliothèques aux mêmes fins.

Pour créer le package manuellement, procédez comme suit :

  1. Dans chaque répertoire du package d'application, incluez un fichier nommé __init__.py, qui peut être vide ou contenir du code qui s'exécute lorsque ce package (n'importe quel module de ce répertoire) est importé.

  2. Dans le répertoire parent de l'ensemble du code que vous souhaitez inclure dans le package de distribution .tar.gz (répertoire parent du répertoire trainer si vous suivez le modèle recommandé), incluez le fichier Setuptools nommé setup.py comprenant les éléments suivants :

    • Instructions d'importation pour setuptools.find_packages et setuptools.setup

    • Appel à setuptools.setup avec (au minimum) les paramètres suivants définis :

      • _name_ défini sur le nom de l'espace de noms du package

      • _version_ défini sur le numéro de cette version du package

      • _install_requires_ défini sur la liste des packages requis par l'application, ainsi que des exigences de version, comme 'docutils>=0.3'

      • _packages_ défini sur find_packages() Cela indique à l'outil "Setuptools" d'inclure tous les sous-répertoires du répertoire parent qui contiennent un fichier __init__.py en tant que "packages importés" (grâce à eux, vous import des modules dans Python à l'aide d'instructions telles que from trainer import util) dans votre package de distribution (le fichier ".tar.gz" contenant l'ensemble du code).

      • _include_package_data_ défini sur True

  3. Exécutez python setup.py sdist pour créer le package de distribution .tar.gz.

Structure de projet recommandée

Vous pouvez structurer l'application d'entraînement comme vous le souhaitez. Cependant, la structure suivante est couramment utilisée dans les exemples de AI Platform Training. Organiser votre projet comme dans les exemples peut vous permettre de les suivre plus facilement.

  • Utilisez un répertoire de projet principal, contenant votre fichier setup.py.

    Utilisez la fonction find_packages() de setuptools dans votre fichier setup.py pour vous assurer que tous les sous-répertoires sont inclus dans le package de distribution .tar.gz que vous créez.

  • Utilisez un sous-répertoire nommé trainer pour stocker votre module d'application principal.

  • Nommez votre module d'application principal task.py.

  • Créez les sous-répertoires du répertoire de projet principal dont vous avez besoin pour mettre en œuvre l'application.

  • Créez un fichier __init__.py dans chaque sous-répertoire. Ces fichiers permettent à Setuptools d'identifier les répertoires avec le code à empaqueter, et peuvent être vides.

Dans les exemples AI Platform Training, le répertoire trainer contient généralement les fichiers sources suivants :

  • task.py contient la logique d'application qui gère la tâche d'entraînement.

  • model.py contient la logique du modèle.

  • util.py, s'il est présent, contient le code permettant d'exécuter l'application d'entraînement.

Structure recommandée d'un projet d'application d'entraînement

Lorsque vous exécutez gcloud ai-platform jobs submit training, définissez l'option --package-path sur trainer. Ainsi, la CLI gcloud recherche un fichier dans le répertoire setup.py parent de trainer, votre répertoire de projet principal.

Modules Python

Votre package d'application peut contenir plusieurs modules (fichiers Python). Vous devez identifier le module qui contient le point d'entrée de votre application. Le service d'entraînement exécute ce module en faisant appel à Python, comme vous le feriez localement.

Par exemple, si vous respectez la structure recommandée dans la section précédente, votre module principal est task.py. Étant donné qu'il se trouve dans un package importé (répertoire contenant un fichier __init__.py) nommé trainer, le nom complet de ce module est trainer.task. Ainsi, si vous envoyez votre tâche à l'aide de gcloud ai-platform jobs submit training, définissez l'option --module-name sur trainer.task.

Consultez le guide Python relatif aux packages pour plus d'informations sur les modules.

Utiliser l'outil gcloud pour importer un package existant

Si vous créez le package vous-même, vous pouvez l'importer avec la CLI gcloud. Exécutez la commande gcloud ai-platform jobs submit training :

  • Définissez l'option --packages sur le chemin d'accès à l'application empaquetée.

  • Définissez l'option --module-name sur le nom du module principal de votre application à l'aide de la notation par points de l'espace de noms de votre package. Il s'agit du fichier Python que vous exécutez pour démarrer l'application. Par exemple, si le module principal est .../my_application/trainer/task.py (reportez-vous à la structure de projet recommandée), le nom du module est trainer.task.

L'exemple ci-dessous montre comment utiliser un package tarball compressé (appelé trainer-0.0.1.tar.gz ici) qui se trouve dans le même répertoire que celui où vous exécutez la commande. La fonction principale se trouve dans un module appelé task.py:

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

Utiliser l'outil gcloud pour employer un package existant déjà dans le cloud

Si vous créez le package vous-même et que vous l'importez vers un emplacement Cloud Storage, vous pouvez utiliser gcloud à cet effet. Exécutez la commande gcloud ai-platform jobs submit training :

  • Définissez l'option --packages sur le chemin d'accès à l'application empaquetée.

  • Définissez l'option --module-name sur le nom du module principal de votre application à l'aide de la notation par points de l'espace de noms de votre package. Il s'agit du fichier Python que vous exécutez pour démarrer l'application. Par exemple, si le module principal est .../my_application/trainer/task.py (reportez-vous à la structure de projet recommandée), le nom du module est trainer.task.

L'exemple ci-dessous montre comment utiliser un package tarball compressé qui se trouve dans un bucket Cloud Storage :

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

$PATH_TO_PACKAGED_TRAINER est une variable d'environnement qui représente le chemin d'accès à un package existant déjà dans le cloud. Par exemple, le chemin d'accès peut pointer vers l'emplacement Cloud Storage suivant, contenant un package tarball compressé nommé trainer-0.0.1.tar.gz :

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

Transférer des packages manuellement

Vous pouvez transférer vos packages manuellement si besoin. Le plus souvent, ce sera pour appeler l'API AI Platform Training and Prediction directement et commencer la tâche d'entraînement. Pour importer manuellement le package et ses dépendances personnalisées dans votre bucket Cloud Storage, le plus simple est d'utiliser l'outil gsutil :

gsutil cp /local/path/to/package.tar.gz  gs://bucket/path/

Cependant, si vous pouvez utiliser la ligne de commande pour cette opération, exécutez simplement gcloud ai-platform jobs submit training pour importer vos packages dans la configuration d'une tâche d'entraînement. Si vous ne pouvez pas utiliser la ligne de commande, faites appel à la bibliothèque cliente Cloud Storage pour effectuer une importation par programmation.

Étapes suivantes

Suivant
Exécuter une tâche d'entraînement