Vertex ML Metadata を追跡する

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

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

ML ワークフローのステップを表す実行を作成します。
既存のアーティファクトを検索し、メタデータストアにすでに書き込まれている入力アーティファクトを見つけます。
メタデータストアにまだ書き込まれていない実行情報への入力と、この実行情報によって生成される出力のアーティファクトを作成する。
実行情報と、その入力アーティファクトと出力アーティファクトとの関係を表すイベントを作成する。
必要に応じて、実行情報とアーティファクトをコンテキストに追加する。コンテキストは、一連の実行情報とアーティファクトをグループ化するために使用できます。たとえば、モデルをトレーニングするために最適な一連のハイパーパラメータを見つけるテストを行っている場合、各テストがそれぞれ固有のパラメータと指標のセットを持つ、異なる実行情報になることがあります。その複数の実行情報をコンテキスト内で比較することで、最適なモデルを生成したテストを見つけることができます。

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

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

@'
{
  "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 "http://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

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 http://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）

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "http://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）

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "http://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

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 http://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）

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 \
     "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID"

PowerShell（Windows）

@'
{
  "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 "http://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

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 http://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）

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 \
     "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents"

PowerShell（Windows）

@'
{
  "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 "http://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

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 http://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）

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

PowerShell（Windows）

@'
{
  "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 "http://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

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 http://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）

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 \
     "http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions"

PowerShell（Windows）

@'
{
  "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 "http://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 の分析を開始する。