영구 리소스에서 실행되는 파이프라인 구성

Gemini Enterprise Agent Platform 영구 리소스는 커스텀 학습 작업 및 파이프라인 실행을 실행하는 데 사용할 수 있는 장기 실행 클러스터입니다. 파이프라인 실행에 영구 리소스를 사용하면 컴퓨팅 리소스 가용성을 보장하고 파이프라인 작업 시작 시간을 줄일 수 있습니다. 영구 리소스는 커스텀 학습 작업에서 지원하는 모든 VM 및 GPU를 지원합니다. 영구 리소스에 대해 자세히 알아보려면 영구 리소스 개요를 참조하세요.

이 페이지에서는 다음을 수행하는 방법을 보여줍니다.

영구 리소스 만들기
영구 리소스를 사용하여 파이프라인 실행 만들기

시작하기 전에

영구 리소스로 파이프라인 실행을 만들려면 먼저 다음 기본 요건을 완료해야 합니다.

파이프라인 정의 및 컴파일

파이프라인을 정의한 다음 파이프라인 정의를 YAML 파일로 컴파일합니다. 파이프라인 정의 및 컴파일에 관한 자세한 내용은 파이프라인 빌드를 참조하세요.

필요한 IAM 역할

영구 리소스를 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대해 Agent Platform 관리자 (roles/aiplatform.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 영구 리소스를 만드는 데 필요한 aiplatform.persistentResources.create 권한이 포함되어 있습니다.

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

영구 리소스 만들기

다음 샘플을 사용하여 파이프라인 실행과 연결할 수 있는 영구 리소스를 만듭니다. 영구 리소스 만들기에 관한 자세한 내용은 영구 리소스 만들기를 참조하세요.

gcloud

파이프라인 실행과 연결할 수 있는 영구 리소스를 만들려면 --enable-custom-service-account 플래그와 함께 gcloud ai persistent-resources create 명령어를 사용합니다.

영구 리소스에 하나 이상의 리소스 풀이 포함될 수 있습니다. 영구 리소스에 여러 리소스 풀을 만들려면 여러 --resource-pool-spec 플래그를 지정합니다.

모든 리소스 풀 구성을 명령줄의 일부로 지정하거나 --config 플래그를 사용해서 구성이 포함된 YAML 파일에 대한 경로를 지정합니다.

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

PROJECT_ID: 영구 리소스를 만들려는 Google Cloud 프로젝트의 프로젝트 ID입니다.
LOCATION: 영구 리소스를 만들려는 리전입니다. 지원되는 리전 목록은 기능 가용성을 참조하세요.
PERSISTENT_RESOURCE_ID: 영구 리소스의 고유한 사용자 정의 ID입니다. 문자로 시작하고 문자 또는 숫자로 끝나야 하며 소문자, 숫자, 하이픈(-)만 포함할 수 있습니다.
DISPLAY_NAME: 선택사항. 영구 리소스의 표시 이름입니다.
MACHINE_TYPE: 사용할 가상 머신(VM) 유형입니다. 지원되는 VM 목록은 머신 유형을 참조하세요. 이 필드는 ResourcePool API 메시지의 machineSpec.machineType 필드에 해당합니다.
REPLICA_COUNT: 선택사항. 자동 확장을 사용하지 않으려는 경우 리소스 풀에 만들 복제본 수입니다. 이 필드는 ResourcePool API 메시지의 replicaCount 필드에 해당합니다. MIN_REPLICA_COUNT 및 MAX_REPLICA_COUNT 필드를 지정하지 않으면 복제본 수를 지정해야 합니다.
MIN_REPLICA_COUNT: 선택사항. 리소스 풀에 자동 확장을 사용하는 경우의 최소 복제본 수입니다. 자동 확장을 사용하려면 MIN_REPLICA_COUNT와 MAX_REPLICA_COUNT를 모두 지정해야 합니다.
MAX_REPLICA_COUNT: 선택사항. 리소스 풀에 자동 확장을 사용하는 경우의 최대 복제본 수입니다. 자동 확장을 사용하려면 MIN_REPLICA_COUNT와 MAX_REPLICA_COUNT를 모두 지정해야 합니다.
CONFIG: ResourcePool 사양 목록이 포함된 영구 리소스 YAML 구성 파일의 경로입니다. 옵션이 구성 파일 및 명령줄 인수 모두에 지정된 경우 명령줄 인수가 구성 파일보다 우선 적용됩니다. 밑줄이 있는 키는 유효하지 않습니다.
YAML 구성 파일 예시:
```
resourcePoolSpecs:
  machineSpec:
    machineType: n1-standard-4
  replicaCount: 1
    
```

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud ai persistent-resources create \
    --persistent-resource-id=PERSISTENT_RESOURCE_ID \
    --display-name=DISPLAY_NAME \
    --project=PROJECT_ID \
    --region=LOCATION \
    --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" \
    --enable-custom-service-account

Windows(PowerShell)

gcloud ai persistent-resources create `
    --persistent-resource-id=PERSISTENT_RESOURCE_ID `
    --display-name=DISPLAY_NAME `
    --project=PROJECT_ID `
    --region=LOCATION `
    --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" `
    --enable-custom-service-account

Windows(cmd.exe)

gcloud ai persistent-resources create ^
    --persistent-resource-id=PERSISTENT_RESOURCE_ID ^
    --display-name=DISPLAY_NAME ^
    --project=PROJECT_ID ^
    --region=LOCATION ^
    --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" ^
    --enable-custom-service-account

다음과 비슷한 응답이 표시됩니다.

Using endpoint [https://us-central1-aiplatform.googleapis.com/]
Operation to create PersistentResource [projects/PROJECT_NUMBER/locations/us-central1/persistentResources/mypersistentresource/operations/OPERATION_ID] is submitted successfully.

You can view the status of your PersistentResource create operation with the command

  $ gcloud ai operations describe projects/sample-project/locations/us-central1/operations/OPERATION_ID

gcloud 명령어 예시:

gcloud ai persistent-resources create \
    --persistent-resource-id=my-persistent-resource \
    --region=us-central1 \
    --resource-pool-spec="replica-count=4,machine-type=n1-standard-4"
    --enable-custom-service-account

고급 `gcloud` 구성

앞의 예시에서 사용할 수 없는 구성 옵션을 지정하려면 --config 플래그를 사용하여 persistentResources 필드를 포함하는 로컬 환경의 config.yaml 파일에 경로를 지정합니다. 예를 들면 다음과 같습니다.

gcloud ai persistent-resources create \
    --persistent-resource-id=PERSISTENT_RESOURCE_ID \
    --project=PROJECT_ID \
    --region=LOCATION \
    --config=CONFIG
    --enable-custom-service-account

Python

이 샘플을 사용해 보기 전에 Python 설정 안내를 따르세요. Agent Platform 빠른 시작: 클라이언트 라이브러리 사용.

Agent Platform에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.

파이프라인 실행과 함께 사용할 수 있는 영구 리소스를 만들려면 영구 리소스를 만들 때 ResourceRuntimeSpec 객체에서 enable_custom_service_account 파라미터를 True로 설정합니다.

from google.cloud.aiplatform.preview import persistent_resource
from google.cloud.aiplatform_v1beta1.types.persistent_resource import ResourcePool
from google.cloud.aiplatform_v1beta1.types.machine_resources import MachineSpec

my_example_resource = persistent_resource.PersistentResource.create(
    persistent_resource_id='PERSISTENT_RESOURCE_ID',
    display_name='DISPLAY_NAME',
    resource_pools=[
        ResourcePool(
            machine_spec=MachineSpec(
                machine_type='MACHINE_TYPE'
            ),
            replica_count=REPLICA_COUNT
        )
    ],
    enable_custom_service_account=True,
)

다음을 바꿉니다.

PERSISTENT_RESOURCE_ID: 영구 리소스의 고유한 사용자 정의 ID입니다. ID에는 소문자, 숫자, 하이픈(-)만 포함해야 합니다. 첫 번째 문자는 소문자여야 하고 마지막 문자는 소문자 또는 숫자여야 합니다.
DISPLAY_NAME: 선택사항. 영구 리소스의 표시 이름
MACHINE_TYPE: 사용할 가상 머신(VM) 유형. 지원되는 VM 목록은 머신 유형을 참조하세요. 이 필드는 ResourcePool API 메시지의 machineSpec.machineType 필드에 해당합니다.
REPLICA_COUNT: 이 리소스 풀을 만들 때 만들 복제본 수입니다.

REST

파이프라인 실행과 연결할 수 있는 PersistentResource 리소스를 만들려면 요청 본문에서 enable_custom_service_account 파라미터를 true로 설정하고 persistentResources/create 메서드를 사용하여 POST 요청을 전송합니다.

영구 리소스에 하나 이상의 리소스 풀이 포함될 수 있습니다. 고정된 수의 복제본 또는 자동 확장을 사용하도록 각 리소스 풀을 구성할 수 있습니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: 영구 리소스를 만들려는 Google Cloud 프로젝트의 프로젝트 ID입니다.
LOCATION: 영구 리소스를 만들려는 리전입니다. 지원되는 리전 목록은 기능 가용성을 참조하세요.
PERSISTENT_RESOURCE_ID: 영구 리소스의 고유한 사용자 정의 ID입니다. 문자로 시작하고 문자 또는 숫자로 끝나야 하며 소문자, 숫자, 하이픈(-)만 포함할 수 있습니다.
DISPLAY_NAME: 선택사항. 영구 리소스의 표시 이름입니다.
MACHINE_TYPE: 사용할 가상 머신(VM) 유형입니다. 지원되는 VM 목록은 머신 유형을 참조하세요. 이 필드는 ResourcePool API 메시지의 machineSpec.machineType 필드에 해당합니다.
REPLICA_COUNT: 선택사항. 자동 확장을 사용하지 않으려는 경우 리소스 풀에 만들 복제본 수입니다. 이 필드는 ResourcePool API 메시지의 replicaCount 필드에 해당합니다. MIN_REPLICA_COUNT 및 MAX_REPLICA_COUNT 필드를 지정하지 않으면 복제본 수를 지정해야 합니다.
MIN_REPLICA_COUNT: 선택사항. 리소스 풀에 자동 확장을 사용하는 경우의 최소 복제본 수입니다. 자동 확장을 사용하려면 MIN_REPLICA_COUNT와 MAX_REPLICA_COUNT를 모두 지정해야 합니다.
MAX_REPLICA_COUNT: 선택사항. 리소스 풀에 자동 확장을 사용하는 경우의 최대 복제본 수입니다. 자동 확장을 사용하려면 MIN_REPLICA_COUNT와 MAX_REPLICA_COUNT를 모두 지정해야 합니다.

HTTP 메서드 및 URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID

JSON 요청 본문:

{
  "display_name": "DISPLAY_NAME",
  "resource_pools": [
    {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE"
      },
      "replica_count": REPLICA_COUNT,
      "autoscaling_spec": {
        "min_replica_count": MIN_REPLICA_COUNT,
        "max_replica_count": MAX_REPLICA_COUNT
      }
    }
  ],
  "resource_runtime_spec": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

cat > request.json << 'EOF'
{
  "display_name": "DISPLAY_NAME",
  "resource_pools": [
    {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE"
      },
      "replica_count": REPLICA_COUNT,
      "autoscaling_spec": {
        "min_replica_count": MIN_REPLICA_COUNT,
        "max_replica_count": MAX_REPLICA_COUNT
      }
    }
  ],
  "resource_runtime_spec": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}
EOF

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

@'
{
  "display_name": "DISPLAY_NAME",
  "resource_pools": [
    {
      "machine_spec": {
        "machine_type": "MACHINE_TYPE"
      },
      "replica_count": REPLICA_COUNT,
      "autoscaling_spec": {
        "min_replica_count": MIN_REPLICA_COUNT,
        "max_replica_count": MAX_REPLICA_COUNT
      }
    }
  ],
  "resource_runtime_spec": {
    "service_account_spec": {
      "enable_custom_service_account": true
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/persistentResources/mypersistentresource/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreatePersistentResourceOperationMetadata",
    "genericMetadata": {
      "createTime": "2023-02-08T21:17:15.009668Z",
      "updateTime": "2023-02-08T21:17:15.009668Z"
    }
  }
}

영구 리소스를 사용하여 파이프라인 실행 만들기

파이프라인 작업을 만들려면 먼저 파이프라인 사양을 만들어야 합니다. 파이프라인 사양은 컴파일된 파이프라인 정의를 변환하여 만드는 메모리 내 객체입니다.

파이프라인 사양 만들기

다음 안내에 따라 파이프라인 실행을 만드는 데 사용할 수 있는 인메모리 파이프라인 사양을 만드세요.

파이프라인을 정의하고 YAML 파일로 컴파일합니다. 파이프라인 정의 및 컴파일에 관한 자세한 내용은 파이프라인 빌드를 참조하세요.
다음 코드 샘플을 사용하여 컴파일된 파이프라인 YAML 파일을 메모리 내 파이프라인 사양으로 변환합니다.
```
import yaml
with open("COMPILED_PIPELINE_PATH", "r") as stream:
  try:
    pipeline_spec = yaml.safe_load(stream)
    print(pipeline_spec)
  except yaml.YAMLError as exc:
    print(exc)
```
COMPILED_PIPELINE_PATH를 컴파일된 파이프라인 YAML 파일의 로컬 경로로 바꿉니다.

파이프라인 실행 만들기

다음 Python 코드 샘플을 사용하여 영구 리소스를 사용하는 파이프라인 실행을 만듭니다.

# Import aiplatform and the appropriate API version v1beta1
from google.cloud import aiplatform, aiplatform_v1beta1
from google.cloud.aiplatform_v1beta1.types import pipeline_job as pipeline_job_types

# Initialize the Vertex SDK using PROJECT_ID and LOCATION
aiplatform.init(project='PROJECT_ID', location='LOCATION')

# Create the API Endpoint
client_options = {
    "api_endpoint": f"LOCATION-aiplatform.googleapis.com"
}

# Initialize the PipeLineServiceClient
client = aiplatform_v1beta1.PipelineServiceClient(client_options=client_options)

# Construct the runtime detail
pr_runtime_detail = pipeline_job_types.PipelineJob.RuntimeConfig.PersistentResourceRuntimeDetail(
    persistent_resource_name=(
        f"projects/PROJECT_NUMBER/"
        f"locations/LOCATION/"
        f"persistentResources/PERSISTENT_RESOURCE_ID"
    ),
    task_resource_unavailable_wait_time_ms=WAIT_TIME,
    task_resource_unavailable_timeout_behavior='TIMEOUT_BEHAVIOR',
)

# Construct the default runtime configuration block
default_runtime = pipeline_job_types.PipelineJob.RuntimeConfig.DefaultRuntime(
    persistent_resource_runtime_detail=pr_runtime_detail
)

# Construct the main runtime configuration
runtime_config = pipeline_job_types.PipelineJob.RuntimeConfig(
    gcs_output_directory='PIPELINE_ROOT',
    parameter_values={
        'project_id': 'PROJECT_ID'
    },
    default_runtime=default_runtime
)

# Construct the pipeline job object
pipeline_job = pipeline_job_types.PipelineJob(
    display_name='PIPELINE_DISPLAY_NAME',
    pipeline_spec=PIPELINE_SPEC,
    runtime_config=runtime_config,
)

# Construct the request
parent_path = f"projects/PROJECT_ID/locations/LOCATION"
request = aiplatform_v1beta1.CreatePipelineJobRequest(
    parent=parent_path,
    pipeline_job=pipeline_job,
)

# Make the API Call to create the pipeline job
response = client.create_pipeline_job(request=request)

# Construct the Google Cloud console link
job_id = response.name.split('/')[-1]
console_link = (
    f"https://console.cloud.google.com/vertex-ai/locations/LOCATION"
    f"/pipelines/runs/{job_id}"
    f"?project=PROJECT_ID"
)

# Print the Google Cloud console link to the pipeline run
print(f"View Pipeline Run in Google Cloud console: {console_link}")