Questa pagina è stata tradotta dall'API Cloud Translation.

Crea, carica e utilizza un modello di pipeline

Un modello di pipeline è una risorsa che puoi utilizzare per pubblicare una definizione di flusso di lavoro in modo che possa essere riutilizzata più volte, da un singolo utente o da più utenti.

Il client del registro di Kubeflow Pipelines SDK è una nuova interfaccia client che puoi utilizzare con un server di registro compatibile, come Artifact Registry, per il controllo della versione dei tuoi modelli Kubeflow Pipelines (KFP). Per maggiori informazioni, consulta Utilizzare il modello in un client del registro dell'SDK Kubeflow Pipelines.

Questa pagina ti mostra come:

Crea un modello di pipeline KFP
Utilizza il client di registro dell'SDK Kubeflow Pipelines per caricare il modello in un repository di modelli di pipeline
Utilizza il modello nel client Kubeflow Pipelines

Prima di iniziare

Prima di creare ed eseguire la pipeline, segui le istruzioni riportate di seguito per configurare il progetto e l'ambiente di sviluppo Google Cloud nella console Google Cloud.

Installa la versione 2 o successiva dell'SDK Kubeflow Pipelines.
(Facoltativo) Prima dell'installazione, esegui questo comando per verificare quale versione dell'SDK Kubeflow Pipelines è attualmente installata:
```
  pip freeze | grep kfp
```
Nota: per eseguire l'upgrade alla versione più recente dell'SDK Kubeflow Pipelines, esegui questo comando:
pip install kfp --upgrade
Se è disponibile una versione aggiornata, questo comando disinstalla la versione attualmente installata e installa la versione più recente.
Installa la versione 1.15.0 o successiva dell'SDK Vertex AI per Python.
(Facoltativo) Prima dell'installazione, esegui questo comando per verificare quale versione dell'SDK Vertex AI per Python è attualmente installata:
```
  pip freeze | grep google-cloud-aiplatform
```
Nota: per eseguire l'upgrade alla versione più recente dell'SDK Vertex AI per Python, esegui questo comando:
pip install google-cloud-aiplatform --upgrade
Se è disponibile una versione aggiornata, questo comando disinstalla la versione attualmente installata e installa la versione più recente.
(Facoltativo) Installa la versione 390.0.0 o una versione successiva di Google Cloud CLI.
Abilita l'API Artifact Registry.

Configurazione delle autorizzazioni

Se non hai ancora configurato il progetto gcloud CLI per Vertex AI Pipelines, segui le istruzioni in Configurare il progetto Google Cloud per Vertex AI Pipelines.

Inoltre, assegna le seguenti autorizzazioni predefinite di Identity and Access Management per utilizzare Artifact Registry come registro dei modelli:

roles/artifactregistry.admin: assegna questo ruolo per creare e gestire un repository.
roles/artifactregistry.repoAdmin o roles/artifactregistry.writer: assegna uno di questi ruoli per gestire i modelli all'interno di un repository.
roles/artifactregistry.reader: assegna questo ruolo per scaricare i modelli da un repository.
roles/artifactregistry.reader: assegna questo ruolo a un account di servizio associato a Vertex AI Pipelines per creare un'esecuzione della pipeline da un modello.

Per saperne di più sui ruoli predefiniti di Identity and Access Management per Artifact Registry, consulta Ruoli predefiniti di Artifact Registry.

Utilizza il seguente esempio per assegnare i ruoli:

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

Sostituisci quanto segue:

PROJECT_ID: il progetto in cui vuoi creare la pipeline.
PRINCIPAL: l'entità a cui stai aggiungendo le autorizzazioni.
ROLE: il ruolo Identity and Access Management che vuoi concedere all'entità.

Consulta Ruoli e autorizzazioni nella documentazione di Artifact Registry per saperne di più su quanto segue:

Crea un repository in Artifact Registry

A questo punto, creerai un repository in Artifact Registry per i tuoi modelli di pipeline.

Console

Apri Vertex AI Pipelines nella console Google Cloud.

Vai a Vertex AI Pipelines
Fai clic sulla scheda I tuoi modelli.
Per aprire il riquadro Seleziona repository, fai clic su Seleziona repository.
Fai clic su Crea repository.
Specifica quickstart-kfp-repo come nome del repository.
In Formato, seleziona Kubeflow Pipelines.
In Tipo di località, seleziona Regione.
Nell'elenco a discesa Regione, seleziona us-central1.

Nota: i comandi e la configurazione di esempio in queste istruzioni utilizzano us-central1, ma puoi usare qualsiasi regione supportata.
Fai clic su Crea.

Google Cloud CLI

