追蹤 Vertex ML Metadata

Vertex ML Metadata 可讓您追蹤及分析機器學習 (ML) 工作流程產生的中繼資料。如果您是第一次使用 Vertex ML Metadata，請參閱 Vertex ML Metadata 簡介，進一步瞭解如何追蹤及分析機器學習工作流程的中繼資料。

本指南將示範如何使用下列程序記錄中繼資料：

1. 建立執行作業，代表機器學習工作流程中的步驟。
2. 查詢現有的構件，找出已寫入中繼資料儲存庫的任何輸入構件。
3. 為尚未寫入中繼資料儲存庫的執行作業輸入內容，以及這項執行作業產生的任何輸出內容建立構件。
4. 建立 事件，代表執行作業與其輸入和輸出構件之間的關係。

5. 視需要將執行作業和構件新增至Context。使用情境將一組執行作業和構件分組。舉例來說，如果您正在實驗，找出訓練模型的最佳超參數組合，則每個實驗可能都是不同的執行作業，有各自的參數和指標組合。您可以比較情境中的執行作業，找出產生最佳模型的實驗。

   您必須先建立情境，才能將執行作業和構件新增至情境。

建立 Vertex ML Metadata 資產的方法有兩種。您可以使用 REST 指令或 Agent Platform SDK for Python。Python SDK 可簡化各種資產類型的建立和探索作業。使用 Python 建立執行作業時，不必手動建構酬載。

事前準備

首次在Google Cloud 專案中使用 Vertex ML Metadata 時，Gemini Enterprise Agent Platform 會建立專案的 Vertex ML Metadata 儲存庫。

如要使用客戶自行管理的加密金鑰 (CMEK) 加密中繼資料，請先使用 CMEK 建立中繼資料儲存庫，再使用 Vertex ML Metadata 追蹤或分析中繼資料。請按照建立使用 CMEK 的中繼資料儲存庫操作說明，設定專案的中繼資料儲存庫。

可建立執行作業

執行作業代表機器學習工作流程中的一個步驟。請按照下列操作說明建立執行作業。

REST

使用任何要求資料之前，請先修改下列項目的值：

• LOCATION_ID：您所在的區域。
• PROJECT_ID：您的專案 ID。
• METADATA_STORE：建立執行的中繼資料儲存庫 ID。預設中繼資料儲存庫名為 default。
• EXECUTION_ID：執行記錄的 ID。如未指定執行作業 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
• 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。這種格式有助於排序及比較版本。
• METADATA：(選用) 描述執行的屬性，例如執行參數。
• DESCRIPTION：(選用) 人類可讀字串，說明要建立的執行作業用途。
• LABELS：選用。使用者定義的中繼資料，用於整理執行作業。

HTTP 方法和網址：

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 執行個體的清單，代表輸入構件。
• output_artifacts：一或多個 aiplatform.Artifact 執行個體的清單，代表輸出構件。
• project：您可以在 Google Cloud 控制台的歡迎頁面找到這些 ID。
• location：請參閱「可用位置清單」。
• execution_id：執行記錄的 ID。如未指定執行作業 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
• metadata：說明執行的屬性，例如執行參數。
• schema_version：描述中繼資料欄位的結構定義版本。
• description：(選用) 人類可讀字串，說明要建立的執行作業用途。

查詢現有構件

「構件」代表機器學習工作流程使用或產生的資料，例如資料集和模型。請按照下列操作說明查詢現有構件。

REST

使用任何要求資料之前，請先修改下列項目的值：

• LOCATION_ID：您所在的區域。
• PROJECT_ID：
• METADATA_STORE：建立構件的中繼資料儲存庫 ID。預設中繼資料儲存庫名為 default。
• PAGE_SIZE：(選用) 要傳回的構件數量上限。如未指定這個值，服務最多會傳回 100 筆記錄。
• PAGE_TOKEN：(選用) 先前 MetadataService.ListArtifacts 呼叫的頁面權杖。指定這個權杖即可取得下一頁結果。

• FILTER：指定將構件納入結果集所需的條件。

HTTP 方法和網址：

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：您可以在 Google Cloud 控制台的歡迎頁面找到這些 ID。
• 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：
• METADATA_STORE：建立構件的中繼資料儲存庫 ID。預設中繼資料儲存庫名為 default。
• ARTIFACT_ID：：(選用) 構件記錄的 ID。如未指定構件 ID，Vertex ML Metadata 會為這個構件建立專屬 ID。
• 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。這種格式有助於排序及比較版本。
• METADATA：(選用) 描述構件的屬性，例如資料集類型。
• DESCRIPTION：(選用) 人類可讀字串，說明要建立的執行作業用途。
• LABELS：選用。使用者定義的中繼資料，用於整理構件。

