Membuat, mengupload, dan menggunakan template pipeline

Template pipeline adalah resource yang dapat Anda gunakan untuk memublikasikan definisi alur kerja sehingga dapat digunakan kembali beberapa kali, oleh satu pengguna atau oleh beberapa pengguna.

Klien registry Kubeflow Pipelines SDK adalah antarmuka klien baru yang dapat digunakan dengan server registry yang kompatibel, seperti Artifact Registry, untuk kontrol versi template Kubeflow Pipelines (KFP). Untuk informasi selengkapnya, lihat Menggunakan template di klien registry Kubeflow Pipelines SDK.

Halaman ini menunjukkan cara:

• Membuat template pipeline KFP
• Menggunakan klien registry Kubeflow Pipelines SDK untuk mengupload template ke repositori template pipeline
• Menggunakan template di klien Kubeflow Pipeline

Sebelum memulai

Sebelum Anda membangun dan menjalankan pipeline, gunakan petunjuk berikut untuk menyiapkan project Google Cloud dan lingkungan pengembangan Anda di konsol Google Cloud.

1. Instal Kubeflow Pipelines SDK v2 atau yang lebih baru.

   pip install --upgrade kfp>=2,<3
   

Catatan: Untuk mengupgrade ke Kubeflow Pipelines SDK versi terbaru, jalankan perintah berikut:
pip install kfp --upgrade
Jika versi terbaru tersedia, menjalankan perintah ini akan meng-uninstal KFP dan menginstal versi terbaru.

Perhatian: Vertex AI Pipelines mendukung Kubeflow Pipelines SDK v1.8, tetapi sebaiknya Anda menginstal v2 atau yang lebih baru untuk menggunakan contoh kode dalam dokumentasi.

1. Instal Vertex AI SDK untuk Python v1.15.0 atau yang lebih baru.
   (Opsional) Sebelum menginstal, jalankan perintah berikut untuk melihat versi Vertex AI SDK untuk Python yang saat ini terinstal:

     pip freeze | grep google-cloud-aiplatform
   

   Catatan: Untuk mengupgrade Vertex AI SDK untuk Python ke versi terbaru, jalankan perintah berikut:
   pip install google-cloud-aiplatform --upgrade
   Jika versi terbaru tersedia, menjalankan perintah ini akan meng-uninstal versi yang saat ini sudah terinstal dan menginstal versi terbaru.

2. (Opsional) Instal Google Cloud CLI 390.0.0 atau yang lebih baru.

3. Aktifkan Artifact Registry API.

Mengonfigurasi izin

Jika Anda belum menyiapkan project gcloud CLI untuk Vertex AI Pipelines, ikuti petunjuk di Mengonfigurasi project Google Cloud untuk Vertex AI Pipelines.

Selain itu, tetapkan izin Identity and Access Management yang telah ditentukan berikut agar dapat menggunakan Artifact Registry sebagai registry template:

• roles/artifactregistry.admin: Menetapkan peran ini untuk membuat dan mengelola repositori.
• roles/artifactregistry.repoAdmin atau roles/artifactregistry.writer: Menetapkan salah satu peran berikut untuk mengelola template di dalam repositori.
• roles/artifactregistry.reader: Menetapkan peran ini untuk mendownload template dari repositori.
• roles/artifactregistry.reader: Menetapkan peran ini ke akun layanan yang terkait dengan Vertex AI Pipelines untuk membuat pipeline yang dijalankan dari template.

Untuk mengetahui informasi selengkapnya tentang peran Identity and Access Management yang telah ditetapkan untuk Artifact Registry, lihat peran Artifact Registry yang ditetapkan sebelumnya.

Gunakan contoh berikut untuk menetapkan peran:

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

Ganti kode berikut:

• PROJECT_ID: Project tempat Anda ingin membuat pipeline.
• PRINCIPAL: Akun utama tempat Anda menambahkan izin.
• ROLE: Peran Identity and Access Management yang ingin Anda berikan kepada akun utama.

Lihat Peran dan izin di dokumentasi Artifact Registry untuk informasi selengkapnya tentang hal berikut:

• Memberikan izin di seluruh project
• Memberikan izin khusus repositori
• Memberikan peran Identity and Access Management dasar kepada pengguna perorangan

Membuat repositori di Artifact Registry

Selanjutnya, Anda akan membuat repositori di Artifact Registry untuk template pipeline.

Konsol

1. Buka Vertex AI Pipelines di konsol Google Cloud.

   Buka Vertex AI Pipelines

2. Klik tab Template Anda.

3. Untuk membuka panel Pilih repositori, klik Pilih repositori.

4. Klik Buat repositori.

5. Tentukan quickstart-kfp-repo sebagai nama repositori.

6. Di bagian Format, pilih Kubeflow Pipelines.

7. Di bagian Jenis Lokasi, pilih Region.

