追蹤 Vertex ML Metadata

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

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

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

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

    如要將執行作業和構件新增至環境，必須先建立環境。

建立 Vertex ML Metadata 資產的方法有兩種：使用 REST 指令或 Python 適用的 Agent Platform SDK。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](/resource-manager/docs/creating-managing-projects#identifiers)。 。
  • METADATA_STORE：建立執行的中繼資料儲存庫 ID。預設中繼資料儲存庫的名稱為 default。
  • EXECUTION_ID：執行記錄的 ID。如未指定執行 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。
  • DISPLAY_NAME：執行的顯示名稱。這個欄位最多可包含 128 個 Unicode 字元。
  • EXECUTION_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"

}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 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 執行個體的清單，代表輸出 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

請展開以下其中一個選項，以傳送要求：

畫面會顯示類似以下的輸出內容。 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：(選用) 狀態列舉中的值，代表構件的目前狀態。這個欄位由用戶端應用程式管理。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"
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 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：(選用) 如果有構件檔案，則為該檔案的統一資源識別碼。如果沒有實際的構件檔案，則可能為空白。
  • 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"
    }
  ]
}

請展開以下其中一個選項，以傳送要求：

您應該會收到執行成功的狀態碼 (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 執行個體的清單，代表輸出 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"

}

請展開以下其中一個選項，以傳送要求：

畫面會顯示類似以下的輸出內容。 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"
  ]
}

請展開以下其中一個選項，以傳送要求：

您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

筆記本

後續步驟