分析 Vertex 機器學習中繼資料

您可以使用 Vertex 機器學習中繼資料，追蹤及分析機器學習 (ML) 系統產生的中繼資料。追蹤這項中繼資料後，您就能更輕鬆地分析機器學習系統的行為。這有助於瞭解系統效能的變化，或比較機器學習系統產生的構件。

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

瞭解如何透過下列方式查詢要分析的 Vertex 機器學習中繼資料：

  • 查詢符合篩選條件的所有構件、執行作業或環境。
  • 查詢執行作業的輸入和輸出構件，以及用於將構件連結至執行作業的事件。
  • 查詢情境的沿襲子圖。這項查詢會傳回內容的構件和執行作業，以及將構件連結至執行作業的事件。

查詢構件、執行作業和環境

您可以使用 Python 適用的 Vertex AI SDK 或 REST API，透過篩選器查詢構件、執行作業和背景資訊記錄，建立類似下列的查詢：

  • 哪些訓練好的模型版本達到特定品質門檻？
  • 特定管道中使用的資料集為何？

以下各節將說明如何建立篩選器，以及如何查詢構件、執行作業和內容。

篩選器語法總覽

以下各節說明如何使用篩選器查詢構件、執行作業和環境。

欄位

篩選構件、執行作業和環境時，系統支援下列欄位。

構件 執行 脈絡資訊
name
display_name
schema_title
create_time
update_time
metadata
state
uri

篩選條件必須加上引號。如果篩選條件包含引號，請務必使用反斜線逸出。

比較運算子

您可以在篩選器中使用下列比較運算子：=、!=、<、>、>=、<=。

舉例來說，以下篩選器會找出顯示名稱為「my_artifact」my_artifact的所有構件。

REST 

display_name=\"my_artifact\"

Python

"display_name=\"my_artifact\""

如果是字串欄位，您可以使用 * 字元進行萬用字元篩選。

如果是 create_time 和 update_time 等時間戳記欄位，您必須使用 RFC 3339 格式設定日期，例如：

REST 

create_time=\"2021-05-11T12:30:00-08:00\"

Python

"create_time=\"2021-05-11T12:30:00-08:00\""

邏輯運算子

您可以使用 AND 和 OR 邏輯運算子合併篩選器，建立複雜的查詢。

以下範例說明如何查詢 ai_platform.model 類型的構件，以及 metadata 欄位 precision 的數值大於 0.9。

REST 

schema_title=\"ai_platform.Model\"+AND+metadata.precision.number_value>0.9

Python

"create_time=\"schema_title=\"ai_platform.Model\" AND metadata.precision.number_value>0.9"

使用遍歷運算子篩選中繼資料

metadata 欄位是 google.protobuf.Struct 的執行個體，格式是在 schema_title 欄位中指定的結構定義中定義。google.protobuf.Struct 是將鍵對應至 google.protobuf.Value 執行個體的資料結構。google.protobuf.Value 資料結構會根據資料類型，將值儲存在不同欄位。例如：

  • 字串會儲存為 metadata.FIELD_NAME.string_value，
  • 數字會儲存為 metadata.FIELD_NAME.number_value，
  • 布林值會儲存為 metadata.FIELD_NAME.bool_value。

如要依 metadata 篩選，您必須使用遍歷運算子遍歷至要篩選的欄位。遍歷運算子採用下列格式。

REST 

metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\"

Python

"metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\""

舉例來說，請考量下列中繼資料結構：

{
   "field_1": 5,
   "field_2": "example",
   "field_3": {
     ...
   },
   "field_4": [],
   "field_5": true,
}

下列查詢說明如何使用遍歷運算子，根據這個範例中繼資料進行篩選。

  • 篩選 metadata.field_1 值小於 5 的記錄。

REST 

metadata.field_1.number_value<5

Python

"metadata.field_1.number_value<5"

  • 篩選 metadata.field_2 值等於「example」的記錄。

REST 

metadata.field_2.string_value=\"example\"

Python

"metadata.field_2.string_value=\"example\""

  • 篩選 metadata.field_5 值等於 true 的記錄。

REST 

metadata.field_5.bool_value=true

Python

"metadata.field_5.bool_value=true"

依父項和子項關係篩選情境

您可以使用 has 運算子，找出指定內容的父項或子項內容。

has 運算子採用下列格式：

  • "parent_contexts:\"CONTEXT_RESOURCE_NAME\""
  • "child_contexts:\"CONTEXT_RESOURCE_NAME\""

內容名稱必須是內容的完整資源名稱，例如： project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT。

下列篩選器示範如何使用 has 運算子：

  • 篩選指定管道的所有子項環境。

REST 

parent_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\"

Python

"parent_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""

  • 篩選指定管道的所有上層環境。

REST 

child_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\"

Python

"child_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""

依關聯和歸因篩選脈絡、執行作業和構件

您可以使用 in_context() 函式，篩選與內容相關聯的構件或執行作業。您可以使用 with_execution() 函式，篩選與執行作業相關聯的特定構件或內容。同樣地，您可以使用 with_artifact() 函式，篩選與構件相關聯的特定執行作業或內容。

篩選函式的格式如下。

  • "in_context(\"CONTEXT_RESOURCE_NAME\")"
  • "with_execution(\"EXECUTION_RESOURCE_NAME\")"
  • "with_artifact(\"ARTIFACT_RESOURCE_NAME\")"

脈絡、執行作業和構件名稱必須是完整資源名稱，如下所示。

  • project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/contexts/CONTEXT
  • project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/executions/EXECUTION
  • project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/artifacts/ARTIFACT

以下範例說明如何篩選指定管道中的物件。

REST 

in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")

Python

"in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")"

