Créer une application d'entraînement Python pour un conteneur prédéfini

Avant de pouvoir effectuer un entraînement sans serveur Gemini Enterprise Agent Platform avec un conteneur prédéfini, vous devez créer une distribution source Python contenant votre application d'entraînement, puis l'importer dans un bucket Cloud Storage auquel votre projet Google Cloud peut accéder.

Alternatives à la création d'une distribution source

Ce guide explique comment créer manuellement une distribution source et l'importer dans Cloud Storage. Avant de suivre le guide, envisagez les autres workflows suivants, qui peuvent s'avérer plus pratiques dans certains cas :

  • Si vous souhaitez effectuer l'entraînement à l'aide du code sur votre ordinateur local et réduire autant que possible les tâches de création de packages manuelles, nous vous recommandons d'utiliser la fonctionnalité d'empaquetage automatique de Google Cloud CLI. Cette fonctionnalité vous permet de créer une image de conteneur Docker, de la transférer vers Artifact Registry et de créer une ressource CustomJob basée sur l'image du conteneur, le tout à l'aide d'une seule commande. Pour en savoir plus, consultez le guide de création d'une ressource CustomJob.

    Pour utiliser la fonctionnalité de création de packages automatique, vous devez installer Docker sur votre ordinateur local. Cette option ne vous permet de créer qu'une ressource CustomJob, et non une ressource TrainingPipeline ou HyperparameterTuningJob. (Découvrez les différences entre les ressources d'entraînement sans serveur.)

  • Pour personnaliser davantage votre image de conteneur et exécuter votre code dans un conteneur en local avant de l'exécuter sur Agent Platform, vous pouvez exécuter la commande local-run de la gcloud CLI pour conteneuriser votre code et l'exécuter localement. Vous pouvez ensuite transmettre manuellement l'image à Artifact Registry.

    Pour exécuter la commande local-run, vous devez installer Docker sur votre ordinateur local.

  • Si vous pouvez écrire votre code d'entraînement dans un seul script Python, vous pouvez utiliser la classe CustomJob du SDK Agent Platform pour Python pour créer un job personnalisé ou la classe CustomTrainingJob pour créer un TrainingPipeline personnalisé. Votre code d'entraînement est automatiquement empaqueté en tant que distribution source et importé dans Cloud Storage.

  • Pour plus de flexibilité, vous pouvez créer manuellement une image de conteneur personnalisé et la transférer vers Artifact Registry.

Si aucune des options précédentes ne convient à votre cas d'utilisation ou si vous préférez empaqueter manuellement votre application d'entraînement en tant que distribution source, suivez les autres étapes de ce guide.

Avant de commencer

