Créer, importer et utiliser un modèle de pipeline

Un modèle de pipeline est une ressource que vous pouvez utiliser pour publier une définition de workflow afin de pouvoir la réutiliser plusieurs fois, par un seul utilisateur ou par plusieurs utilisateurs.

Le client de registre du SDK Kubeflow Pipelines est une nouvelle interface cliente que vous pouvez utiliser avec un serveur de registre compatible, tel qu'Artifact Registry, pour le contrôle des versions de vos modèles Kubeflow Pipelines (KFP). Pour en savoir plus, consultez la section Utiliser le modèle dans un client de registre du SDK Kubeflow Pipelines.

Cette page vous explique comment :

Créer un modèle de pipeline KFP
Utiliser le client de registre du SDK Kubeflow Pipelines pour importer le modèle dans un dépôt de modèle de pipeline
Utiliser le modèle dans le client Kubeflow Pipelines

Avant de commencer

Avant de créer et d'exécuter votre pipeline, suivez les instructions ci-dessous pour configurer votre projet et votre environnement de développement Google Cloud dans la console Google Cloud.

Installez la version 2 ou une version ultérieure du SDK Kubeflow Pipelines.
(Facultatif) Avant l'installation, exécutez la commande suivante pour voir quelle version du SDK Kubeflow Pipelines est actuellement installée :
```
  pip freeze | grep kfp
```
Remarque : Pour passer à la dernière version du SDK Kubeflow Pipelines, exécutez la commande suivante :
pip install kfp --upgrade
Si une version mise à jour est disponible, l'exécution de cette commande désinstalle la version actuellement installée et installe la dernière version.
Installez la version 1.15.0 ou une version ultérieure du SDK Vertex AI pour Python.
(Facultatif) Avant l'installation, exécutez la commande suivante pour connaître la version du SDK Vertex AI pour Python actuellement installée :
```
  pip freeze | grep google-cloud-aiplatform
```
Remarque : Pour passer à la dernière version du SDK Vertex AI pour Python, exécutez la commande suivante :
pip install google-cloud-aiplatform --upgrade
Si une version mise à jour est disponible, l'exécution de cette commande va désinstaller la version actuellement installée et installer la dernière version.
(Facultatif) Installez la version 390.0.0 ou une version ultérieure de Google Cloud CLI.
Activez l'API Artifact Registry.

Configurer des autorisations

Si vous n'avez pas encore configuré votre projet gcloud CLI pour Vertex AI Pipelines, suivez les instructions de la section Configurer votre projet Google Cloud pour Vertex AI Pipelines.

Attribuez également les autorisations prédéfinies IAM suivantes pour utiliser Artifact Registry en tant que registre de modèles :

roles/artifactregistry.admin : attribuez ce rôle pour créer et gérer un dépôt.
roles/artifactregistry.repoAdmin ou roles/artifactregistry.writer : attribuez l'un de ces rôles pour gérer les modèles dans un dépôt.
roles/artifactregistry.reader : attribuez ce rôle pour télécharger des modèles à partir d'un dépôt.
roles/artifactregistry.reader : attribuez ce rôle à un compte de service associé à Vertex AI Pipelines pour créer une exécution de pipeline à partir d'un modèle.

Pour en savoir plus sur les rôles Identity and Access Management prédéfinis pour Artifact Registry, consultez la section Rôles Artifact Registry prédéfinis.

Utilisez l'exemple suivant pour attribuer des rôles :

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL \
    --role=ROLE

Remplacez les éléments suivants :

PROJECT_ID : projet dans lequel vous souhaitez créer le pipeline
PRINCIPAL : compte principal auquel vous ajoutez des autorisations
ROLE : rôle de gestion de l'authentification et des accès que vous souhaitez attribuer au compte principal

Consultez la section Rôles et autorisations de la documentation Artifact Registry pour en savoir plus sur les éléments suivants :

Créer un dépôt dans Artifact Registry

Vous allez ensuite créer un dépôt dans Artifact Registry pour vos modèles de pipeline.

Console

Ouvrez Vertex AI Pipelines dans la console Google Cloud.

