Vertex ML Metadata を追跡する

Vertex ML Metadata を使用すると、機械学習（ML）ワークフローによって生成されたメタデータを追跡して分析できます。Vertex ML Metadata を初めて使用する場合は、Vertex ML Metadata の概要で、ML ワークフローのメタデータの追跡と分析の詳細を確認してください。

このガイドでは、次の手順でメタデータをロギングする方法について説明します。

1. ML ワークフローのステップを表す実行を作成します。
2. 既存のアーティファクトを検索し、メタデータ ストアにすでに書き込まれている入力アーティファクトを見つけます。
3. メタデータ ストアにまだ書き込まれていない実行情報への入力と、この実行情報によって生成される出力のアーティファクトを作成する。
4. 実行情報と、その入力アーティファクトと出力アーティファクトとの関係を表すイベントを作成する。

5. 必要に応じて、実行情報とアーティファクトをコンテキストに追加する。コンテキストは、一連の実行情報とアーティファクトをグループ化するために使用できます。たとえば、モデルをトレーニングするために最適な一連のハイパーパラメータを見つけるテストを行っている場合、各テストがそれぞれ固有のパラメータと指標のセットを持つ、異なる実行情報になることがあります。その複数の実行情報をコンテキスト内で比較することで、最適なモデルを生成したテストを見つけることができます。

   実行情報とアーティファクトは、コンテキストを作成した後、追加する必要があります。

Vertex ML Metadata アセットを作成するには 2 つの方法があります。REST コマンドまたは Vertex AI SDK for Python を使用できます。Python SDK を使用すると、さまざまなアセットタイプの作成と検出を簡単に行うことができます。Python を使用して実行を作成する場合、ペイロードを手動で構築する必要はありません。

始める前に

Google Cloud プロジェクトで初めて Vertex ML Metadata を使用すると、Vertex AI によりプロジェクトの Vertex ML Metadata ストアが作成されます。

顧客管理の暗号鍵（CMEK）でメタデータを暗号化する場合は、Vertex ML Metadata を使用してメタデータを追跡または分析する前に、CMEK を使用してメタデータ ストアを作成する必要があります。プロジェクトのメタデータ ストアは、CMEK を使用するメタデータ ストアの作成の手順で構成します。

実行情報の作成

実行情報は、ML ワークフローのステップを表し、次の手順で実行を作成します。

REST

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

• LOCATION_ID: 使用するリージョン。
• PROJECT_ID: 実際のプロジェクト ID。
• METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
• EXECUTION_ID: 実行レコードの ID。実行 ID が指定されていない場合、この実行の固有識別子が Vertex ML Metadata により作成されます。
• DISPLAY_NAME: 実行の表示名。このフィールドには、最大 128 文字の Unicode 文字を使用できます。
• EXECUTION_STATE: 省略可。実行の現在の状態を表す State 列挙型の値。このフィールドは、クライアント アプリケーションが管理します。Vertex ML Metadata は状態遷移の妥当性を確認しません。
• METADATA_SCHEMA_TITLE: メタデータ フィールドを記述するスキーマのタイトル。スキーマのタイトルは . の形式にする必要があります。名前空間名は 2～20 文字にし、先頭を小文字にします。名前には文字と数字を使用できます。スキーマ名は 2～49 文字にし、先頭は大文字にする必要があります。名前には英字と数字を使用できます。
• METADATA_SCHEMA_VERSION: 省略可。メタデータ フィールドを記述するスキーマのバージョン。schema_version は、1.0.0、1.0.1 のように、3 つの数字をピリオドで区切った文字列にする必要があります。この形式はバージョンの順序付けや比較に役立ちます。
• METADATA: 省略可。実行を記述するプロパティ（実行のパラメータなど）。
• DESCRIPTION: 省略可。人が読める形式の文字列。作成する実行の目的を記述します。
• LABELS: 省略可。実行を編成するためのユーザー定義のメタデータ。

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID

リクエストの本文（JSON）:

{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}

