您可以使用 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<5Python
"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/CONTEXTproject/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/executions/EXECUTIONproject/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
查詢執行作業
執行作業代表機器學習工作流程中的步驟,例如預先處理資料或訓練模型。請按照下列操作說明查詢執行作業。
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
查詢情境
您可以透過情境,將執行作業、構件和其他情境分組。請按照下列操作說明查詢背景資訊。
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
輸出構件
這個 Python SDK 範例涉及查詢執行作業的輸出構件。
Python
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",
}
]
}