Accéder à Vertex AI Pipelines
Cliquez sur l'onglet Vos modèles.
Pour ouvrir le volet Sélectionner un dépôt, cliquez sur Sélectionner un dépôt.
Cliquez sur Créer un dépôt.
Spécifiez quickstart-kfp-repo comme nom de dépôt.
Sous Format, sélectionnez Kubeflow Pipelines.
Sous Type d'emplacement, sélectionnez Région.
Dans la liste déroulante Région, sélectionnez us-central1.

Remarque : Les exemples de commandes et de configuration fournis dans ces instructions utilisent us-central1, mais vous pouvez utiliser n'importe quelle région compatible.
Cliquez sur Créer.

Google Cloud CLI

Exécutez la commande suivante pour créer un fichier.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

LOCATION : emplacement ou région dans lequel vous souhaitez créer le dépôt, par exemple us-central1

Exécutez la commande gcloud artifacts repositories create :

Linux, macOS ou Cloud Shell

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Windows (PowerShell)

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Windows (cmd.exe)

gcloud artifacts repositories create quickstart-kfp-repo --location=LOCATION_ID --repository-format=KFP

Créer un modèle

Utilisez l'exemple de code suivant pour définir un pipeline avec un seul composant. Pour plus d'informations sur la définition d'un pipeline à l'aide de KFP, consultez la page Construire un pipeline.

from kfp import dsl
from kfp import compiler

@dsl.component()
def hello_world(text: str) -> str:
    print(text)
    return text

@dsl.pipeline(name='hello-world', description='A simple intro pipeline')
def pipeline_hello_world(text: str = 'hi there'):
    """Pipeline that passes small pipeline parameter string to consumer op."""

    consume_task = hello_world(
        text=text)  # Passing pipeline parameter as argument to consumer op

compiler.Compiler().compile(
    pipeline_func=pipeline_hello_world,
    package_path='hello_world_pipeline.yaml')

Lorsque vous exécutez l'exemple, l'instruction compiler.Compiler().compile(...) compile le pipeline "hello-world" dans le fichier YAML local nommé hello_world_pipeline.yaml.

Importer le modèle

Console

Ouvrez Vertex AI Pipelines dans la console Google Cloud.

Accéder à Vertex AI Pipelines
Cliquez sur Importer pour ouvrir le volet Importer un pipeline ou un composant.
Dans la liste déroulante Dépôt, sélectionnez le dépôt quickstart-kfp-repo.
Renseignez un nom pour le modèle de pipeline.
Dans le champ Fichier, cliquez sur Choisir pour sélectionner et importer le modèle YAML de pipeline compilé à partir de votre système de fichiers local.
Une fois le modèle de pipeline importé, il est répertorié sur la page Vos modèles.

Accéder à Vos modèles

Client du SDK Kubeflow Pipelines

Pour configurer votre client de registre du SDK Kubeflow Pipelines, exécutez les commandes suivantes :

from kfp.registry import RegistryClient

client = RegistryClient(host=f"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo")

Importez le fichier YAML compilé dans votre dépôt dans Artifact Registry.

templateName, versionName = client.upload_pipeline(
  file_name="hello_world_pipeline.yaml",
  tags=["v1", "latest"],
  extra_headers={"description":"This is an example pipeline template."})

Pour vérifier que le modèle a été importé, procédez comme suit :
1. Ouvrez Vertex AI Pipelines dans la console Google Cloud.
  
  Accéder à Vertex AI Pipelines
2. Cliquez sur l'onglet Vos modèles.
3. Cliquez sur Sélectionner un dépôt.
4. Dans la liste, sélectionnez le dépôt quickstart-kfp-repo, puis cliquez sur Sélectionner.
5. Le package de modèle importé hello-world doit s'afficher dans la liste.
6. Pour afficher la liste des versions du modèle de pipeline, cliquez sur le modèle hello-world.
7. Pour afficher la topologie du pipeline, cliquez sur la version.

Utiliser le modèle dans Vertex AI

Une fois que vous avez importé votre modèle de pipeline dans votre dépôt dans Artifact Registry, vous pouvez l'utiliser dans Vertex AI Pipelines.

Créer un bucket de préproduction pour votre modèle

Avant de pouvoir utiliser votre modèle de pipeline, vous devez créer un bucket Cloud Storage pour les exécutions de pipeline de préproduction.

Pour créer le bucket, suivez les instructions de la section Configurer un bucket Cloud Storage pour les artefacts de pipeline, puis exécutez la commande suivante :