8. Di menu drop-down Region, pilih us-central1.

   Catatan: Contoh perintah dan konfigurasi dalam petunjuk ini menggunakan us-central1, tetapi Anda dapat menggunakan region yang didukung.

9. Klik Buat.

Google Cloud CLI

Jalankan perintah berikut untuk membuat repositori.

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

• LOCATION: Lokasi atau region tempat Anda ingin membuat repositori, misalnya, us-central1

Jalankan perintah gcloud artifacts repositories create:

Linux, macOS, atau Cloud Shell

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Windows (PowerShell)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Windows (cmd.exe)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

 

Membuat template

Gunakan contoh kode berikut untuk menentukan pipeline dengan komponen tunggal. Untuk informasi tentang cara menentukan pipeline menggunakan KFP, lihat Membangun 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')

Saat Anda menjalankan contoh tersebut, pernyataan compiler.Compiler().compile(...) akan mengompilasi pipeline "hello-world" ke dalam file YAML lokal bernama hello_world_pipeline.yaml.

Mengupload template

Konsol

1. Buka Vertex AI Pipelines di konsol Google Cloud.

   Buka Vertex AI Pipelines

2. Klik Upload untuk membuka panel Upload pipeline atau komponen.

3. Di menu drop-down Repositori, pilih repositori quickstart-kfp-repo.

4. Tentukan Nama untuk template pipeline.

5. Di kolom File, klik Pilih untuk memilih dan mengupload YAML template pipeline yang dikompilasi dari sistem file lokal Anda.

6. Setelah diupload, template pipeline akan tercantum di halaman Template Anda.

   Buka Template Anda

Klien Kubeflow Pipelines SDK

1. Untuk mengonfigurasi klien registry Kubeflow Pipelines SDK, jalankan perintah berikut:

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

2. Upload file YAML yang dikompilasi ke repositori Anda di 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."})
   

3. Untuk memverifikasi bahwa template telah diupload:

   1. Buka Vertex AI Pipelines di konsol Google Cloud.

      Buka Vertex AI Pipelines

   2. Klik tab Template Anda.

   3. Klik Pilih repositori.

   4. Dari daftar, pilih repositori quickstart-kfp-repo, lalu klik Pilih.

   5. Anda akan menemukan paket template yang diupload hello-world dari daftar.

   6. Untuk melihat daftar versi template pipeline, klik template hello-world.

   7. Untuk melihat topologi pipeline, klik versi.

Menggunakan template di Vertex AI

Setelah mengupload template pipeline ke repositori Anda di Artifact Registry, template pipeline siap digunakan di Vertex AI Pipelines.

Membuat bucket staging untuk template

Sebelum dapat menggunakan template pipeline, Anda harus membuat bucket Cloud Storage untuk staging operasi pipeline.

Untuk membuat bucket, ikuti petunjuk di bagian Mengonfigurasi bucket Cloud Storage untuk artefak pipeline, lalu jalankan perintah berikut:

STAGING_BUCKET="gs://BUCKET_NAME"

Ganti BUCKET_NAME dengan nama bucket yang baru saja Anda buat.

Membuat pipeline yang dijalankan dari template Anda

Anda dapat menggunakan Vertex AI SDK untuk Python atau konsol Google Cloud untuk membuat pipeline yang dijalankan dari template Anda di Artifact Registry.

Konsol

1. Buka Vertex AI Pipelines di konsol Google Cloud.

   Buka Vertex AI Pipelines

2. Klik tab Template Anda.

3. Untuk membuka panel Pilih repositori, klik Pilih repositori.

4. Pilih repositori quickstart-kfp-repo, lalu klik Pilih.

5. Klik paket hello-world.

6. Di samping versi 4f245e8f9605, klik Buat Operasi.

7. Klik Konfigurasi Runtime.

8. Masukkan perintah berikut di bagian Lokasi Cloud Storage:

   gs://BUCKET_NAME
   

   Ganti BUCKET_NAME dengan nama bucket yang Anda buat untuk staging operasi pipeline.

9. Klik Kirim.

Vertex AI SDK untuk Python

Gunakan contoh berikut untuk membuat operasi pipeline dari template Anda:

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

Ganti kode berikut:

• PROJECT_ID: Project Google Cloud tempat pipeline ini berjalan.

• SHA256_TAG: Nilai hash sha256 dari versi template.

• TAG: Tag versi template.

Melihat operasi pipeline yang dibuat

Anda dapat melihat operasi yang dibuat oleh versi pipeline tertentu di Vertex AI SDK untuk Python.

Konsol

1. Buka Vertex AI Pipelines di konsol Google Cloud.

   Buka Vertex AI Pipelines

2. Klik tab Template Anda.

3. Klik Pilih repositori.

4. Dari daftar, pilih repositori quickstart-kfp-repo, lalu klik Pilih.