您可以在篩選函式中使用萬用字元 *，依據各資源的參數進行篩選。舉例來說，您可以使用下列項目，篩選出對 system.model 構件類型執行的所有動作。

REST 

with_artifact(\"*\",\"schema_title='name.model'\")

Python

"with_artifact(\"*\",\"schema_title='name.model'\")"

您還可以依據下列其他支援的參數進行篩選

  • input=true/false：篩選輸入或輸出構件類型。
  • event_time：篩選執行作業或構件的事件時間。
  • 所有其他支援的篩選欄位

您可以結合欄位和邏輯運算元，建構複雜的篩選查詢。請注意，系統支援的巢狀函式深度上限為 5。

查詢構件

資料集和模型等構件代表 ML 工作流程使用或產生的資料。請按照下列操作說明查詢構件。

REST

使用任何要求資料之前，請先替換以下項目：

  • LOCATION_ID：您的區域。
  • PROJECT_ID：您的專案 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。
  • 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/executions?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

畫面會顯示類似以下的輸出內容。 EXECUTION_ID 是執行記錄的 ID。

{
  "executions": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "displayName": "Example execution 1",
      "etag": "67891011",
      "createTime": "2021-05-18T00:06:56.177Z",
      "updateTime": "2021-05-18T00:06:56.177Z",
      "schemaTitle": "system.Run",
      "schemaVersion": "0.0.1",
      "metadata": {},
      "description": "Description of the example execution."
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "displayName": "Example execution 2",
      "etag": "67891011",
      "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 Optional

from google.cloud import aiplatform


def list_execution_sample(
    project: str,
    location: str,
    display_name_filter: Optional[str] = "display_name=\"my_execution_*\"",
    create_date_filter:  Optional[str] = "create_time>\"2022-06-11T12:30:00-08:00\"",
):
    aiplatform.init(
        project=project,
        location=location)

    combined_filters = f"{display_name_filter} AND {create_date_filter}"

    return aiplatform.Execution.list(filter=combined_filters)
  • 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。
  • 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/contexts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

畫面會顯示類似以下的輸出內容。 CONTEXT_ID 是內容記錄的 ID。

{
  "contexts": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID",
      "displayName": "Experiment 1",
      "etag": "67891011",
      "createTime": "2021-05-18T22:36:02.153Z",
      "updateTime": "2021-05-18T22:36:02.153Z",
      "parentContexts": [],
      "schemaTitle": "system.Experiment",
      "schemaVersion": "0.0.1",
      "metadata": {}
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID",
      "displayName": "Pipeline run 1",
      "etag": "67891011",
      "createTime": "2021-05-18T22:35:02.600Z",
      "updateTime": "2021-05-18T22:35:02.600Z",
      "parentContexts": [],
      "schemaTitle": "system.PipelineRun",
      "schemaVersion": "0.0.1",
      "metadata": {}
    }
  ]
}

查詢執行的輸入和輸出構件

請按照下列操作說明，在指定環境中查詢構件和執行作業，以及將構件連結至執行作業的事件。

Python 適用的 Vertex AI SDK

輸入構件

這個 Python SDK 範例會查詢執行的輸入構件。

Python

from google.cloud import aiplatform


def get_execution_input_artifacts_sample(
    execution: aiplatform.Execution
):
    return execution.get_input_artifacts()

輸出構件

這個 Python SDK 範例會查詢執行的輸出構件。

Python

from google.cloud import aiplatform


def get_execution_output_artifacts_sample(
    execution: aiplatform.Execution
):
    return execution.get_output_artifacts()

REST

這個 REST 範例包含查詢執行作業的輸入和輸出構件。

REST

使用任何要求資料之前，請先替換以下項目：

  • LOCATION_ID：您的區域。
  • PROJECT_ID：。
  • METADATA_STORE：建立執行的中繼資料商店 ID。 預設中繼資料儲存庫的名稱為 default。
  • EXECUTION_ID：執行記錄的 ID。

HTTP 方法和網址：

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

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

畫面會顯示類似以下的輸出。EXECUTION_ID 是執行記錄的 ID。如未指定執行 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。ARTIFACT_ID 是構件記錄的 ID。

{
  "artifacts": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "displayName": "Example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "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."
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "displayName": "Example artifact 2",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "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."
    }
  ],
  "executions": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "displayName": "Example execution 1",
      "etag": "678901011",
      "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."
    }
  ],
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "INPUT",
    },
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "OUTPUT",
    }
  ]
}

查詢內容的沿襲子圖

請按照下列操作說明，在指定環境中查詢構件和執行作業，以及將構件連結至執行作業的事件。

REST

使用任何要求資料之前，請先替換以下項目：

  • LOCATION_ID：您的區域。
  • PROJECT_ID：。
  • METADATA_STORE：建立執行的中繼資料商店 ID。 預設中繼資料儲存庫的名稱為 default。
  • CONTEXT_ID：(選用) 內容記錄的 ID。

HTTP 方法和網址：

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID:queryContextLineageSubgraph

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

畫面會顯示類似以下的輸出。EXECUTION_ID 是執行記錄的 ID。如未指定執行 ID，Vertex ML Metadata 會為這項執行作業建立專屬 ID。ARTIFACT_ID 是構件記錄的 ID。

{
  "artifacts": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "displayName": "Example artifact",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "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."
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "displayName": "Example artifact 2",
      "uri": "gs://your_bucket_name/artifacts/dataset.csv",
      "etag": "678901011",
      "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."
    }
  ],
  "executions": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "displayName": "Example execution 1",
      "etag": "678901011",
      "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."
    }
  ],
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "INPUT",
    },
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "OUTPUT",
    }
  ]
}

後續步驟