Avant de préparer votre application d'entraînement pour qu'elle s'exécute dans le cloud, procédez comme suit :

  1. Développez votre application d'entraînement à l'aide d'un framework de machine learning (ML) disponible dans l'un des conteneurs prédéfinis d'Agent Platform pour l'entraînement. Assurez-vous que votre application d'entraînement répond aux exigences concernant le code d'entraînement.

    Si vous écrivez l'application d'entraînement à partir de zéro, nous vous recommandons d'organiser votre code en fonction de la structure de l'application décrite dans la section suivante de ce document.

  2. Créez un bucket Cloud Storage dans le projet Google Cloud dans lequel vous prévoyez d'utiliser Agent Platform. Vous allez stocker votre application d'entraînement dans ce bucket. (Bien qu'il soit possible d'utiliser un bucket dans un autre bucketGoogle Cloud , cela nécessite une configuration supplémentaire qui n'est pas abordée dans ce guide.)

    Pour des performances optimales, assurez-vous que le bucket Cloud Storage se trouve à l'emplacement dans lequel vous prévoyez d'utiliser Agent Platform.

  3. Connaissez toutes les bibliothèques Python dont dépend votre application d'entraînement, qu'il s'agisse de dépendances personnalisées ou de bibliothèques disponibles sans frais via PyPI.

Structure de l'application

Lorsque vous effectuez un entraînement sans serveur à l'aide d'un conteneur prédéfini, vous devez spécifier votre code d'entraînement en respectant les conditions suivantes :

  • Fournissez le code sous la forme d'une ou de plusieurs distributions source Python.

    Si vous utilisez l'API Agent Platform pour démarrer un entraînement sans serveur, spécifiez-les dans le champ packageUris.

  • Créez un module dans l'une de ces distributions source qui servira de point d'entrée pour l'entraînement.

    Si vous utilisez l'API Agent Platform pour démarrer un entraînement personnalisé, spécifiez-le dans le champ pythonModule.

Tant que vous remplissez ces conditions, vous pouvez structurer votre application d'entraînement comme vous le souhaitez. Cependant, nous vous recommandons de créer une seule distribution source Python en organisant votre code dans la structure suivante (souvent utilisée dans les exemples Agent Platform) :

  • Utilisez un répertoire de projet principal, contenant votre fichier setup.py. Consultez la section suivante pour obtenir des conseils sur le contenu de ce fichier.

  • Dans le répertoire du projet principal, créez un sous-répertoire nommé trainer/ qui sert de package principal pour votre code d'entraînement.

  • Dans trainer/, créez un module nommé task.py qui sert de point d'entrée pour votre code d'entraînement.

  • Pour accepter trainer/task.py, créez tous les modules Python supplémentaires que vous souhaitez dans le package trainer/ et créez tous les sous-répertoires supplémentaires avec ce code supplémentaire que vous souhaitez dans le répertoire de projet principal.

  • Créez un fichier __init__.py dans chaque sous-répertoire pour en faire un package.

La suite de ce guide part du principe que votre code est organisé conformément à cette structure.

Créer une distribution source

La création d'une distribution source Python est un sujet vaste qui dépasse largement le cadre de cette documentation. Pour plus de commodité, cette section présente l'utilisation de Setuptools pour créer une distribution source à utiliser avec Agent Platform. Vous pouvez utiliser d'autres bibliothèques aux mêmes fins.

  1. Créez un fichier setup.py qui indique à Setuptools comment créer la distribution source. Un setup.py de base comprend 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 votre distribution source.

      • version défini sur le numéro de version de cette version de votre distribution source.

      • install_requires défini sur la liste des dépendances requises par l'application, ainsi que des exigences de version, comme 'docutils>=0.3'

      • La valeur de packages est find_packages(). Cela indique à Setuptools d'inclure tous les sous-répertoires du répertoire parent contenant un fichier __init__.py en tant que packages.

      • La valeur de include_package_data est True.

    L'exemple suivant présente un fichier setup.py de base pour une application d'entraînement :

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

  2. Exécutez la commande suivante pour créer une distribution source, dist/trainer-0.1.tar.gz :

    python setup.py sdist --formats=gztar

Dépendances pour l'application Python

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

Pour chaque instance dupliquée de votre job d'entraînement sans serveur, votre code s'exécute dans un conteneur avec de nombreuses dépendances Python courantes déjà installées. Vérifiez les dépendances incluses dans le conteneur prédéfini que vous prévoyez d'utiliser pour l'entraînement et notez toutes les dépendances qui ne sont pas déjà installées. Il vous suffit de suivre les étapes suivantes pour les dépendances qui ne sont pas déjà installées dans le conteneur prédéfini.

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

  • Les dépendances standards, qui sont des packages de distribution courants disponibles sur PyPI.
  • Dépendances personnalisées : par exemple, packages que vous avez développés vous-même ou packages internes d'une organisation

Les sections suivantes décrivent la procédure pour chaque type.

Dépendances standards (PyPI)

Vous pouvez indiquer les dépendances standards de votre application dans son script setup.py. Agent Platform utilise pip pour installer votre application d'entraînement sur les instances répliquées qu'il alloue à votre job. La commande pip install recherche les dépendances configurées et les installe.

L'exemple suivant montre un setup.py semblable à celui d'une section précédente. Toutefois, ce fichier setup.py indique à Agent Platform d'installer some_PyPI_package lors de l'installation de l'application d'entraînement :

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

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 de la distribution source de chaque dépendance. Les dépendances personnalisées doivent se trouver dans un emplacement Cloud Storage. Agent Platform utilise pip install pour installer des dépendances personnalisées. Elles peuvent ainsi avoir leurs propres dépendances standards dans leurs scripts setup.py.

Chaque URI inclus correspond au chemin d'accès à une distribution source au format tar (.tar.gz) ou wheel (.whl). Agent Platform installe chaque dépendance en utilisant pip install sur chaque instance dupliquée qu'il alloue à votre job d'entraînement.

Si vous utilisez l'API Agent Platform pour démarrer l'entraînement sans serveur, spécifiez les URI Cloud Storage de ces dépendances ainsi que votre application d'entraînement dans le champ packageUris.

Modules Python

Votre 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 une 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 utilisez l'API Agent Platform pour démarrer un entraînement personnalisé, définissez le champ moduleName sur trainer.task.

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

Importer votre distribution source dans Cloud Storage

Vous pouvez utiliser gcloud CLI pour importer votre distribution source et toutes les dépendances personnalisées dans un bucket Cloud Storage. Exemple :

gcloud storage cp dist/trainer-0.1.tar.gz CLOUD_STORAGE_DIRECTORY

Remplacez CLOUD_STORAGE_DIRECTORY par l'URI (commençant par gs:// et se terminant par /) d'un répertoire Cloud Storage dans un bucket auquel votre projetGoogle Cloud peut accéder.

Pour découvrir d'autres façons d'importer votre distribution source dans Cloud Storage, consultez la page Importer des objets dans la documentation de Cloud Storage.

Migrer de python_package_spec vers container_spec

La configuration PythonPackageSpec (executorImageUri) n'accepte que les conteneurs d'entraînement prédéfinis officiellement compatibles. Si votre framework ou votre environnement d'exécution a atteint la fin de sa disponibilité (EOA), comme scikit-learn ou XGBoost, ou si vous avez besoin de versions de Python plus récentes (comme Python 3.11 ou version ultérieure) et de bibliothèques système externes, migrez votre charge de travail d'entraînement pour utiliser ContainerSpec.

Contrairement à python_package_spec, ContainerSpec ne comporte pas de champs package_uris ni python_module.

Pour migrer votre charge de travail vers container_spec, choisissez l'une des approches suivantes :

  • Conserver les packages sur Cloud Storage : transmettez l'URI du package via args ou env à un script de point d'entrée dans votre conteneur qui télécharge le package, l'installe avec pip et exécute python -m <module>.

    Par exemple, dans le script de point d'entrée de votre conteneur :

    #!/usr/bin/env bash
set -e

PACKAGE_URI="$1"
MODULE_NAME="$2"
shift 2

gcloud storage cp "${PACKAGE_URI}" ./package.tar.gz
pip install --no-cache-dir ./package.tar.gz
python -m "${MODULE_NAME}" "$@"

  • Intégrer le code à l'image : vous pouvez également copier les fichiers et les dépendances de votre application d'entraînement directement dans l'image Docker au moment de la compilation (par exemple, avec COPY et pip install dans votre Dockerfile) et définir le point d'entrée directement dans l'image.

Étapes suivantes