本頁面由 Cloud Translation API 翻譯而成。

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

管道範本是一種資源，可用於發布工作流程定義，讓單一使用者或多位使用者重複使用。

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

本文說明如何：

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

事前準備

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

安裝 Kubeflow Pipelines SDK 第 2 版或更新版本。
```
pip install --upgrade "kfp>=2,<3"
```

安裝 Python 適用的 Vertex AI SDK 1.15.0 以上版本。
(選用) 安裝前，請執行下列指令，查看已安裝的 Vertex AI SDK for Python 版本：
```
  pip freeze | grep google-cloud-aiplatform
```
注意： 如要升級至最新版 Vertex AI SDK for Python，請執行下列指令：
pip install google-cloud-aiplatform --upgrade
如有更新版本，執行這項指令會解除安裝目前版本，並安裝最新版本。
(選用) 安裝 390.0.0 以上版本的 Google Cloud CLI。
啟用 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 的預先定義 Identity and Access Management 角色，請參閱預先定義的 Artifact Registry 角色。

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

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

更改下列內容：

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

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

在 Artifact Registry 中建立存放區

接著，您要在 Artifact Registry 中為管道範本建立存放區。

控制台

在 Google Cloud 控制台中開啟 Vertex AI Pipelines。

前往 Vertex AI Pipelines
按一下「你的範本」分頁標籤。
如要開啟「Select repository」(選取存放區) 窗格，請按一下「Select repository」(選取存放區)。
點選「Create Repository」(建立存放區)。
指定 quickstart-kfp-repo 做為存放區名稱。
在「格式」下方，選取 Kubeflow Pipelines。
在「位置類型」下方，選取「區域」。
在「Region」(區域) 下拉式清單中選取「us-central1」。

注意： 這些操作說明中的範例指令和設定使用 us-central1，但您可以改用任何支援的區域。
點選「建立」。

Google Cloud CLI

執行下列指令來建立存放區。

使用下列任何指令資料之前，請先替換以下項目：

LOCATION：要建立存放區的位置或區域，例如 us-central1

執行 gcloud artifacts repositories create 指令：

Linux、macOS 或 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

建立範本

使用下列程式碼範例定義管道，其中包含單一元件。如要瞭解如何使用 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 檔案。

上傳範本

控制台

在 Google Cloud 控制台中開啟 Vertex AI Pipelines。

前往 Vertex AI Pipelines
按一下「上傳」，開啟「上傳 pipeline 或元件」窗格。
在「Repository」(存放區) 下拉式清單中，選取 quickstart-kfp-repo 存放區。
指定管道範本的「名稱」。
在「檔案」欄位中，按一下「選擇」，從本機檔案系統選取並上傳已編譯的管線範本 YAML。
上傳管道範本後，該範本會列在「您的範本」頁面中。

前往「Your templates」(你的範本)

Kubeflow Pipelines SDK 用戶端

如要設定 Kubeflow Pipelines SDK 登錄用戶端，請執行下列指令：

from kfp.registry import RegistryClient

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

將編譯後的 YAML 檔案上傳至 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."})

如要確認範本是否已上傳：
1. 在 Google Cloud 控制台中開啟 Vertex AI Pipelines。
  
  前往 Vertex AI Pipelines
2. 按一下「你的範本」分頁標籤。
3. 點選「Select repository」(選取存放區)。
4. 從清單中選取 quickstart-kfp-repo 存放區，然後按一下「選取」。
5. 您應該會在清單中找到上傳的範本套件 hello-world。
6. 如要查看管道範本的版本清單，請按一下 hello-world 範本。
7. 如要查看管道拓撲，請點選版本。

在 Vertex AI 中使用範本

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

為範本建立暫存值區

使用管道範本前，您需要先建立 Cloud Storage 值區，用於暫存管道執行作業。

如要建立 bucket，請按照「為管道構件設定 Cloud Storage bucket」中的操作說明執行，然後執行下列指令：

STAGING_BUCKET="gs://BUCKET_NAME"

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

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

您可以使用 Python 適用的 Vertex AI SDK 或 Google Cloud 控制台，從 Artifact Registry 中的範本建立 pipeline 執行作業。

控制台

在 Google Cloud 控制台中開啟 Vertex AI Pipelines。

前往 Vertex AI Pipelines
按一下「你的範本」分頁標籤。
如要開啟「Select repository」(選取存放區) 窗格，請按一下「Select repository」(選取存放區)。
選取 quickstart-kfp-repo 存放區，然後按一下「選取」。
按一下 hello-world 檔案包。
按一下 4f245e8f9605 版本旁邊的「建立執行」。
按一下「執行階段設定」。
在「Cloud Storage location」(Cloud Storage 位置) 下方輸入下列內容：
```
gs://BUCKET_NAME
```
將 BUCKET_NAME 替換為您為管道執行階段建立的值區名稱。
按一下「提交」。

Python 適用的 Vertex AI SDK

使用下列範例，從範本建立管道執行作業：

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

更改下列內容：

PROJECT_ID：這個管道執行的 Google Cloud 專案。
SHA256_TAG：範本版本的 sha256 雜湊值。
TAG：範本的版本標記。

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

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

控制台

在 Google Cloud 控制台中開啟 Vertex AI Pipelines。

前往 Vertex AI Pipelines
按一下「你的範本」分頁標籤。
點選「Select repository」(選取存放區)。
從清單中選取 quickstart-kfp-repo 存放區，然後按一下「選取」。
如要查看 hello-world 管道範本的版本清單，請按一下 hello world 範本。
按一下要查看管道執行的所需版本。
如要查看所選版本的管道執行作業，請依序點選「查看執行作業」和「執行作業」分頁標籤。

Python 適用的 Vertex AI SDK

如要列出管道執行作業，請執行 pipelineJobs.list 指令，如以下一或多個範例所示：

  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 項目。套件名稱是套件的專屬 ID，且各版本皆不得重複。長度必須介於 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 overview」。
Repository API
- 格式關鍵字為「KFP」
套件 API
版本 API
標記 API
GitHub 上的 Proto 定義

建立、上傳及使用管道範本 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定權限

在 Artifact Registry 中建立存放區

控制台

Google Cloud CLI

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

建立範本

上傳範本

控制台

Kubeflow Pipelines SDK 用戶端

在 Vertex AI 中使用範本

為範本建立暫存值區

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

控制台

Python 適用的 Vertex AI SDK

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

控制台

Python 適用的 Vertex AI SDK

在 Kubeflow Pipelines SDK 登錄用戶端中使用範本

使用 Artifact Registry REST API

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

curl 要求範例

建構上傳要求

上傳回覆

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

curl 要求範例

下載回覆

參考連結

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