Pipelinevorlage erstellen, hochladen und verwenden

Eine Pipelinevorlage ist eine Ressource, mit der Sie eine Workflowdefinition veröffentlichen können, damit sie mehrmals von einem einzelnen Nutzer oder von mehreren Nutzern wiederverwendet werden kann.

Der Kubeflow Pipelines SDK-Registry-Client ist eine neue Clientschnittstelle, die Sie mit einem kompatiblen Registry-Server wie Artifact Registry für die Versionsverwaltung Ihrer KFP-Vorlagen (Kubeflow Pipelines) verwenden können. Weitere Informationen finden Sie unter Vorlage in einem Kubeflow Pipelines SDK-Registry-Client verwenden.

Sie erfahren hier, wie Sie:

Eine KFP-Pipelinevorlage erstellen
Den Registry-Client des Kubeflow Pipelines SDK verwenden, um die Vorlage in ein Pipelinevorlagen-Repository hochzuladen
Im Kubeflow Pipelines-Client die Vorlage verwenden

Vorbereitung

Bevor Sie Ihre Pipeline erstellen und ausführen, folgen Sie der Anleitung unten, um Ihr Google Cloud-Projekt und Ihre Entwicklungsumgebung in der Google Cloud Console einzurichten.

Installieren Sie Version 2 oder höher des Kubeflow Pipelines SDK.
(Optional) Führen Sie vor der Installation den folgenden Befehl aus, um zu sehen, welche Version des Kubeflow Pipelines SDK derzeit installiert ist:
```
  pip freeze | grep kfp
```
Hinweis: Führen Sie den folgenden Befehl aus, um ein Upgrade auf die neueste Version des Kubeflow Pipelines SDK auszuführen:
pip install kfp --upgrade
Wenn eine aktualisierte Version verfügbar ist, deinstalliert dieser Befehl Ihre aktuell installierte Version und installiert die neueste Version.
Installieren Sie Version 1.15.0 oder höher des Vertex AI SDK für Python.
(Optional) Führen Sie vor der Installation den folgenden Befehl aus, um zu sehen, welche Version des Vertex AI SDK für Python derzeit installiert ist:
```
  pip freeze | grep google-cloud-aiplatform
```
Hinweis: Führen Sie den folgenden Befehl aus, um ein Upgrade auf die neueste Version des Vertex AI SDK für Python durchzuführen:
pip install google-cloud-aiplatform --upgrade
Wenn eine aktualisierte Version verfügbar ist, wird durch das Ausführen dieses Befehls die aktuell installierte Version deinstalliert und die neueste Version installiert.
(Optional) Installieren Sie mindestens Version 390.0.0 oder höher der Google Cloud CLI.
Aktivieren Sie die Artifact Registry API.

Berechtigungen konfigurieren

Wenn Sie Ihr gcloud CLI-Projekt noch nicht für Vertex AI Pipelines eingerichtet haben, folgen Sie der Anleitung unter Google Cloud-Projekt für Vertex AI Pipelines konfigurieren.

Weisen Sie außerdem folgende vordefinierte IAM-Berechtigungen (Identity and Access Management) zu, um Artifact Registry als Vorlagen-Registry zu verwenden:

roles/artifactregistry.admin: Diese Rolle erlaubt es, ein Repository zu erstellen und zu verwalten.
roles/artifactregistry.repoAdmin oder roles/artifactregistry.writer: Diese Rolle erlaubt es, Vorlagen in einem Repository zu verwalten.
roles/artifactregistry.reader: Diese Rolle erlaubt es, Vorlagen aus einem Repository herunterzuladen.
roles/artifactregistry.reader: Diese Rolle erlaubt es einem Dienstkonto, das mit Vertex AI Pipelines verknüpft ist, eine Pipeline aus einer Vorlage auszuführen.

Weitere Informationen zu vordefinierten IAM-Rollen (Identitäts- und Zugriffsverwaltung) für Artifact Registry finden Sie unter Vordefinierte Artifact Registry-Rollen.

Im folgenden Beispiel weisen Sie Rollen zu:

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

Ersetzen Sie Folgendes:

PROJECT_ID: Das Projekt, in dem Sie die Pipeline erstellen möchten.
PRINCIPAL: Das Hauptkonto, dem Sie Berechtigungen hinzufügen.
ROLE: Die IAM-Rolle, die Sie dem Hauptkonto zuweisen möchten.

In der Artifact Registry-Dokumentation finden Sie unter Rollen und Berechtigungen weitere Informationen zu folgenden Themen:

Repository in Artifact Registry erstellen

Als Nächstes erstellen Sie in Artifact Registry ein Repository für Ihre Pipelinevorlagen.

Console

Öffnen Sie Vertex AI Pipelines in der Google Cloud Console.

Zu Vertex AI Pipelines
Klicken Sie auf den Tab Meine Vorlagen.
Klicken Sie zum Öffnen des Bereichs Repository auswählen auf Repository auswählen.
Klicken Sie auf Repository erstellen.
Geben Sie quickstart-kfp-repo als Repository-Namen an.
Wählen Sie unter Format die Option Kubeflow Pipelines aus.
Wählen Sie unter Standorttyp die Option Region aus.
Wählen Sie in der Drop-down-Liste Region us-central1 aus.

Hinweis: Die Beispielbefehle und die Konfiguration in dieser Anleitung verwenden us-central1. Sie können aber auch jede andere der unterstützten Regionen verwenden.
Klicken Sie auf Erstellen.

Google Cloud CLI

Führen Sie den folgenden Befehl aus, um ein Repository zu erstellen:

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

LOCATION: Der Standort oder die Region, in der Sie das Repository erstellen möchten, z. B. us-central1.

Führen Sie den Befehl gcloud artifacts repositories create aus:

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

Vorlage erstellen

Im folgenden Codebeispiel wird eine Pipeline mit einer einzelnen Komponente definiert. Informationen zum Definieren einer Pipeline mit KFP finden Sie unter Pipeline erstellen.

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

Wenn Sie das Beispiel ausführen, kompiliert die compiler.Compiler().compile(...)-Anweisung die Pipeline "hello-world" in die lokale YAML-Datei mit dem Namen hello_world_pipeline.yaml.

Vorlage hochladen

Console

Öffnen Sie Vertex AI Pipelines in der Google Cloud Console.

Zu Vertex AI Pipelines
Klicken Sie auf Hochladen, um den Bereich Pipeline oder Komponente hochladen zu öffnen.
Wählen Sie in der Drop-down-Liste Repository das Repository quickstart-kfp-repo aus.
Geben Sie einen Namen für die Pipelinevorlage an.
Klicken Sie im Feld Datei auf Auswählen, um die YAML-Datei der kompilierten Pipelinevorlage aus dem lokalen Dateisystem auszuwählen und hochzuladen.
Nachdem Sie die Pipelinevorlage hochgeladen haben, wird sie auf der Seite Meine Vorlagen aufgeführt.

Zur Seite Meine Vorlagen

Kubeflow Pipelines SDK-Client

Führen Sie die folgenden Befehle aus, um den Registry-Client des Kubeflow Pipelines SDK zu konfigurieren:

from kfp.registry import RegistryClient

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

Laden Sie die kompilierte YAML-Datei in Ihr Repository in Artifact Registry hoch.

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

So überprüfen Sie, ob die Vorlage hochgeladen wurde:
1. Öffnen Sie Vertex AI Pipelines in der Google Cloud Console.
  
  Zu Vertex AI Pipelines
2. Klicken Sie auf den Tab Meine Vorlagen.
3. Klicken Sie auf Repository auswählen.
4. Wählen Sie in der Liste das Repository quickstart-kfp-repo aus und klicken Sie auf Auswählen.
5. Sie sollten das hochgeladene Vorlagenpaket hello-world aus der Liste sehen.
6. Klicken Sie auf die Vorlage hello-world, um eine Liste der Versionen der Pipelinevorlage aufzurufen.
7. Klicken Sie zum Anzeigen der Pipelinetopologie auf die Version.

Vorlage in Vertex AI verwenden

Nachdem Sie Ihre Pipelinevorlage in Ihr Repository in Artifact Registry hochgeladen haben, kann sie in Vertex AI Pipelines verwendet werden.

