파이프라인 템플릿 생성, 업로드, 사용

파이프라인 템플릿은 워크플로 정의를 게시하는 데 사용하는 리소스로서 단일 사용자 또는 여러 사용자가 여러 번 재사용할 수 있는 리소스입니다.

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 v2 이상을 설치합니다.
   (선택사항) 설치하기 전에 다음 명령어를 실행하여 현재 설치된 Kubeflow Pipelines SDK 버전을 확인합니다.

     pip freeze | grep kfp
   

   참고: 최신 버전의 Kubeflow Pipelines SDK로 업그레이드하려면 다음 명령어를 실행하세요.
   pip install kfp --upgrade
   업데이트된 버전을 사용할 수 있는 경우 이 명령어를 실행하면 현재 설치된 버전이 제거되고 최신 버전이 설치됩니다.

2. Vertex AI SDK for Python v1.15.0 이상을 설치합니다.
   (선택사항) 설치하기 전에 다음 명령어를 실행하여 현재 설치된 Python용 Vertex AI SDK 버전을 확인합니다.

     pip freeze | grep google-cloud-aiplatform
   

   참고: 최신 버전의 Vertex AI SDK for Python으로 업그레이드하려면 다음 명령어를 실행합니다.
   pip install google-cloud-aiplatform --upgrade
   업데이트된 버전을 사용할 수 있는 경우 이 명령어를 실행하면 현재 설치된 버전이 제거되고 최신 버전이 설치됩니다.

3. (선택사항) Google Cloud CLI 390.0.0 이상을 설치합니다.

4. Artifact Registry API를 사용 설정하세요.

권한 구성

Vertex AI Pipelines를 위한 gcloud CLI 프로젝트를 아직 설정하지 않은 경우 Vertex AI Pipelines용 Google Cloud 프로젝트 구성의 안내를 따릅니다.

또한 Artifact Registry를 템플릿 레지스트리로 사용하도록 다음 사전 정의된 Identity and Access Management 권한을 할당합니다.

• 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 문서에서 역할 및 권한을 참조하세요.

• 프로젝트 전체 권한 부여
• 저장소별 권한 부여
• 개별 사용자에게 기본 Identity and Access Management 역할 부여

Artifact Registry에서 저장소 만들기

다음으로 Artifact Registry에 파이프라인 템플릿을 위한 저장소를 만듭니다.

콘솔

1. Google Cloud 콘솔에서 Vertex AI Pipelines를 엽니다.

   Vertex AI Pipelines로 이동

2. 내 템플릿 탭을 클릭합니다.

3. 저장소 선택 창을 열려면 저장소 선택을 클릭합니다.

4. 저장소 만들기를 클릭합니다.

5. quickstart-kfp-repo를 저장소 이름으로 지정합니다.

6. 형식에서 Kubeflow Pipelines를 선택합니다.

7. 위치 유형에서 리전을 선택합니다.

8. 리전 드롭다운 목록에서 us-central1을 선택합니다.

   참고: 이 안내의 예시 명령어 및 구성에서는 us-central1을 사용하지만 지원되는 리전을 사용하시면 됩니다.

9. 만들기를 클릭합니다.

Google Cloud CLI

다음 명령어를 실행하여 저장소를 만듭니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• LOCATION: 저장소를 만들려는 위치나 리전입니다(예: us-central1).

gcloud artifacts repositories create 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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 파일로 컴파일입니다.

템플릿 업로드

콘솔

1. Google Cloud 콘솔에서 Vertex AI Pipelines를 엽니다.

   Vertex AI Pipelines로 이동

2. 업로드를 클릭하여 파이프라인 또는 구성요소 업로드 창을 엽니다.

3. 저장소 드롭다운 목록에서 quickstart-kfp-repo 저장소를 선택합니다.

4. 파이프라인 템플릿의 이름을 지정합니다.

5. 파일 필드에서 선택을 클릭하여 로컬 파일 시스템에서 컴파일된 파이프라인 템플릿 YAML을 선택하고 업로드합니다.

