您可以使用 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
查詢執行作業
執行作業代表機器學習工作流程中的一個步驟,例如預先處理資料或訓練模型。請按照下列操作說明查詢執行作業。
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": {} } ] }
查詢執行的輸入和輸出構件
請按照下列操作說明,在指定環境中查詢構件和執行作業,以及將構件連結至執行作業的事件。
Python 適用的 Vertex AI SDK
輸入構件
這個 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", } ] }