分析 Vertex ML Metadata

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

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

瞭解如何透過下列方式,查詢要分析的 Vertex ML Metadata:

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

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

您可以使用 Vertex AI SDK for Python 或 REST API,透過篩選器查詢構件、執行作業和情境記錄,建立如下的查詢:

  • 哪些訓練模型版本達到特定品質門檻?
  • 特定管道使用哪個資料集?

以下各節說明如何建立篩選器,以及如何查詢構件、執行作業和情境。

篩選器語法總覽

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

欄位

篩選構件、執行作業和情境時,支援下列欄位。

構件 執行作業 背景資訊
name
display_name
schema_title
create_time
update_time
metadata
state
uri

篩選條件必須以引號括住。篩選器中的任何引號都必須以反斜線逸出。

比較運算子

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

例如,下列篩選器會找出顯示名稱為 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 類型的構件,以及數值大於 0.9 的 metadata 欄位 precision。

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。

查詢構件

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

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": {}
    }
  ]
}

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

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

Agent Platform SDK for Python

輸入構件

這個 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",
    }
  ]
}

後續步驟