您可以使用 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_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"
篩選值等於 example 的
metadata.field_2
記錄。
REST
metadata.field_2.string_value=\"example\"
Python
"metadata.field_2.string_value=\"example\""
篩選值等於 true 的
metadata.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
查詢執行作業
執行作業代表機器學習工作流程中的步驟,例如預先處理資料或訓練模型。請按照下列操作說明查詢執行作業。
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
查詢背景資訊
您可以使用情境將執行作業、構件和其他情境分組。請使用以下指示查詢背景資訊。
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
輸出構件
這個 Python SDK 範例會查詢執行作業的輸出構件。
Python 適用的 Vertex AI SDK
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", } ] }