STAGING_BUCKET="gs://BUCKET_NAME"

Remplacez BUCKET_NAME par le nom du bucket que vous venez de créer.

Créer une exécution de pipeline à partir de votre modèle

Vous pouvez utiliser le SDK Vertex AI pour Python ou la console Google Cloud pour créer une exécution de pipeline à partir de votre modèle dans Artifact Registry.

Console

Ouvrez Vertex AI Pipelines dans la console Google Cloud.

Accéder à Vertex AI Pipelines
Cliquez sur l'onglet Vos modèles.
Pour ouvrir le volet Sélectionner un dépôt, cliquez sur Sélectionner un dépôt.
Sélectionnez le dépôt quickstart-kfp-repo, puis cliquez sur Sélectionner.
Cliquez sur le package hello-world.
À côté de la version 4f245e8f9605, cliquez sur Créer une exécution.
Cliquez sur Configuration de l'environnement d'exécution.
Saisissez la commande suivante sous Emplacement Cloud Storage :
```
gs://BUCKET_NAME
```
Remplacez BUCKET_NAME par le nom du bucket que vous avez créé pour la préproduction des exécutions du pipeline.
Cliquez sur Envoyer.

SDK Vertex AI pour Python

Utilisez l'exemple suivant pour créer une exécution de pipeline à partir de votre modèle :

from google.cloud import aiplatform

# Initialize the aiplatform package
aiplatform.init(
    project="PROJECT_ID",
    location='us-central1',
    staging_bucket=STAGING_BUCKET)

# Create a pipeline job using a version ID.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world@SHA256_TAG" + \
        versionName)

# Alternatively, create a pipeline job using a tag.
job = aiplatform.PipelineJob(
    display_name="hello-world-latest",
    template_path="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/TAG")

job.submit()

Remplacez les éléments suivants :

PROJECT_ID : projet Google Cloud dans lequel ce pipeline s'exécute.
SHA256_TAG : valeur de hachage sha256 de la version du modèle.
TAG : tag de version du modèle.

Afficher les exécutions de pipeline créées

Vous pouvez afficher les exécutions créées par une version de pipeline spécifique dans le SDK Vertex AI pour Python.

Console

Ouvrez Vertex AI Pipelines dans la console Google Cloud.

Accéder à Vertex AI Pipelines
Cliquez sur l'onglet Vos modèles.
Cliquez sur Sélectionner un dépôt.
Dans la liste, sélectionnez le dépôt quickstart-kfp-repo, puis cliquez sur Sélectionner.
Pour afficher la liste des versions du modèle de pipeline hello-world, cliquez sur le modèle hello world.
Cliquez sur la version pour laquelle vous souhaitez afficher les exécutions du pipeline.
Pour afficher les exécutions du pipeline pour la version sélectionnée, cliquez sur Afficher les exécutions, puis sur l'onglet Exécutions.

SDK Vertex AI pour Python

