Analiza metadatos de AA

Puedes usar Vertex ML Metadata para hacer un seguimiento y analizar los metadatos que generan los sistemas de aprendizaje automático (AA). Mediante el seguimiento de estos metadatos, es más fácil analizar el comportamiento de tu sistema de AA. Esto puede ayudarte a comprender los cambios en el rendimiento de tu sistema o a comparar los artefactos que tu sistema de AA produce.

Si no estás familiarizado con Vertex ML Metadata, lee la introducción a Vertex ML Metadata para obtener más información sobre el seguimiento y el análisis de los metadatos de tu flujo de trabajo de AA.

En este documento se describe cómo consultar los metadatos de AA que deseas analizar de las siguientes maneras:

Consulta artefactos, ejecuciones y contextos

Puedes usar la API de REST para consultar registros de artefactos, ejecuciones y contextos con filtros a fin de crear consultas como la siguiente:

  • ¿Qué versiones de un modelo entrenado alcanzaron un cierto umbral de calidad?
  • ¿Qué ejecuciones de la canalización usaron un conjunto de datos determinado?

En las siguientes secciones, se muestra cómocrear filtros y cómo consultar artefactos, ejecuciones y contextos.

Descripción general de la sintaxis del filtro

En las siguientes secciones se describe cómo usar filtros para buscar artefactos, ejecuciones y contextos.

Campos

Los siguientes campos son compatibles cuando se filtran artefactos, ejecuciones y contextos.

Artefacto Ejecución Context
name
display_name
schema_title
create_time
update_time
metadata
state
uri

Tu filtro debe estar entre comillas y todas las comillas que formen parte del filtro deben escaparse con una barra inversa.

Operadores de comparación

Puedes usar los siguientes operadores de comparación en tus filtros: =, !=, <, >, >= y <=.

Por ejemplo, en los siguientes filtros se encuentran todos los artefactos en los que el nombre visible es my_artifact.

"display_name=\"my_artifact\""

Para los campos de string, puedes usar el filtro de comodín con el caracter *.

Para los campos de marca de tiempo, como create_time y update_time, debes formatear la fecha con el formato RFC 3339, por ejemplo:

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

Filtra metadatos con el operador de desvío

El campo metadata es una instancia de google.protobuf.Struct cuyo formato se define en el esquema especificado en el campo schema_title. google.protobuf.Struct es una estructura de datos que asigna claves a instancias google.protobuf.Value. La estructura de datos google.protobuf.Value almacena valores en diferentes campos según su tipo de datos. Por ejemplo: las strings se almacenan como metadata.FIELD_NAME.string_value, los números se almacenan como metadata.FIELD_NAME.number_value y los booleanos se almacenan como metadata.FIELD_NAME.bool_value.

Para filtrar en metadata, debes usar el operador de desvío a fin de recorrer el campo que deseas filtrar. El operador de desvío usa el siguiente formato.

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

Por ejemplo, considera una estructura de metadatos como la siguiente:

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

En las siguientes consultas, se ilustra cómo usar el operador de desvío para filtrar los metadatos de este ejemplo.

  • Filtra los registros que tengan metadata.field_1 con un valor inferior a 5.

    "metadata.field_1.number_value<5"

  • Filtra los registros que tienen metadata.field_2 con un valor igual a ejemplo.

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

  • Filtra los registros que tengan metadata.field_5 con un valor igual a verdadero.

    "metadata.field_5.bool_value=true"

Filtra contextos según las relaciones superiores y secundarias

Puedes usar el operador has para buscar contextos superiores o secundarios de un contexto específico.

El operador usa el siguiente formato:

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

El nombre del contexto debe ser el nombre completo del recurso del contexto, como el siguiente: project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT.

Los siguientes filtros demuestran cómo usar el operador has:

  • Filtra todos los contextos que sean secundarios de la canalización especificada.

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

  • Filtra todos los contextos que sean superiores de la canalización especificada.

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

Filtra artefactos y ejecuciones en un contexto

Puedes usar la función in_context() para filtrar artefactos o ejecuciones que se asocian con un contexto.

La función in_context() usa el siguiente formato.

"in_context(\"CONTEXT_RESOURCE_NAME\")"

El nombre del contexto debe ser el nombre completo del recurso del contexto, como se muestra a continuación.

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