リクエストを送信するには、次のいずれかのオプションを開きます。

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'
{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

@'
{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
'@  | 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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
  "displayName": "Example Execution",
  "etag": "67891011",
  "labels": {
    "test_label": "test_label_value"
  },
  "createTime": "2021-05-18T00:04:49.659Z",
  "updateTime": "2021-05-18T00:04:49.659Z",
  "schemaTitle": "system.Run",
  "schemaVersion": "0.0.1",
  "metadata": {},
  "description": "Description of the example execution."
}

Python

Python

from typing import Any, Dict, List, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import execution_schema


def create_execution_sample(
    display_name: str,
    input_artifacts: List[aiplatform.Artifact],
    output_artifacts: List[aiplatform.Artifact],
    project: str,
    location: str,
    execution_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    with execution_schema.ContainerExecution(
        display_name=display_name,
        execution_id=execution_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create() as execution:
        execution.assign_input_artifacts(input_artifacts)
        execution.assign_output_artifacts(output_artifacts)
        return execution

• display_name: 実行の表示名。このフィールドには、最大 128 文字の Unicode 文字を使用できます。
• input_artifacts: 入力アーティファクトを表す aiplatform.Artifact の 1 つ以上のインスタンスを含むリスト。
• output_artifacts: 出力アーティファクトを表す aiplatform.Artifact の 1 つ以上のインスタンスを含むリスト。
• project: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。
• location: 利用可能なロケーションの一覧をご覧ください。
• execution_id: 実行レコードの ID。実行 ID が指定されていない場合、この実行の固有識別子が Vertex ML Metadata により作成されます。
• metadata: 実行のパラメータなど、実行を記述するプロパティ。
• schema_version: メタデータ フィールドを記述するスキーマのバージョン。
• description: 省略可。人が読める形式の文字列。作成する実行の目的を記述します。

既存のアーティファクトを検索する

アーティファクトは、データセットやモデルなど、ML ワークフローによって使用または生成されるデータを表します。既存のアーティファクトは、次の手順で検索します。

REST

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

• LOCATION_ID: 使用するリージョン。
• PROJECT_ID: 実際のプロジェクト ID。
• METADATA_STORE: アーティファクトが作成されるメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
• PAGE_SIZE: 省略可。返されるアーティファクトの最大数。この値が指定されていない場合は、最大 100 件のレコードが返されます。
• PAGE_TOKEN: 省略可。前回取得した MetadataService.ListArtifacts 呼び出しのページトークン。次の結果ページを取得するには、このトークンを指定します。

• FILTER: 結果セットにアーティファクトを含めるために必要な条件を指定します。

HTTP メソッドと URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

リクエストを送信するには、次のいずれかのオプションを開きます。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER" | Select-Object -Expand Content

出力は次のようになります。ARTIFACT_ID は、アーティファクト レコードの ID です。

{
  "artifacts": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/artifacts/ARTIFACT_ID",
      "displayName": "Example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "67891011",
      "createTime": "2021-05-18T00:33:13.833Z",
      "updateTime": "2021-05-18T00:33:13.833Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the example artifact."
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "displayName": "Another example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset-2.csv",
      "etag": "67891012",
      "createTime": "2021-05-18T00:29:24.344Z",
      "updateTime": "2021-05-18T00:29:24.344Z",
      "state": "LIVE",
      "schemaTitle": "system.Dataset",
      "schemaVersion": "0.0.1",
      "metadata": {
        "payload_format": "CSV"
      },
      "description": "Description of the other example artifact."
    }
  ]
}

Python

Python

from typing import Optional

from google.cloud import aiplatform


def list_artifact_sample(
    project: str,
    location: str,
    display_name_filter: Optional[str] = "display_name=\"my_model_*\"",
    create_date_filter: Optional[str] = "create_time>\"2022-06-11\"",
    order_by: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    combined_filters = f"{display_name_filter} AND {create_date_filter}"
    return aiplatform.Artifact.list(
        filter=combined_filters,
        order_by=order_by,
    )

• project: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。
• location: 利用可能なロケーションの一覧をご覧ください。
• display_name_filter: リソースの一覧表示中に表示名に適用されるフィルタ。display_name=\"my_filter\" という形式で指定します。
• create_date_filter: リソースの一覧表示中に create_date 名に適用されるフィルタ。create_time>\"2022-06-11T12:30:00-08:00\" の形式で指定します。

アーティファクトを作成する

アーティファクトは、次の手順で作成します。

REST

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

• LOCATION_ID: 使用するリージョン。
• PROJECT_ID: 実際のプロジェクト ID。
• METADATA_STORE: アーティファクトが作成されるメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
• ARTIFACT_ID: 省略可。アーティファクト レコードの ID。アーティファクト ID が指定されていない場合、このアーティファクトの固有識別子が Vertex ML Metadata により作成されます。
• DISPLAY_NAME: 省略可。アーティファクトのユーザー定義の名前。
• URI: アーティファクトの保存場所。
• ARTIFACT_STATE: 省略可。アーティファクトの現在の状態を表す State 列挙型の値。このフィールドは、クライアント アプリケーションが管理します。Vertex ML Metadata は状態遷移の妥当性を確認しません。
• METADATA_SCHEMA_TITLE: メタデータ フィールドを記述するスキーマのタイトル。スキーマのタイトルは . の形式にする必要があります。名前空間名は 2～20 文字にし、先頭を小文字にします。名前には文字と数字を使用できます。スキーマ名は 2～49 文字にし、先頭は大文字にする必要があります。名前には英字と数字を使用できます。
• METADATA_SCHEMA_VERSION: 省略可。メタデータ フィールドを記述するスキーマのバージョン。schema_version は、1.0.0、1.0.1 のように、3 つの数字をピリオドで区切った文字列にする必要があります。この形式はバージョンの順序付けや比較に役立ちます。
• METADATA: 省略可。データセットのタイプなど、アーティファクトを記述するプロパティ。
• DESCRIPTION: 省略可。人が読める形式の文字列。作成する実行の目的を記述します。
• LABELS: 省略可。アーティファクトを編成するためのユーザー定義のメタデータ。

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID

リクエストの本文（JSON）:

{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}

リクエストを送信するには、次のいずれかのオプションを開きます。

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'
{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}
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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

@'
{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}
'@  | 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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/default/artifacts/ARTIFACT_ID",
  "displayName": "Example artifact",
  "uri": "gs://your_bucket_name/artifacts/dataset.csv",
  "etag": "67891011",
  "labels": {
    "test_label": "test_label_value"
  },
  "createTime": "2021-05-18T00:29:24.344Z",
  "updateTime": "2021-05-18T00:29:24.344Z",
  "state": "LIVE",
  "schemaTitle": "system.Dataset",
  "schemaVersion": "0.0.1",
  "metadata": {
    "payload_format": "CSV"
  },
  "description": "Description of the example artifact."
}

Python

Python

from typing import Dict, Optional

from google.cloud.aiplatform.metadata.schema.system import artifact_schema


def create_artifact_sample(
    project: str,
    location: str,
    uri: Optional[str] = None,
    artifact_id: Optional[str] = None,
    display_name: Optional[str] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
    metadata: Optional[Dict] = None,
):
    system_artifact_schema = artifact_schema.Artifact(
        uri=uri,
        artifact_id=artifact_id,
        display_name=display_name,
        schema_version=schema_version,
        description=description,
        metadata=metadata,
    )
    return system_artifact_schema.create(project=project, location=location,)

• project: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。
• location: 利用可能なロケーションの一覧をご覧ください。
• uri: 省略可。アーティファクト ファイルの Uniform Resource Identifier（ファイルが存在する場合）。実際のアーティファクト ファイルがない場合は空になります。
• artifact_id: 省略可。アーティファクト レコードの ID。アーティファクト ID が指定されていない場合、このアーティファクトの固有識別子が Vertex ML Metadata により作成されます。
• display_name: （省略可）アーティファクトのユーザー定義の名前。
• schema_version: メタデータ フィールドを記述するスキーマのバージョン。
• description: 省略可。人が読める形式の文字列。作成するアーティファクトの目的を記述します。
• metadata: アーティファクトを記述するプロパティ（アーティファクト パラメータなど）。

アーティファクトを実行情報にリンクするイベントを作成する

イベントは、実行情報と、その入力 / 出力アーティファクトの関係を表します。アーティファクトを実行情報にリンクするイベントは、次の手順で作成します。

REST

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

• LOCATION_ID: 使用するリージョン。
• PROJECT_ID: 実際のプロジェクト ID。
• METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
• EXECUTION_ID: 実行レコードの ID。

• ARTIFACT: アーティファクトのリソース名。リソース名は projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID のように構成されています。

• EVENT_TYPE: 省略可。アーティファクトが実行情報の入力か出力かを指定する EventType 列挙型の値。

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents

リクエストの本文（JSON）:

{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを開きます。

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'
{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}
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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

@'
{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}
'@  | 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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents" | Select-Object -Expand Content

成功を示すステータス コード（2xx）と空のレスポンスが返されます。

Python

Python

from typing import Any, Dict, List, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import execution_schema


def create_execution_sample(
    display_name: str,
    input_artifacts: List[aiplatform.Artifact],
    output_artifacts: List[aiplatform.Artifact],
    project: str,
    location: str,
    execution_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    with execution_schema.ContainerExecution(
        display_name=display_name,
        execution_id=execution_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create() as execution:
        execution.assign_input_artifacts(input_artifacts)
        execution.assign_output_artifacts(output_artifacts)
        return execution

• input_artifacts: 入力アーティファクトを表す aiplatform.Artifact の 1 つ以上のインスタンスを含むリスト。
• output_artifacts: 出力アーティファクトを表す aiplatform.Artifact の 1 つ以上のインスタンスを含むリスト。
• project: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。
• location: 利用可能なロケーションの一覧をご覧ください。
• execution_id: 実行レコードの ID。実行 ID が指定されていない場合、この実行の固有識別子が Vertex ML Metadata により作成されます。
• metadata: 実行のパラメータなど、実行を記述するプロパティ。
• schema_version: メタデータ フィールドを記述するスキーマのバージョン。
• description: 省略可。人が読める形式の文字列。作成する実行の目的を記述します。

コンテキストを作成する

コンテキストを使用すると、アーティファクトと実行の複数のセットをグループ化できます。コンテキストは、次の手順で作成します。Vertex AI Experiments は、そのコンテキストに対してアーティファクトと実行を自動的にログに記録するコンテキストを作成します（テストを作成または削除するを参照）。

REST

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

• LOCATION_ID: 使用するリージョン。
• PROJECT_ID: 実際のプロジェクト ID。
• METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
• CONTEXT_ID: 省略可。コンテキスト レコードの ID。コンテキスト ID が指定されていない場合、このコンテキストの固有識別子が Vertex ML Metadata により作成されます。
• DISPLAY_NAME: コンテキストの表示名。このフィールドには、最大 128 文字の Unicode 文字を使用できます。
• PARENT_CONTEXT: 親コンテキストのリソース名を指定します。1 つのコンテキストに指定できる親コンテキストは 10 個までです。
• METADATA_SCHEMA_TITLE: メタデータ フィールドを記述するスキーマのタイトル。スキーマのタイトルは . の形式にする必要があります。名前空間名は 2～20 文字にし、先頭を小文字にします。名前には文字と数字を使用できます。スキーマ名は 2～49 文字にし、先頭は大文字にする必要があります。名前には英字と数字を使用できます。
• METADATA_SCHEMA_VERSION: 省略可。メタデータ フィールドを記述するスキーマのバージョン。schema_version は、1.0.0、1.0.1 のように、3 つの数字をピリオドで区切った文字列にする必要があります。この形式はバージョンの順序付けや比較に役立ちます。
• METADATA: コンテキストを記述するプロパティ（コンテキスト パラメータなど）。
• DESCRIPTION: 省略可。人が読める形式の文字列。作成する実行の目的を記述します。
• LABELS: 省略可。コンテキストを編成するためのユーザー定義のメタデータ。

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID

リクエストの本文（JSON）:

{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}

リクエストを送信するには、次のいずれかのオプションを開きます。

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'
{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

@'
{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}
'@  | 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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID" | Select-Object -Expand Content

出力は次のようになります。CONTEXT_ID は、コンテキスト レコードの ID です。

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID",
  "displayName": "Example context:",
  "etag": "67891011",
  "labels": {
    "test_label": "test_label_value"
  },
  "createTime": "2021-05-18T01:52:51.642Z",
  "updateTime": "2021-05-18T01:52:51.642Z",
  "schemaTitle": "system.Experiment",
  "schemaVersion": "0.0.1",
  "metadata": {},
  "description": "Description of the example context."
}

Python

Python

from typing import Any, Dict, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import context_schema


def create_context_sample(
    display_name: str,
    project: str,
    location: str,
    context_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    return context_schema.Experiment(
        display_name=display_name,
        context_id=context_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create()

• display_name: コンテキストの表示名。このフィールドには、最大 128 文字の Unicode 文字を使用できます。
• project: 実際のプロジェクト ID。これらの ID は、Google Cloud コンソールの [ようこそ] ページで確認できます。
• location: 利用可能なロケーションの一覧をご覧ください。
• context_id: 省略可。コンテキスト レコードの ID。
• metadata: コンテキストを記述するプロパティ（コンテキスト パラメータなど）。
• schema_version: メタデータ フィールドを記述するスキーマのバージョン。
• description: 省略可。人が読める形式の文字列。作成するコンテキストの目的を記述します。

コンテキストにアーティファクトと実行情報を追加する

アーティファクトと実行情報は、次の手順でコンテキストに追加します。

REST

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

• LOCATION_ID: 使用するリージョン。
• PROJECT_ID: 実際のプロジェクト ID。
• METADATA_STORE: 実行が作成されたメタデータ ストア ID。デフォルトのメタデータ ストアの名前は default です。
• CONTEXT: 省略可。コンテキスト レコードの ID。

• このコンテキストに追加するアーティファクトの ARTIFACT リソース名を指定します。リソース名の形式は、次のような形になります。

  projects/PROJECT_ID/locations/location/metadataStores/metadata-store/artifacts/artifact

• このコンテキストに追加する実行情報の EXECUTION リソース名を指定します。リソース名の形式は、次のような形になります。

  projects/PROJECT_ID/locations/location/metadataStores/metadata-store/executions/execution

HTTP メソッドと URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions

リクエストの本文（JSON）:

{
  "artifacts": [
    "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID"
  ],
  "executions": [
  "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID"
  ]
}

リクエストを送信するには、次のいずれかのオプションを開きます。

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'
{
  "artifacts": [
    "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID"
  ],
  "executions": [
  "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID"
  ]
}
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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

@'
{
  "artifacts": [
    "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID"
  ],
  "executions": [
  "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID"
  ]
}
'@  | 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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions" | Select-Object -Expand Content

成功を示すステータス コード（2xx）と空のレスポンスが返されます。

ノートブック

詳細については、選択した環境で次の Jupyter ノートブックを実行してください。

• 「Vertex AI のカスタム トレーニング ジョブの指標とパラメータを追跡し、詳細な分析を行う」:

  Colab で開く | Colab Enterprise で開く | Vertex AI Workbench ユーザー管理ノートブックで開く | GitHub で表示する

• 「ML トレーニング ジョブの指標とパラメータを追跡し、このメタデータを Vertex AI SDK で分析する」:

  Colab で開く | Colab Enterprise で開く | Vertex AI Workbench ユーザー管理ノートブックで開く | GitHub で表示する

• 「Vertex ML Metadata を使用して、Vertex AI Pipelines の実行全体でアーティファクトと指標を追跡する」:

  Colab で開く | Colab Enterprise で開く | Vertex AI Workbench ユーザー管理ノートブックで開く | GitHub で表示する

次のステップ

• Vertex ML Metadata の分析を開始する。