6. 파이프라인 템플릿을 업로드하면 파이프라인 템플릿이 내 템플릿 페이지에 나열됩니다.

   내 템플릿으로 이동

Kubeflow Pipelines SDK 클라이언트

1. Kubeflow Pipelines SDK 레지스트리 클라이언트를 구성하려면 다음 명령어를 실행합니다.

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

2. 컴파일된 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."})
   

3. 템플릿이 업로드되었는지 확인하려면 다음 단계를 따르세요.

   1. Google Cloud 콘솔에서 Vertex AI Pipelines를 엽니다.

      Vertex AI Pipelines로 이동

   2. 내 템플릿 탭을 클릭합니다.

   3. 저장소 선택을 클릭합니다.

   4. 목록에서 quickstart-kfp-repo 저장소를 선택한 후 선택을 클릭합니다.

   5. 목록에서 업로드된 템플릿 패키지 hello-world를 찾습니다.

   6. 파이프라인 템플릿 버전 목록을 보려면 hello-world 템플릿을 클릭합니다.

   7. 파이프라인 토폴로지를 보려면 버전을 클릭합니다.

Vertex AI에서 템플릿 사용하기

Artifact Registry의 저장소에 파이프라인 템플릿을 업로드하면 Vertex AI Pipelines에서 사용할 수 있습니다.

템플릿의 스테이징 버킷 만들기

파이프라인 템플릿을 사용하려면 먼저 파이프라인 실행을 스테이징할 Cloud Storage 버킷을 만들어야 합니다.

버킷을 만들려면 파이프라인 아티팩트를 위한 Cloud Storage 버킷 구성의 안내를 따른 후 다음 명령어를 실행합니다.

STAGING_BUCKET="gs://BUCKET_NAME"

BUCKET_NAME을 방금 만든 버킷의 이름으로 바꿉니다.

템플릿에서 파이프라인 실행 만들기

Python용 Vertex AI SDK 또는 Google Cloud 콘솔을 사용하여 Artifact Registry의 템플릿에서 실행되는 파이프라인을 만들 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 Vertex AI Pipelines를 엽니다.

   Vertex AI Pipelines로 이동

2. 내 템플릿 탭을 클릭합니다.

3. 저장소 선택 창을 열려면 저장소 선택을 클릭합니다.

4. quickstart-kfp-repo 저장소를 선택한 후 선택을 클릭합니다.

5. hello-world 패키지를 클릭합니다.

6. 4f245e8f9605 버전 옆의 실행 만들기를 클릭합니다.

7. 런타임 구성을 클릭합니다.

8. Cloud Storage 위치에 다음을 입력합니다.

   gs://BUCKET_NAME
   

   BUCKET_NAME을 파이프라인 실행 스테이징을 위해 만든 버킷의 이름으로 바꿉니다.

9. 제출을 클릭합니다.

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: 템플릿의 버전 태그입니다.

생성된 파이프라인 실행 보기

Python용 Vertex AI SDK에서 특정 파이프라인 버전으로 생성된 실행을 볼 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 Vertex AI Pipelines를 엽니다.

   Vertex AI Pipelines로 이동

2. 내 템플릿 탭을 클릭합니다.

3. 저장소 선택을 클릭합니다.

4. 목록에서 quickstart-kfp-repo 저장소를 선택한 후 선택을 클릭합니다.

5. hello-world 파이프라인 템플릿의 버전 목록을 보려면 hello world 템플릿을 클릭합니다.

6. 파이프라인 실행을 보려는 원하는 버전을 클릭합니다.

7. 선택한 버전의 파이프라인 실행을 보려면 실행 보기를 클릭한 후 실행 탭을 클릭합니다.

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 패키지)의 콘텐츠입니다. 권장 크기 한도는 10MiB입니다.

패키지 이름은 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은 16진수 문자열로 형식이 지정된 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'입니다.
• 패키지 API
• 버전 API
• 태그 API
• GitHub의 Proto 정의