Pour lister les exécutions des pipelines, exécutez la commande pipelineJobs.list comme indiqué dans un ou plusieurs des exemples suivants :

  from google.cloud import aiplatform

  # To filter all runs created from a specific version
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/*" AND ' + \
           'template_metadata.version="%s"' % versionName
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a specific version tag
  filter = 'template_uri="https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/latest"'
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a package
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world/*"'
  aiplatform.PipelineJob.list(filter=filter)

  # To filter all runs created from a repo
  filter = 'template_uri:"https://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/*"'
  aiplatform.PipelineJob.list(filter=filter)

Utiliser le modèle dans un client de registre du SDK Kubeflow Pipelines

Vous pouvez utiliser un client de registre du SDK Kubeflow Pipelines avec Artifact Registry pour télécharger et utiliser votre modèle de pipeline.

Pour lister les ressources dans le dépôt, exécutez les commandes suivantes :

templatePackages = client.list_packages()
templatePackage = client.get_package(package_name = "hello-world")

versions = client.list_versions(package_name="hello-world")
version = client.get_version(package_name="hello-world", version=versionName)

tags = client.list_tags(package_name = "hello-world")
tag = client.get_tag(package_name = "hello-world", tag="latest")

Pour obtenir la liste complète des méthodes et documents disponibles, consultez les fichiers proto dans le dépôt GitHub d'Artifact Registry.

Pour télécharger le modèle sur votre système de fichiers local, exécutez les commandes suivantes :

# Sample 1
filename = client.download_pipeline(
  package_name = "hello-world",
  version = versionName)
# Sample 2
filename = client.download_pipeline(
  package_name = "hello-world",
  tag = "v1")
# Sample 3
filename = client.download_pipeline(
  package_name = "hello-world",
  tag = "v1",
  file_name = "hello-world-template.yaml")

Utiliser l'API REST Artifact Registry

Les sections suivantes récapitulent comment utiliser l'API REST Artifact Registry pour gérer vos modèles de pipeline dans votre dépôt Artifact Registry.

Importer un modèle de pipeline à l'aide de l'API REST Artifact Registry

Vous pouvez importer un modèle de pipeline en créant une requête HTTP à l'aide des valeurs de paramètre décrites dans cette section, où :

PROJECT_ID est le projet Google Cloud dans lequel ce pipeline s'exécute.
REPO_ID est l'ID de votre dépôt Artifact Registry.

Exemple de requête curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -F tags=v1,latest \
    -F content=@pipeline_spec.yaml \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID

Construire la requête d'importation

La requête est une requête HTTP ou HTTPS en plusieurs parties. Elle doit inclure le jeton d'authentification dans l'en-tête de la requête. Pour en savoir plus, consultez la section gcloud auth print-access-token.

La charge utile de la requête correspond au contenu du fichier pipeline_spec.yaml (ou du package au format .zip). La taille maximale recommandée est de 10 Mio.

Le nom du package provient de l'entrée pipeline_spec.pipeline_info.name du fichier pipeline_spec.yaml. Le nom du package l'identifie de manière unique et est immuable entre les versions. Il peut comporter entre 4 et 128 caractères et doit correspondre à l'expression régulière suivante : ^[a-z0-9][a-z0-9-]{3,127}$

Les tags du package sont une liste allant jusqu'à huit tags séparés par des virgules. Chaque tag doit correspondre à l'expression régulière suivante : ^[a-zA-Z0-9\-._~:@+]{1,128}$.

Si un tag existe et pointe vers un pipeline déjà importé, le tag est mis à jour pour pointer vers le pipeline que vous importez actuellement. Par exemple, si le tag latest pointe vers un pipeline que vous avez déjà importé, et que vous importez une nouvelle version avec --tag=latest, le tag latest est supprimé du fichier importé précédemment et attribué au nouveau pipeline que vous importez actuellement.

Si le pipeline que vous importez est identique à un pipeline que vous avez précédemment importé, l'importation aboutit. Les métadonnées du pipeline importé, y compris ses tags de version, sont mises à jour pour correspondre aux valeurs des paramètres de votre requête d'importation.

Réponse d'importation

Si la requête d'importation aboutit, elle renvoie un état HTTP OK. Le corps de la réponse est le suivant :

{packageName}/{versionName=sha256:abcdef123456...}

où versionName est le condensé sha256 de pipeline_spec.yaml au format de chaîne hexadécimale.

Télécharger un modèle de pipeline à l'aide de l'API REST Artifact Registry

Vous pouvez télécharger un modèle de pipeline en créant une requête HTTP à l'aide des valeurs de paramètre décrites dans cette section, où :

PROJECT_ID est le projet Google Cloud dans lequel ce pipeline s'exécute.
REPO_ID est l'ID de votre dépôt Artifact Registry.
PACKAGE_ID est l'ID de package de votre modèle importé.
TAG est le tag de version.
VERSION est la version du modèle au format sha256:abcdef123456....

Pour le téléchargement standard d'Artifact Registry, vous devez former le lien de téléchargement comme suit :

url = https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION
url = https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/TAG

Exemples de requêtes curl

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION

Vous pouvez remplacer VERSION par TAG et télécharger le même modèle, comme indiqué dans l'exemple suivant :

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/TAG

Télécharger la réponse

Si la requête de téléchargement aboutit, elle renvoie un état HTTP OK. Le corps de la réponse est constitué du contenu du fichier pipeline_spec.yaml.

Liens référents

Artifact Registry : Présentation du dépôt pour plus d'informations sur la gestion de vos dépôts.
API Repository
- Le mot clé de format est "KFP"
API Package
API Version
API Tag
Définitions proto sur GitHub