Staging-Bucket für Ihre Vorlage erstellen

Bevor Sie Ihre Pipelinevorlage verwenden können, müssen Sie einen Cloud Storage-Bucket für die Ausführung von Staging-Pipelines erstellen.

Folgen Sie zum Erstellen des Buckets der Anleitung unter Cloud Storage-Bucket für Pipelineartefakte konfigurieren und führen Sie dann den folgenden Befehl aus:

STAGING_BUCKET="gs://BUCKET_NAME"

Ersetzen Sie BUCKET_NAME durch den Namen des Buckets, den Sie gerade erstellt haben.

Pipeline aus Ihrer Vorlage erstellen

Sie können das Vertex AI SDK für Python oder die Google Cloud Console verwenden, um eine Pipeline aus Ihrer Vorlage in Artifact Registry zu erstellen.

Console

Öffnen Sie Vertex AI Pipelines in der Google Cloud Console.

Zu Vertex AI Pipelines
Klicken Sie auf den Tab Meine Vorlagen.
Klicken Sie zum Öffnen des Bereichs Repository auswählen auf Repository auswählen.
Wählen Sie das Repository quickstart-kfp-repo aus und klicken Sie auf Auswählen.
Klicken Sie auf das Paket hello-world.
Klicken Sie neben der Version 4f245e8f9605 auf Ausführung erstellen.
Klicken Sie auf Laufzeitkonfiguration.
Geben Sie unter Cloud Storage-Speicherort Folgendes ein:
```
gs://BUCKET_NAME
```
Ersetzen Sie dabei BUCKET_NAME durch den Namen des Buckets, den Sie für das Staging der Pipeline erstellt haben.
Klicken Sie auf Senden.

Vertex AI SDK für Python

Im folgenden Beispiel wird eine Pipeline erstellt, die aus Ihrer Vorlage ausgeführt wird:

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

Ersetzen Sie Folgendes:

PROJECT_ID: Das Google Cloud-Projekt, in dem diese Pipeline ausgeführt wird.
SHA256_TAG: Der sha256-Hash-Wert der Vorlagenversion.
TAG: Das Versions-Tag der Vorlage.

Erstellte Pipelineausführungen ansehen

Sie können die von einer bestimmten Pipelineversion erstellten Ausführungen im Vertex AI SDK für Python anzeigen.

Console

Öffnen Sie Vertex AI Pipelines in der Google Cloud Console.

Zu Vertex AI Pipelines
Klicken Sie auf den Tab Meine Vorlagen.
Klicken Sie auf Repository auswählen.
Wählen Sie in der Liste das Repository quickstart-kfp-repo aus und klicken Sie auf Auswählen.
Klicken Sie auf die Vorlage hello world, um die Liste der Versionen für die Pipelinevorlage hello-world aufzurufen.
Klicken Sie auf die gewünschte Version, für die Sie die Pipelineausführungen anzeigen möchten.
Klicken Sie zum Anzeigen der Pipelineausführungen für die ausgewählte Version auf Ausführungen ansehen und dann auf den Tab Ausführungen.

Vertex AI SDK für Python

Führen Sie den Befehl pipelineJobs.list wie in einem oder mehreren der folgenden Beispiele aus, um die Pipelineausführungen aufzulisten:

  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)

Vorlage in einem Kubeflow Pipelines SDK-Registry-Client verwenden

Sie können einen Kubeflow Pipelines SDK-Registry-Client zusammen mit Artifact Registry verwenden, um Ihre Pipelinevorlage herunterzuladen und zu verwenden.

Führen Sie die folgenden Befehle aus, um die Ressourcen im Repository aufzulisten:

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

Eine vollständige Liste der verfügbaren Methoden und Dokumente finden Sie in den proto-Dateien im Artifact Registry-GitHub-Repository.

Führen Sie die folgenden Befehle aus, um die Vorlage in Ihr lokales Dateisystem herunterzuladen:

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

Artifact Registry REST API verwenden

In den folgenden Abschnitten wird zusammengefasst, wie Sie mit der Artifact Registry REST API Ihre Pipelinevorlagen in Ihrem Artifact Registry-Repository verwalten.

