このページは Cloud Translation API によって翻訳されました。

永続リソースでのパイプライン実行を構成する

Vertex AI 永続リソースは、カスタムトレーニングジョブとパイプラインの実行に使用できる長時間実行クラスタです。パイプライン実行に永続リソースを使用すると、コンピューティングリソースの可用性を確保し、パイプラインタスクの起動時間を短縮できます。永続リソースでは、カスタムトレーニングジョブでサポートされているすべての VM と GPU がサポートされます。永続リソースの詳細については、永続リソースの概要をご覧ください。

このページでは、次の方法について説明します。

永続リソースを作成する
永続リソースを使用してパイプライン実行を作成する

始める前に

永続リソースを使用してパイプライン実行を作成する前に、次の前提条件を満たす必要があります。

パイプラインを定義してコンパイルする

パイプラインを定義し、パイプラインの定義を YAML ファイルにコンパイルします。パイプラインの定義とコンパイルの詳細については、パイプラインのビルドをご覧ください。

必要な IAM のロール

永続リソースの作成に必要な権限を取得するには、プロジェクトに対する Vertex AI 管理者（roles/aiplatform.admin）IAM ロールを付与するように管理者に依頼します。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、永続リソースを作成するために必要な aiplatform.persistentResources.create 権限が含まれています。

カスタムロールや他の事前定義ロールを使用して、この権限を取得することもできます。

永続リソースを作成する

次のサンプルを使用して、パイプライン実行に関連付けることができる永続リソースを作成します。永続リソースの作成の詳細については、永続リソースを作成するをご覧ください。

gcloud

パイプライン実行に関連付けることができる永続リソースを作成するには、--enable-custom-service-account フラグを指定して gcloud ai persistent-resources create コマンドを実行します。

永続リソースには 1 つ以上のリソースプールを設定できます。永続リソースに複数のリソースプールを作成するには、複数の --resource-pool-spec フラグを指定します。

すべてのリソースプール構成をコマンドラインの一部として指定できます。または、同構成を含む YAML ファイルへのパスを、--config フラグを使用して指定できます。

後述のコマンドデータを使用する前に、次のように置き換えます。

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

このサンプルを試す前に、Vertex AI クイックスタート: クライアントライブラリの使用にある Python の設定手順を完了してください。詳細については、Vertex AI Python API のリファレンスドキュメントをご覧ください。

Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

パイプライン実行で使用できる永続リソースを作成するには、永続リソースの作成時に 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 リクエストを送信します。

永続リソースには 1 つ以上のリソースプールを設定できます。各リソースプールは、固定数のレプリカと自動スケーリングのいずれかを使用するように設定できます。

リクエストのデータを使用する前に、次のように置き換えます。

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 を実行すると、現在アクティブなアカウントを確認できます。

@'
{
  "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}")