Esegui questo comando per creare un repository.

Prima di utilizzare uno qualsiasi dei dati di comando riportati di seguito, effettua le seguenti sostituzioni:

LOCATION: la località o la regione in cui vuoi creare il repository, ad esempio us-central1

Esegui il comando gcloud artefatti repository create:

Linux, macOS o 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

Crea un modello

Utilizza il seguente esempio di codice per definire una pipeline con un singolo componente. Per informazioni su come definire una pipeline utilizzando KFP, consulta Creare una 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')

Quando esegui l'esempio, l'istruzione compiler.Compiler().compile(...) compila la pipeline "hello-world" nel file YAML locale denominato hello_world_pipeline.yaml.

Carica il modello

Console

Apri Vertex AI Pipelines nella console Google Cloud.

Vai a Vertex AI Pipelines
Fai clic su Carica per aprire il riquadro Carica pipeline o componente.
Nell'elenco a discesa Repository, seleziona il repository quickstart-kfp-repo.
Specifica un nome per il modello di pipeline.
Nel campo File, fai clic su Scegli per selezionare e caricare il modello YAML della pipeline compilato dal tuo file system locale.
Una volta caricato, il modello di pipeline viene elencato nella pagina I tuoi modelli.

Vai a I tuoi modelli

Client dell'SDK Kubeflow Pipelines

Per configurare il client del registro dell'SDK Kubeflow Pipelines, esegui questi comandi:

from kfp.registry import RegistryClient

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

Carica il file YAML compilato nel tuo repository in 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."})

Per verificare che il modello sia stato caricato:
1. Apri Vertex AI Pipelines nella console Google Cloud.
  
  Vai a Vertex AI Pipelines
2. Fai clic sulla scheda I tuoi modelli.
3. Fai clic su Seleziona repository.
4. Seleziona il repository quickstart-kfp-repo dall'elenco e fai clic su Seleziona.
5. Nell'elenco dovresti trovare il pacchetto di modello caricato hello-world.
6. Per visualizzare l'elenco delle versioni del modello di pipeline, fai clic sul modello hello-world.
7. Per visualizzare la topologia della pipeline, fai clic sulla versione.

Utilizza il modello in Vertex AI

Dopo aver caricato il modello di pipeline nel repository in Artifact Registry, è pronto per essere utilizzato in Vertex AI Pipelines.

Crea un bucket gestione temporanea per il tuo modello

Prima di poter utilizzare il modello di pipeline, devi creare un bucket Cloud Storage per le esecuzioni temporanee della pipeline.

Per creare il bucket, segui le istruzioni in Configurare un bucket Cloud Storage per gli artefatti della pipeline ed esegui questo comando:

STAGING_BUCKET="gs://BUCKET_NAME"

Sostituisci BUCKET_NAME con il nome del bucket appena creato.

Crea un'esecuzione della pipeline dal tuo modello

Puoi utilizzare l'SDK Vertex AI per Python o la console Google Cloud per creare una pipeline eseguita dal tuo modello in Artifact Registry.

Console

Apri Vertex AI Pipelines nella console Google Cloud.

Vai a Vertex AI Pipelines
Fai clic sulla scheda I tuoi modelli.
Per aprire il riquadro Seleziona repository, fai clic su Seleziona repository.
Seleziona il repository quickstart-kfp-repo, quindi fai clic su Seleziona.
Fai clic sul pacchetto hello-world.
Accanto alla versione di 4f245e8f9605, fai clic su Crea esecuzione.
Fai clic su Configurazione runtime.
Inserisci quanto segue in Posizione Cloud Storage:
```
gs://BUCKET_NAME
```
Sostituisci BUCKET_NAME con il nome del bucket che hai creato per la gestione temporanea della pipeline.
Fai clic su Invia.

SDK Vertex AI per Python

Utilizza il seguente esempio per creare un'esecuzione della pipeline dal tuo modello:

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()

Sostituisci quanto segue:

PROJECT_ID: il progetto Google Cloud in cui viene eseguita questa pipeline.
SHA256_TAG: il valore hash sha256 della versione del modello.
TAG: il tag della versione del modello.

Visualizza le esecuzioni della pipeline create

Puoi visualizzare le esecuzioni create da una versione specifica della pipeline nell'SDK Vertex AI per Python.

Console

Apri Vertex AI Pipelines nella console Google Cloud.

Vai a Vertex AI Pipelines
Fai clic sulla scheda I tuoi modelli.
Fai clic su Seleziona repository.
Seleziona il repository quickstart-kfp-repo dall'elenco e fai clic su Seleziona.
Per visualizzare l'elenco delle versioni per il modello di pipeline hello-world, fai clic sul modello hello world.
Fai clic sulla versione per cui vuoi visualizzare le esecuzioni della pipeline.
Per visualizzare le esecuzioni della pipeline per la versione selezionata, fai clic su Visualizza esecuzioni, quindi sulla scheda Esecuzioni.

