您可以使用 Vertex ML Metadata 来跟踪和分析机器学习 (ML) 系统生成的元数据。通过跟踪这些元数据,您可以更轻松地分析机器学习系统的行为。它可帮助您了解系统性能的变化,或者比较机器学习系统生成的工件。
如果您刚开始接触 Vertex ML Metadata,请参阅 Vertex ML Metadata 简介以详细了解如何跟踪和分析机器学习工作流的元数据。
了解如何通过以下方法查询要分析的 Vertex ML Metadata:
- 查询符合过滤条件的所有工件、执行作业或上下文。
- 查询执行作业的输入和输出工件,以及用于将工件连接到执行作业的事件。
- 查询上下文的沿袭子图。此查询会返回上下文的工件和执行作业,以及将工件连接到执行作业的事件。
查询工件、执行和上下文
您可以使用 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"
过滤
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"
按父子关系过滤上下文
您可以使用“包含”运算符来查找指定上下文的父上下文或子上下文。
“包含”运算符采用以下格式:
"parent_contexts:\"CONTEXT_RESOURCE_NAME\""
"child_contexts:\"CONTEXT_RESOURCE_NAME\""
上下文名称必须是上下文的完整资源名称,如下所示:project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT
。
以下过滤条件展示了如何使用“包含”运算符:
过滤出作为指定流水线的所有子上下文。
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
查询执行
执行作业代表机器学习工作流中的一个步骤,例如预处理数据或训练模型。请按照以下说明查询执行作业。
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
Python
查询上下文
上下文可让您对执行作业、工件和其他上下文集进行分组。请按照以下说明查询上下文。
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
输出工件
此 Python SDK 示例涉及查询执行作业的输出工件。
Python
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 会为执行作业创建一个唯一标识符。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 会为执行作业创建一个唯一标识符。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", } ] }