Pipelinevorlage mit der Artifact Registry REST API hochladen

Sie können eine Pipelinevorlage hochladen, indem Sie eine HTTP-Anfrage mit den in diesem Abschnitt beschriebenen Parameterwerten erstellen. Dabei gilt:

PROJECT_ID ist das Google Cloud-Projekt, in dem diese Pipeline ausgeführt wird.
REPO_ID ist die ID Ihres Artifact Registry-Repositorys.

Beispiel für eine curl-Anfrage

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

Uploadanfrage erstellen

Die Anfrage ist eine mehrteilige HTTP- oder HTTPS-Anfrage. Sie muss das Authentifizierungstoken im Anfrage-Header enthalten. Weitere Informationen finden Sie unter gcloud auth print-access-token.

Die Nutzlast der Anfrage ist der Inhalt der Datei pipeline_spec.yaml (oder des .zip-Pakets). Empfohlen wird eine Größenbeschränkung von 10 MiB.

Der Paketname wird aus dem Eintrag pipeline_spec.pipeline_info.name in der Datei pipeline_spec.yaml übernommen. Der Paketname identifiziert das Paket eindeutig und ist in allen Versionen gleich. Er kann zwischen 4 und 128 Zeichen lang sein und muss dem folgenden regulären Ausdruck entsprechen: ^[a-z0-9][a-z0-9-]{3,127}$.

Die Paket-tags sind eine Liste von bis zu acht durch Kommas getrennten Tags. Jedes Tag muss dem folgenden regulären Ausdruck entsprechen: ^[a-zA-Z0-9\-._~:@+]{1,128}$.

Wenn ein Tag vorhanden ist und auf eine Pipeline verweist, die bereits hochgeladen wurde, wird das Tag aktualisiert, sodass es auf die Pipeline verweist, die Sie gerade hochladen. Wenn das Tag latest beispielsweise auf eine Pipeline verweist, die Sie bereits hochgeladen haben, und Sie eine neue Version mit --tag=latest hochladen, wird das Tag latest aus der zuvor hochgeladenen Pipeline entfernt und der neuen Pipeline zugewiesen, die Sie hochladen.

Wenn die hochgeladene Pipeline mit einer von Ihnen zuvor hochgeladenen Pipeline identisch ist, ist der Upload erfolgreich. Die Metadaten der hochgeladenen Pipeline, einschließlich ihrer Versions-Tags, werden aktualisiert, damit sie den Parameterwerten Ihrer Uploadanfrage entsprechen.

Uploadantwort

Wenn die Uploadanfrage erfolgreich ist, wird der Status HTTP OK zurückgegeben. Der Antworttext sieht so aus:

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

Dabei ist versionName das sha256-Digest von pipeline_spec.yaml, formatiert als Hexadezimalstring.

Pipelinevorlage mit der Artifact Registry REST API herunterladen

Sie können eine Pipelinevorlage herunterladen, indem Sie eine HTTP-Anfrage mit den in diesem Abschnitt beschriebenen Parameterwerten erstellen. Dabei gilt:

PROJECT_ID ist das Google Cloud-Projekt, in dem diese Pipeline ausgeführt wird.
REPO_ID ist die ID Ihres Artifact Registry-Repositorys.
PACKAGE_ID ist die Paket-ID der hochgeladenen Vorlage.
TAG ist das Versions-Tag.
VERSION ist die Vorlagenversion im Format sha256:abcdef123456....

Für den standardmäßigen Artifact Registry-Download sollten Sie den Download-Link so erstellen:

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

Beispiel-curl-Anfragen

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

Sie können VERSION durch TAG ersetzen und dieselbe Vorlage herunterladen, wie im folgenden Beispiel gezeigt:

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

Downloadantwort

Wenn die Downloadanfrage erfolgreich ist, wird der Status HTTP OK zurückgegeben. Der Antworttext ist der Inhalt der Datei pipeline_spec.yaml.

Referenzlinks

Weitere Informationen zum Verwalten Ihrer Repositories finden Sie unter Artifact Registry – Repository-Übersicht.
Repository API
- Das Format format ist „KFP”.
Paket-API
Versions-API
Tag-API
Proto-Definitionen auf GitHub