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.

1. 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
   

2. 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
   

3. (Optional) Installieren Sie mindestens Version 390.0.0 oder höher der Google Cloud CLI.

4. 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:

• Projektweite Berechtigungen gewähren
• Repository-spezifische Berechtigungen erteilen
• Einzelnen Nutzern IAM-Rollen zuweisen

Repository in Artifact Registry erstellen

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

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

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

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

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.

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="http://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="http://us-central1-kfp.pkg.dev/PROJECT_ID/quickstart-kfp-repo/hello-world:TAG")

job.submit()

Erstellte Pipelineausführungen ansehen

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

  from google.cloud import aiplatform

  # To filter all runs created from a specific version
  filter = 'template_uri:"http://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="http://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:"http://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:"http://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 \
    http://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 = http://us-central1-kfp.pkg.dev/PROJECT_ID/REPO_ID/PACKAGE_ID/VERSION
url = http://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)" \
    http://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)" \
    http://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