Analisar metadados de ML

É possível usar o Vertex ML Metadata para rastrear e analisar os metadados produzidos pelos sistemas de machine learning (ML). Ao acompanhar esses metadados, fica mais fácil analisar o comportamento do seu sistema de ML. Isso pode ajudar você a entender as alterações no desempenho do sistema ou a comparar os artefatos produzidos pelo sistema de ML.

Se você está começando a usar o Vertex ML Metadata, leia a introdução sobre metadados do Vertex para saber mais sobre como rastrear e analisar os metadados do fluxo de trabalho de ML.

Este documento descreve como consultar os metadados de ML que você quer analisar das seguintes maneiras:

Consultar artefatos, execuções e contextos

Use a API REST para consultar artefatos, execuções e registros de contextos usando filtros para criar consultas como as seguintes:

  • Quais versões de um modelo treinado atingiram um determinado limite de qualidade?
  • Quais execuções de pipeline usaram um determinado conjunto de dados?

As seções a seguir demonstram comocriar filtros e como consultarartefatos .Execuções econtextos.

Visão geral da sintaxe de filtros

As seções a seguir descrevem como usar filtros para consultar artefatos, execuções e contextos.

Campos

Os campos a seguir são compatíveis com a filtragem de artefatos, execuções e contextos.

Artefato Execução Context
name
display_name
schema_title
create_time
update_time
metadata
state
uri

Seu filtro precisa ser colocado entre aspas, e todas as aspas que fazem parte do filtro precisam ser escapadas com uma barra invertida.

Operadores de comparação

É possível usar os seguintes operadores de comparação nos filtros: =, !=, <, >, >=, <=.

Por exemplo, os filtros a seguir para encontrar todos os artefatos em que o nome de exibição é my_artifact.

"display_name=\"my_artifact\""

Para campos de string, é possível usar a filtragem de caracteres curinga com o caractere *.

Para campos de carimbo de data/hora, como create_time e update_time, formate a data usando o formato RFC 3339, por exemplo:

"create_time=\"2021-05-11T12:30:00-08:00\""

Filtrar por metadados usando o operador de travessia

O campo metadata é uma instância de google.protobuf.Struct com o formato definido no esquema especificado no campo schema_title. google.protobuf.Struct é uma estrutura de dados que mapeia chaves para instâncias google.protobuf.Value. A estrutura de dados de google.protobuf.Value armazena valores em campos diferentes, dependendo do tipo de dados. Por exemplo, as strings são armazenadas como metadata.FIELD_NAME.string_value, os números são armazenados como metadata.FIELD_NAME.number_value e os booleanos são armazenados como metadata.FIELD_NAME.bool_value.

Para filtrar por metadata, use o operador de passagem para percorrer o campo que você quer filtrar. O operador de travessia usa o formato a seguir.

"metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\""

Por exemplo, considere uma estrutura de metadados como esta:

{
   "field_1": 5,
   "field_2": "example",
   "field_3": {
     ...
   },
   "field_4": [],
   "field_5": true,
}

As consultas a seguir ilustram como usar o operador de travessia para filtrar esses metadados de exemplo.

  • Filtre os registros que tenham metadata.field_1 com um valor menor que 5.

    "metadata.field_1.number_value<5"

  • Filtre por registros que tenham metadata.field_2 com um valor igual ao example.

    "metadata.field_2.string_value=\"test\""

  • Filtre por registros que tenham metadata.field_5 com um valor igual a true.

    "metadata.field_5.bool_value=true"

Filtrar contextos pelos relacionamentos pai/filho

Você pode usar o operador has para encontrar contextos que sejam pai ou filho de um contexto especificado.

O operador has usa o seguinte formato:

  • "parent_contexts:\"CONTEXT_RESOURCE_NAME\""
  • "child_contexts:\"CONTEXT_RESOURCE_NAME\""

O nome do contexto precisa ser o nome completo do recurso do contexto, como: project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT.

Os filtros a seguir demonstram como usar o operador "contém":

  • Filtre todos os contextos que são filhos do pipeline especificado.

    "parent_contexts: \"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""

  • Filtre todos os contextos que são pai do pipeline especificado.

    "child_contexts: \"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""

