分析 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 的所有構件。

REST

display_name=\"my_artifact\"

Python

"display_name=\"my_artifact\""

針對字串欄位,您可以使用萬用字元篩選功能搭配 * 字元。

對於 create_timeupdate_time 等時間戳記欄位,您必須使用 RFC 3339 格式設定日期,例如:

REST

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

Python

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

邏輯運算子

您可以使用 ANDOR 邏輯運算子結合篩選器,建立複雜的查詢。

以下範例說明如何查詢 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"
  • 篩選值等於 examplemetadata.field_2 記錄。

REST

metadata.field_2.string_value=\"example\"

Python

"metadata.field_2.string_value=\"example\""
  • 篩選值等於 truemetadata.field_5 記錄。

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 適用的 Vertex AI SDK

Python 適用的 Vertex AI SDK

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:您的專案 ID。您可以在 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:您的專案 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 適用的 Vertex AI SDK

Python 適用的 Vertex AI SDK

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:您的專案 ID。您可以在 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:您的專案 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 適用的 Vertex AI SDK

from google.cloud import aiplatform


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

輸出構件

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

Python 適用的 Vertex AI SDK

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:您的專案 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:您的專案 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",
    }
  ]
}

後續步驟