5. Untuk melihat daftar versi template pipeline hello-world, klik template hello world.

6. Klik versi yang ingin Anda lihat operasi pipelinenya.

7. Untuk melihat operasi pipeline pada versi yang dipilih, klik Lihat Operasi, lalu klik tab Operasi.

Vertex AI SDK untuk Python

Untuk mencantumkan operasi pipeline, jalankan perintah pipelineJobs.list seperti yang ditunjukkan dalam satu atau beberapa contoh berikut:

  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)

Menggunakan template di klien registry Kubeflow Pipelines SDK

Anda dapat menggunakan klien registry Kubeflow Pipelines SDK bersama dengan Artifact Registry untuk mendownload dan menggunakan template pipeline Anda.

• Untuk menampilkan daftar resource dalam repositori, jalankan perintah berikut:

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

  Untuk mengetahui daftar lengkap metode dan dokumen yang tersedia, lihat file proto di repo GitHub Artifact Registry.

• Untuk mendownload template ke sistem file lokal, jalankan perintah berikut:

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

Menggunakan Artifact Registry REST API

Bagian berikut merangkum cara menggunakan Artifact Registry REST API untuk mengelola template pipeline di repositori Artifact Registry.

Mengupload template pipeline menggunakan Artifact Registry REST API

Anda dapat mengupload template pipeline dengan membuat permintaan HTTP menggunakan parameter value yang dijelaskan di bagian ini, dengan:

• PROJECT_ID: Project Google Cloud tempat pipeline ini berjalan.
• REPO_ID adalah ID repositori Artifact Registry Anda.

Contoh permintaan 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

Membuat permintaan upload

Permintaan adalah permintaan multibagian HTTP atau HTTPS. Token tersebut harus menyertakan token autentikasi di header permintaan. Untuk mengetahui informasi selengkapnya, lihat gcloud auth print-access-token.

Payload permintaan adalah konten file pipeline_spec.yaml (atau paket .zip). Batas ukuran yang direkomendasikan adalah 10 MiB.

Nama paket diambil dari entri pipeline_spec.pipeline_info.name dalam file pipeline_spec.yaml. Nama paket mengidentifikasi paket secara unik dan tidak dapat diubah di seluruh versi. Panjangnya dapat terdiri dari 4 hingga 128 karakter dan harus cocok dengan ekspresi reguler berikut: ^[a-z0-9][a-z0-9-]{3,127}$.

Paket tags adalah daftar hingga delapan tag yang dipisahkan koma. Setiap tag harus cocok dengan ekspresi reguler berikut: ^[a-zA-Z0-9\-._~:@+]{1,128}$.

Jika tag ada dan mengarah ke pipeline yang telah diupload, tag tersebut akan diperbarui agar mengarah ke pipeline yang sedang Anda upload. Misalnya, jikalatest tag tersebut mengarah ke pipeline yang telah Anda upload, dan Anda mengupload versi baru dengan--tag=latest, tag latest dihapus dari pipeline yang diupload sebelumnya dan ditetapkan ke pipeline baru yang sedang Anda upload.

Jika pipeline yang Anda upload sama dengan pipeline yang telah Anda upload sebelumnya, upload berhasil. Metadata pipeline yang diupload, termasuk tag versinya, akan diupdate agar cocok dengan nilai parameter permintaan upload Anda.

Respons upload

Jika permintaan upload berhasil, permintaan akan menampilkan status HTTP OK. Isi responsnya adalah sebagai berikut:

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

dengan versionName adalah digest sha256 dari pipeline_spec.yaml yang diformat sebagai string heksadesimal.

Mendownload template pipeline menggunakan Artifact Registry REST API

Anda dapat mendownload template pipeline dengan membuat permintaan HTTP menggunakan parameter value yang dijelaskan di bagian ini, dengan:

• PROJECT_ID: Project Google Cloud tempat pipeline ini berjalan.
• REPO_ID adalah ID repositori Artifact Registry Anda.
• PACKAGE_ID adalah ID paket dari template yang Anda upload.
• TAG adalah tag versi.
• VERSION adalah versi template dalam format sha256:abcdef123456....

Untuk download Artifact Registry standar, Anda harus membuat link download sebagai berikut:

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

Contoh permintaan 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

Anda dapat mengganti VERSION dengan TAG dan mendownload template yang sama, seperti yang ditunjukkan pada contoh berikut:

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

Respons download

Jika permintaan download berhasil, permintaan akan menampilkan status HTTP OK. Isi respons adalah isi file pipeline_spec.yaml.

Link referensi

• Artifact Registry - Ringkasan repositori untuk informasi selengkapnya tentang cara mengelola repositori Anda.
• Repository API
  • Kata kunci format adalah "KFP"
• Package API
• Version API
• Tag API
• Definisi proto di GitHub