Filtrar artefatos e execuções em um contexto

Use a função in_context() para filtrar artefatos ou execuções que estão associados a um contexto.

A função in_context() usa o seguinte formato:

"in_context(\"CONTEXT_RESOURCE_NAME\")"

O nome do contexto precisa ser o nome completo do recurso do contexto, como o seguinte.

project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT

O exemplo a seguir demonstra como filtrar objetos que estão no pipeline especificado.

"in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")"

Operadores lógicos

Use os operadores lógicos AND e OR para combinar filtros e criar uma consulta complexa.

O exemplo a seguir demonstra como consultar artefatos do tipo ai_platform.model e um campo metadata precision com um valor numérico maior que 0,9.

"schema_title=\"ai_platform.Model\" AND metadata.precision.number_value>0.9"

Consultar artefatos

Os artefatos representam dados usados ou produzidos pelo fluxo de trabalho de ML, como conjuntos de dados e modelos. Use as instruções a seguir para consultar artefatos.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o artefato é criado. O armazenamento de metadados padrão é denominado default.
  • PAGE_SIZE: opcional. O número máximo de artefatos a serem retornados. Se esse valor não for especificado, um máximo de 100 registros será retornado.
  • PAGE_TOKEN: opcional. Um token de página de uma chamada anterior de MetadataService.ListArtifacts. Especifique esse token para ver a próxima página de resultados.
  • FILTER: especifica as condições necessárias para incluir um artefato no conjunto de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact",
      "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/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "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."
    }
  ]
}

Consultar execuções

As execuções representam uma etapa no fluxo de trabalho de ML, como o pré-processamento de dados ou o treinamento de um modelo. Use as instruções a seguir para consultar execuções.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução é criada. O armazenamento de metadados padrão é chamado de default.
  • PAGE_SIZE: opcional. O número máximo de execuções a serem retornadas. Se esse valor não for especificado, um máximo de 100 registros será retornado.
  • PAGE_TOKEN: opcional. Um token de página de uma chamada MetadataService.ListExecutions anterior. Especifique esse token para receber a próxima página de resultados.
  • FILTER: especifica as condições necessárias para incluir uma execução no conjunto de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "executions": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "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": "Descrption of the example execution."
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-2",
      "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": "Descrption of the example execution."
    }
  ]
}

Consultar contextos

Os contextos permitem agrupar conjuntos de execuções, artefatos e outros contextos. Use as instruções a seguir para consultar contextos.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o contexto é criado. O armazenamento de metadados padrão é denominado default.
  • PAGE_SIZE: opcional. O número máximo de contextos a serem retornados. Se esse valor não for especificado, serão retornados no máximo 100 registros.
  • PAGE_TOKEN: opcional. Um token de página de uma chamada MetadataService.ListExecutions anterior. Especifique esse token para ver a próxima página de resultados.
  • FILTER: especifica as condições necessárias para incluir um contexto no conjunto de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "contexts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/contexts/experiment-1",
      "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/12345/locations/us-central1/metadataStores/default/contexts/pipeline-run-1",
      "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": {}
    }
  ]
}

Consultar artefatos de entrada e saída de uma execução

Use as instruções a seguir para consultar os artefatos e execuções no contexto especificado, além dos eventos que conectam artefatos às execuções.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução é criada. O armazenamento de metadados padrão é denominado default.
  • EXECUTION_ID: o ID do registro de execução.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION:queryExecutionInputsAndOutputs

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "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/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "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/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "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/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "INPUT",
    },
    {
      "artifact": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "OUTPUT",
    }
  ]
}

Consultar o subgráfico de linhagem de um contexto

Use as instruções a seguir para consultar os artefatos e execuções no contexto especificado, além dos eventos que conectam artefatos às execuções.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução é criada. O armazenamento de metadados padrão é denominado default.
  • CONTEXT_ID: o ID do registro de contexto.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts/CONTEXT_ID:queryContextLineageSubgraph

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "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/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "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/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "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/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-1",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "INPUT",
    },
    {
      "artifact": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "execution": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "eventTime": "2021-05-18T00:04:49.659Z",,
      "type": "OUTPUT",
    }
  ]
}

A seguir