En el siguiente ejemplo se muestra cómo filtrar objetos que se encuentran en la canalización especificada.

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

Operadores lógicos

Puedes usar los operadores lógicos AND y OR para combinar filtros para crear una consulta compleja.

En el siguiente ejemplo, se muestra cómo consultar los artefactos de tipo ai_platform.model y un campo metadata precision con un valor numérico mayor que 0.9.

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

Consulta los artefactos

Los artefactos representan los datos que tu flujo de trabajo de AA usa o produce, como conjuntos de datos y modelos. Usa las siguientes instrucciones para buscar artefactos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Tu región.
  • PROJECT: Tu ID del proyecto o número de proyecto.
  • METADATA_STORE: Es el ID del almacén de metadatos en el que se crea el artefacto. Es el almacén de metadatos predeterminado se llama default.
  • PAGE_SIZE: (Opcional). El número máximo de artefactos que se mostrarán. Si no se especifica este valor, se mostrarán 100 registros como máximo.
  • PAGE_TOKEN: (Opcional). Un token de página de una llamada anterior a MetadataService.ListArtifacts. Especifica este token para obtener la siguiente página de resultados.
  • FILTER: Especifica las condiciones necesarias para incluir un artefacto en el conjunto de resultados.

Método HTTP y 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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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."
    }
  ]
}

Consulta de ejecuciones

Las ejecuciones representan un paso en tu flujo de trabajo del AA, como el procesamiento previo de datos o el entrenamiento de un modelo. Usa las siguientes instrucciones para consultar las ejecuciones.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Tu región.
  • PROJECT: Tu ID del proyecto o número de proyecto.
  • METADATA_STORE: Es el ID del almacén de metadatos en el que se crea la ejecución. Es el almacén de metadatos predeterminado se llama default.
  • PAGE_SIZE: (Opcional). Es la cantidad máxima de ejecuciones que se mostrarán. Si no se especifica este valor, se mostrarán 100 registros como máximo.
  • PAGE_TOKEN: (Opcional). Un token de página de una llamada anterior a MetadataService.ListExecutions. Especifica este token para obtener la siguiente página de resultados.
  • FILTER: Especifica las condiciones necesarias para incluir una ejecución en el conjunto de resultados.

Método HTTP y 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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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."
    }
  ]
}

Consulta de contextos

Los contextos te permiten agrupar conjuntos de ejecuciones, artefactos y otros contextos. Usa las siguientes instrucciones para buscar contextos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Tu región.
  • PROJECT: Tu ID del proyecto o número de proyecto.
  • METADATA_STORE: Es el ID del almacén de metadatos en el que se crea el contexto. Es el almacén de metadatos predeterminado se llama default.
  • PAGE_SIZE: (Opcional). La cantidad máxima de contextos que se mostrarán. Si no se especifica este valor, se mostrarán 100 registros como máximo.
  • PAGE_TOKEN: (Opcional). Un token de página de una llamada anterior a MetadataService.ListExecutions. Especifica este token para obtener la siguiente página de resultados.
  • FILTER: Especifica las condiciones necesarias para incluir un contexto en el conjunto de resultados.

Método HTTP y 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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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": {}
    }
  ]
}

Consulta artefactos de entrada y salida de una ejecución

Usa las siguientes instrucciones para consultar los artefactos y las ejecuciones en el contexto especificado, junto con los eventos que conectan los artefactos con las ejecuciones.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Tu región.
  • PROJECT: Tu ID del proyecto o número de proyecto.
  • METADATA_STORE: Es el ID del almacén de metadatos en el que se crea la ejecución. Es el almacén de metadatos predeterminado se llama default.
  • EXECUTION_ID: Es el ID del registro de ejecución.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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",
    }
  ]
}

Consulta el subgrafo de linaje de un contexto

Usa las siguientes instrucciones para consultar los artefactos y las ejecuciones en el contexto especificado, junto con los eventos que conectan los artefactos con las ejecuciones.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Tu región.
  • PROJECT: Tu ID del proyecto o número de proyecto.
  • METADATA_STORE: Es el ID del almacén de metadatos en el que se crea la ejecución. Es el almacén de metadatos predeterminado se llama default.
  • CONTEXT_ID: El ID del registro de contexto.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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",
    }
  ]
}

¿Qué sigue?