建立、上傳及使用管道範本

管道範本是您用來發布工作流程定義的資源，這樣單一使用者或多位使用者就能多次重複使用。

Kubeflow Pipelines SDK 註冊用戶端是新的用戶端介面，可搭配相容的註冊伺服器 (例如 Artifact Registry) 使用，用於 Kubeflow Pipelines (KFP) 範本的版本控制。詳情請參閱「在 Kubeflow Pipelines SDK 註冊用戶端中使用範本」。

本頁面說明如何：

• 建立 KFP 管道範本
• 使用 Kubeflow Pipelines SDK 註冊用戶端，將範本上傳至管道範本存放區
• 在 Kubeflow Pipelines 用戶端中使用範本

事前準備

在建構及執行管道前，請按照下列操作說明在 Google Cloud 主控台中設定 Google Cloud 專案和開發環境。

1. 安裝 Kubeflow Pipelines SDK 2 以上版本。

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

1. 安裝 Python 適用的 Vertex AI SDK 1.15.0 以上版本。
   (選用) 安裝前，請執行下列指令，查看目前安裝的是哪個版本的 Vertex AI SDK for Python：

     pip freeze | grep google-cloud-aiplatform
   

2. (選用) 安裝 390.0.0 以上版本的 Google Cloud CLI。

3. 啟用 Artifact Registry API。

設定權限

如果您尚未為 Vertex AI Pipelines 設定 gcloud CLI 專案，請按照「為 Vertex AI Pipelines 設定專案 Google Cloud 」中的指示操作。

此外，請指派下列預先定義的 Identity and Access Management 權限，以便使用 Artifact Registry 做為範本登錄：

• roles/artifactregistry.admin：指派這個角色可建立及管理存放區。
• roles/artifactregistry.repoAdmin 或 roles/artifactregistry.writer：指派任何這些角色，以便管理存放區中的範本。
• roles/artifactregistry.reader：指派此角色，以便從存放區下載範本。
• roles/artifactregistry.reader：將這個角色指派給與 Vertex AI Pipelines 相關聯的服務帳戶，以便透過範本建立管線執行作業。

如要進一步瞭解 Artifact Registry 的預先定義身分與存取權管理角色，請參閱「預先定義的 Artifact Registry 角色」。

請使用下列範例指派角色：

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

更改下列內容：

• PROJECT_ID：您要建立管道的專案。
• PRINCIPAL：您要為其新增權限的實體。
• ROLE：您要授予實體的 Identity and Access Management 角色。

如要進一步瞭解以下內容，請參閱 Artifact Registry 說明文件中的「角色和權限」一節：

• 授予專案層級權限
• 授予存放區專屬權限
• 為個別使用者授予基本 Identity and Access Management 角色

在 Artifact Registry 中建立存放區

接下來，您將在 Artifact Registry 中為管道範本建立存放區。

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

建立範本

使用以下程式碼範例，定義含有單一元件的管道。如要瞭解如何使用 KFP 定義管道，請參閱「建構管道」一文。

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

執行範例時，compiler.Compiler().compile(...) 陳述式會將「hello-world」管道編譯至名為 hello_world_pipeline.yaml 的本機 YAML 檔案中。

上傳範本

在 Vertex AI 中使用範本

將管道範本上傳至 Artifact Registry 中的存放區後，即可在 Vertex AI Pipelines 中使用。

為範本建立測試值區

您必須先建立 Cloud Storage 值區，才能使用管道範本，以便管道執行階段。

如要建立值區，請按照「為管道成果物設定 Cloud Storage 值區」中的指示操作，然後執行下列指令：

STAGING_BUCKET="gs://BUCKET_NAME"

將 BUCKET_NAME 替換為剛建立的值區名稱。

使用範本建立管道執行作業

您可以使用 Vertex AI SDK for Python 或 Google Cloud 控制台，在 Artifact Registry 中根據範本建立管道執行作業。

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

查看已建立的管道執行作業

您可以在 Python 適用的 Vertex AI SDK 中，查看特定管道版本建立的執行作業。

  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)

在 Kubeflow Pipelines SDK 註冊用戶端中使用範本

您可以使用 Kubeflow Pipelines SDK 登錄用戶端搭配 Artifact Registry，下載並使用管道範本。

• 如要列出存放區中的資源，請執行下列指令：

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

  如需可用方法和文件的完整清單，請參閱 Artifact Registry GitHub 存放區中的 proto 檔案。

• 如要將範本下載至本機檔案系統，請執行下列指令：

  # 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

以下各節將概略說明如何使用 Artifact Registry REST API 管理 Artifact Registry 存放區中的管道範本。

使用 Artifact Registry REST API 上傳管道範本

您可以使用本節所述的參數值建立 HTTP 要求，藉此上傳管道範本，其中：

• PROJECT_ID 是這個管道執行的 Google Cloud 專案。
• REPO_ID 是 Artifact Registry 存放區的 ID。

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

建立上傳要求

這項要求是 HTTP 或 HTTPS 多部分要求。要求標頭中必須包含驗證權杖。詳情請參閱 gcloud auth print-access-token。

要求的酬載是 pipeline_spec.yaml 檔案 (或 .zip 套件) 的內容。建議的大小限制為 10 MiB。

套件名稱會從 pipeline_spec.yaml 檔案中的 pipeline_spec.pipeline_info.name 項目取得。套件名稱可明確識別套件，且在各版本中均無法變更。長度介於 4 到 128 個半形字元之間，且必須符合下列規則運算式：^[a-z0-9][a-z0-9-]{3,127}$。

套件 tags 是一份清單，最多包含八個以半形逗號分隔的標記。每個代碼都必須符合下列規則運算式：^[a-zA-Z0-9\-._~:@+]{1,128}$。

如果標記已存在，且指向已上傳的管道，系統會更新標記，使其指向您目前正在上傳的管道。舉例來說，如果 latest 標記指向您已上傳的管道，而您使用 --tag=latest 上傳新版本，系統會從先前上傳的管道移除 latest 標記，並將其指派給您上傳的新管道。

如果您上傳的管道與先前上傳的管道相同，上傳作業就會成功。上傳管道的中繼資料 (包括版本標記) 會更新，以符合上傳要求的參數值。

上傳回覆

如果上傳要求成功，則會傳回 HTTP OK 狀態。回應主體如下所示：

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

其中 versionName 是 pipeline_spec.yaml 的 sha256 摘要，經過格式化為十六進位字串。

使用 Artifact Registry REST API 下載管道範本

您可以使用本節所述的參數值建立 HTTP 要求，藉此下載管道範本，其中：

• PROJECT_ID 是這個管道執行的 Google Cloud 專案。
• REPO_ID 是 Artifact Registry 存放區的 ID。
• PACKAGE_ID 是上傳範本的套件 ID。
• TAG 是版本代碼。
• VERSION 是範本版本，格式為 sha256:abcdef123456...。

如要下載標準 Artifact Registry，請按照以下方式建立下載連結：

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

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

您可以將 VERSION 替換為 TAG，並下載相同的範本，如以下範例所示：

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

下載回應

如果下載要求成功，就會傳回 HTTP OK 狀態。回應主體是 pipeline_spec.yaml 檔案的內容。

參考資料連結

• 如要進一步瞭解如何管理存放區，請參閱「Artifact Registry - 存放區總覽」。
• Repository API
  • 格式關鍵字為「KFP」
• Package API
• Version API
• Tag API
• GitHub 上的 Proto 定義