分析 Vertex ML Metadata

您可以使用 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

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

Python

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

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

输出工件

此 Python SDK 示例涉及查询执行作业的输出工件。

Python

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 会为执行作业创建一个唯一标识符。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",
    }
  ]
}

后续步骤