HTTP 方法和網址：

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：您可以在 Google Cloud 控制台的歡迎頁面找到這些 ID。
• location：請參閱「可用位置清單」。
• uri：(選用) 構件檔案的統一資源 ID (如有)。如果沒有實際的構件檔案，則可能為空白。
• artifact_id：：(選用) 構件記錄的 ID。如未指定構件 ID，Vertex ML Metadata 會為這個構件建立專屬 ID。
• display_name：(選用) 使用者定義的構件名稱。
• schema_version：描述中繼資料欄位的結構定義版本。
• description：(選用) 人類可讀字串，說明要建立的構件用途。
• metadata：說明構件的屬性，例如構件參數。

建立事件，將構件連結至執行作業

事件代表執行作業與其輸入和輸出構件之間的關係。請按照下列操作說明建立事件，將構件連結至執行作業。

REST

使用任何要求資料之前，請先修改下列項目的值：

• LOCATION_ID：您所在的區域。
• PROJECT_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 方法和網址：

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 執行個體的清單，代表輸入構件。
• output_artifacts：一或多個 aiplatform.Artifact 執行個體的清單，代表輸出構件。
• project：您可以在 Google Cloud 控制台的歡迎頁面找到這些 ID。
• location：請參閱「可用位置清單」。
• execution_id：執行記錄的 ID。如未指定執行作業 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
• metadata 描述執行的屬性，例如執行參數。
• schema_version：描述中繼資料欄位的結構定義版本。
• description：(選用) 人類可讀字串，說明要建立的執行作業用途。

建立脈絡資料

您可以透過情境，將一組構件和執行作業分組。請按照下列操作說明建立情境。請注意，Vertex AI Experiments 會建立一個內容，並自動記錄該內容的構件和執行作業 (請參閱「建立或刪除實驗」)。

REST

使用任何要求資料之前，請先修改下列項目的值：

• LOCATION_ID：您所在的區域。
• PROJECT_ID：
• METADATA_STORE：建立執行作業的中繼資料儲存庫 ID。預設中繼資料儲存庫名為 default。
• CONTEXT_ID：(選用) 情境記錄的 ID。如未指定背景資訊 ID，Vertex ML Metadata 會為這個背景資訊建立專屬 ID
• DISPLAY_NAME：情境的顯示名稱。這個欄位最多可包含 128 個 Unicode 字元。
• PARENT_CONTEXT：：指定任何父項情境的資源名稱。一個結構定義最多只能有 10 個上層結構定義。
• METADATA_SCHEMA_TITLE：說明中繼資料欄位的結構定義標題。結構定義的標題必須符合「.」格式。命名空間的開頭必須是小寫字母，可包含小寫字元和數字，長度介於 2 到 20 個字元之間。結構定義名稱開頭須為大寫英文字母，可包含英文字母和數字，長度須介於 2 到 49 個半形字元之間。
• METADATA_SCHEMA_VERSION：(選用) 描述中繼資料欄位的結構定義版本。schema_version 必須是由三個數字組成的字串，並以半形句號分隔，例如 1.0.0、1.0.1。這種格式有助於排序及比較版本。
• METADATA：描述情境的屬性，例如情境參數。
• DESCRIPTION：(選用) 人類可讀字串，說明要建立的執行作業用途。
• LABELS：選用。使用者定義的中繼資料，用於整理脈絡資料。

HTTP 方法和網址：

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：您可以在 Google Cloud 控制台的歡迎頁面找到這些 ID。
• location：請參閱「可用位置清單」。
• context_id：(選用) 情境記錄的 ID。
• metadata 描述情境的屬性，例如情境參數。
• schema_version：描述中繼資料欄位的結構定義版本。
• description：(選用) 人類可讀的字串，說明要建立的內容用途。

將構件和執行作業新增至情境

請按照下列操作說明，將構件和執行作業新增至情境。

REST

使用任何要求資料之前，請先修改下列項目的值：

• LOCATION_ID：您所在的區域。
• PROJECT_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 方法和網址：

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) 和空白回應。

Notebooks

如要瞭解詳情，請在您選擇的環境中執行下列筆記本：

• 「追蹤 自訂訓練工作的指標和參數，並執行詳細分析」：

  在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 中查看

• 「追蹤機器學習訓練工作的指標和參數，並使用 分析這項中繼資料」：

  在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 中查看

• 「使用 Vertex ML Metadata 追蹤 Pipelines 執行作業的構件和指標」：

  在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 中查看

後續步驟

• 開始分析 Vertex ML Metadata。