SDK Vertex AI per Python

Per elencare le esecuzioni delle pipeline, esegui il comando pipelineJobs.list come mostrato in uno o più dei seguenti esempi:

  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)

Utilizza il modello in un client del registro dell'SDK Kubeflow Pipelines

Puoi utilizzare un client di registro dell'SDK Kubeflow Pipelines insieme ad Artifact Registry per scaricare e utilizzare il tuo modello di pipeline.

Per elencare le risorse nel repository, esegui questi comandi:

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")

Per l'elenco completo dei metodi e dei documenti disponibili, consulta i file proto nel repository GitHub di Artifact Registry.

Per scaricare il modello nel file system locale, esegui questi comandi:

# 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")

Utilizzare l'API REST Artifact Registry

Le seguenti sezioni riassumono come utilizzare l'API REST di Artifact Registry per gestire i modelli di pipeline nel tuo repository Artifact Registry.

Carica un modello di pipeline utilizzando l'API REST Artifact Registry

Puoi caricare un modello di pipeline creando una richiesta HTTP utilizzando i valori parametro descritti in questa sezione, dove:

PROJECT_ID è il progetto Google Cloud in cui viene eseguita questa pipeline.
REPO_ID è l'ID del repository Artifact Registry.

Esempio di richiesta 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

Creazione della richiesta di caricamento in corso...

La richiesta è una richiesta multiparte HTTP o HTTPS. Deve includere il token di autenticazione nell'intestazione della richiesta. Per ulteriori informazioni, consulta gcloud auth print-access-token.

Il payload della richiesta è il contenuto del file pipeline_spec.yaml (o del pacchetto .zip). Il limite di dimensioni consigliato è 10 MiB.

Il nome del pacchetto viene recuperato dalla voce pipeline_spec.pipeline_info.name nel file pipeline_spec.yaml. Il nome del pacchetto identifica in modo univoco il pacchetto ed è immutabile tra le versioni. Può avere una lunghezza compresa tra 4 e 128 caratteri e deve corrispondere alla seguente espressione regolare: ^[a-z0-9][a-z0-9-]{3,127}$.

Il pacchetto tags è un elenco di massimo otto tag separati da virgole. Ogni tag deve corrispondere alla seguente espressione regolare: ^[a-zA-Z0-9\-._~:@+]{1,128}$.

Se un tag esiste e rimanda a una pipeline già caricata, il tag viene aggiornato in modo che punti alla pipeline in fase di caricamento. Ad esempio, se il tag latest rimanda a una pipeline già caricata e carichi una nuova versione con --tag=latest, il tag latest viene rimosso dalla pipeline caricata in precedenza e assegnato alla nuova pipeline in fase di caricamento.

Se la pipeline che stai caricando è identica a una pipeline caricata in precedenza, il caricamento viene eseguito correttamente. I metadati della pipeline caricata, inclusi i relativi tag di versione, vengono aggiornati in modo che corrispondano ai valori dei parametri della richiesta di caricamento.

Carica risposta

Se la richiesta di caricamento ha esito positivo, viene restituito lo stato HTTP OK. Il corpo della risposta è il seguente:

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

dove versionName è il digest sha256 di pipeline_spec.yaml formattato come stringa esadecimale.

Scarica un modello di pipeline utilizzando l'API REST Artifact Registry

Puoi scaricare un modello di pipeline creando una richiesta HTTP utilizzando i valori parametro descritti in questa sezione, dove:

PROJECT_ID è il progetto Google Cloud in cui viene eseguita questa pipeline.
REPO_ID è l'ID del repository Artifact Registry.
PACKAGE_ID è l'ID pacchetto del modello caricato.
TAG è il tag della versione.
VERSION è la versione del modello nel formato sha256:abcdef123456....

Per il download standard di Artifact Registry, devi creare il link di download come segue:

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

Esempi di richieste 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

Puoi sostituire VERSION con TAG e scaricare lo stesso modello, come mostrato nell'esempio seguente:

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

Scarica risposta

Se la richiesta di download ha esito positivo, viene restituito lo stato HTTP OK. Il corpo della risposta è il contenuto del file pipeline_spec.yaml.

Link di riferimento

Artifact Registry - Panoramica del repository per ulteriori informazioni su come gestire i repository.
API repository
- La parola chiave format è "KFP"
API Package
API Version
API Tag
Definizioni dei protocollo su GitHub