Analyser des métadonnées de ML

Vertex ML Metadata vous permet de suivre et d'analyser les métadonnées générées par vos systèmes de machine learning (ML). Le suivi de ces métadonnées facilite l'analyse du comportement de votre système de ML. Cela peut vous aider à comprendre les variations de performances de votre système ou à comparer les artefacts générés par votre système de ML.

Si vous débutez avec Vertex ML Metadata, lisez sa présentation pour en savoir plus sur le suivi et l'analyse des métadonnées de votre workflow de ML.

Ce document explique comment interroger les métadonnées de ML que vous souhaitez analyser de différentes manières :

Interroger des artefacts, des exécutions et des contextes

L'API REST vous permet d'interroger des enregistrements d'artefacts, d'exécutions et de contextes à l'aide de filtres pour créer des requêtes telles que les suivantes :

  • Quelles versions d'un modèle entraîné ont atteint un certain seuil de qualité ?
  • Quelles exécutions de pipeline ont utilisé un ensemble de données spécifique ?

Les sections suivantes expliquent comment créer des filtres et comment interroger des artefacts, des exécutions et des contextes.

Présentation de la syntaxe des filtres

Les sections suivantes décrivent comment utiliser des filtres pour interroger des artefacts, des exécutions et des contextes.

Champs

Les champs suivants sont disponibles lorsque vous filtrez des artefacts, des exécutions et des contextes.

Artefact Exécution Contexte
name
display_name
schema_title
create_time
update_time
metadata
state
uri

Votre filtre doit être placé entre guillemets. Tous les guillemets inclus dans votre filtre doivent être échappés avec une barre oblique inverse.

Opérateurs de comparaison

Vous pouvez utiliser les opérateurs de comparaison suivants dans vos filtres : =, !=, <, >, >= et <=.

Par exemple, les filtres suivants permettent de rechercher tous les artefacts dont le nom à afficher est my_artifact.

"display_name=\"my_artifact\""

Pour les champs de type chaîne, vous pouvez appliquer un filtre générique avec le caractère *.

Pour les champs d'horodatage, tels que create_time et update_time, la date doit être au format RFC 3339. Exemple :

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

Filtrer les métadonnées à l'aide de l'opérateur de balayage

Le champ metadata est une instance de google.protobuf.Struct dont le format est défini dans le schéma spécifié dans le champ schema_title. google.protobuf.Struct est une structure de données qui mappe les clés aux instances google.protobuf.Value. La structure de données google.protobuf.Value stocke les valeurs dans des champs différents en fonction de leur type de données. Par exemple, les chaînes sont stockées en tant que metadata.FIELD_NAME.string_value, les nombres en tant que metadata.FIELD_NAME.number_value et les valeurs booléennes en tant que metadata.FIELD_NAME.bool_value.

Pour filtrer les métadonnées (metadata), vous devez utiliser l'opérateur de balayage pour parcourir le champ dans lequel vous souhaitez appliquer le filtre. L'opérateur de balayage utilise le format suivant.

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

Prenons l'exemple d'une structure de métadonnées telle que la suivante :

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

Les requêtes suivantes montrent comment utiliser l'opérateur de balayage pour filtrer cet exemple de métadonnées.

  • Filtrez les enregistrements dont la valeur metadata.field_1 est inférieure à 5.

    "metadata.field_1.number_value<5"

  • Filtrez les enregistrements dont la valeur metadata.field_2 est example.

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

  • Filtrez les enregistrements dont la valeur metadata.field_5 est true.

    "metadata.field_5.bool_value=true"

Filtrer les contextes en fonction de leurs relations parent-enfant

Vous pouvez utiliser l'opérateur has pour rechercher les contextes parent ou enfant d'un contexte spécifié.

L'opérateur "has" utilise le format suivant :

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

Le nom du contexte doit correspondre au nom complet de la ressource du contexte, comme suit : project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT.

Les filtres suivants montrent comment utiliser l'opérateur "has" :

  • Filtre pour tous les contextes enfants du pipeline spécifié.

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

  • Filtre pour tous les contextes parents du pipeline spécifié.

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

Filtrer les artefacts et les exécutions dans un contexte

Vous pouvez utiliser la fonction in_context() pour filtrer les artefacts ou les exécutions associés à un contexte.

La fonction in_context() utilise le format suivant.

"in_context(\"CONTEXT_RESOURCE_NAME\")"

Le nom du contexte doit correspondre au nom complet de la ressource du contexte, comme suit.

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

L'exemple suivant montre comment filtrer les objets qui se trouvent dans le pipeline spécifié.

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

Opérateurs logiques

Vous pouvez utiliser les opérateurs logiques AND et OR pour combiner des filtres afin de créer une requête complexe.

L'exemple suivant montre comment interroger des artefacts de type ai_platform.model et un champ metadata precision avec une valeur numérique supérieure à 0,9.

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

Requête d'artefacts

Les artefacts correspondent aux données utilisées ou créées par votre workflow de ML, telles que les ensembles de données et les modèles. Suivez les instructions ci-dessous pour interroger des artefacts.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION : votre région.
  • PROJECT : ID de votre projet ou numéro de projet.
  • METADATA_STORE : ID du magasin de métadonnées dans lequel l'artefact est créé. Le magasin de métadonnées par défaut s'appelle default.
  • PAGE_SIZE : (Facultatif) Nombre maximal d'artefacts à renvoyer. Si cette valeur n'est pas spécifiée, 100 enregistrements sont renvoyés au maximum.
  • PAGE_TOKEN : (Facultatif) Jeton de page reçu d'un appel MetadataService.ListArtifacts précédent. Spécifiez ce jeton pour obtenir la page de résultats suivante.
  • FILTER : spécifie les conditions requises pour inclure un artefact dans l'ensemble de résultats.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Requête d'exécutions

Les exécutions représentent une étape de votre workflow de ML, telle que le prétraitement des données ou l'entraînement d'un modèle. Suivez les instructions ci-dessous pour interroger des exécutions.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION : votre région.
  • PROJECT : ID de votre projet ou numéro de projet.
  • METADATA_STORE : ID du magasin de métadonnées dans lequel l'exécution est créée. Le magasin de métadonnées par défaut s'appelle default.
  • PAGE_SIZE : (Facultatif) Nombre maximal d'exécutions à renvoyer. Si cette valeur n'est pas spécifiée, 100 enregistrements sont renvoyés au maximum.
  • PAGE_TOKEN : (Facultatif) Jeton de page reçu d'un appel MetadataService.ListExecutions précédent. Spécifiez ce jeton pour obtenir la page de résultats suivante.
  • FILTER : spécifie les conditions requises pour inclure une exécution dans l'ensemble de résultats.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Requête de contextes

Les contextes vous permettent de regrouper des ensembles d'exécutions, d'artefacts et d'autres contextes. Suivez les instructions ci-dessous pour interroger des contextes.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION : votre région.
  • PROJECT : ID de votre projet ou numéro de projet.
  • METADATA_STORE : ID du magasin de métadonnées dans lequel le contexte est créé. Le magasin de métadonnées par défaut s'appelle default.
  • PAGE_SIZE : (Facultatif) Nombre maximal de contextes à renvoyer. Si cette valeur n'est pas spécifiée, 100 enregistrements sont renvoyés au maximum.
  • PAGE_TOKEN : (Facultatif) Jeton de page reçu d'un appel MetadataService.ListExecutions précédent. Spécifiez ce jeton pour obtenir la page de résultats suivante.
  • FILTER : spécifie les conditions requises pour inclure un contexte dans l'ensemble de résultats.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Interroger les artefacts d'entrée et de sortie d'une exécution

Suivez les instructions ci-dessous pour interroger les artefacts et les exécutions du contexte spécifié, ainsi que les événements permettant de connecter les artefacts aux exécutions.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION : votre région.
  • PROJECT : ID de votre projet ou numéro de projet.
  • METADATA_STORE : ID du magasin de métadonnées dans lequel l'exécution est créée. Le magasin de métadonnées par défaut s'appelle default.
  • EXECUTION_ID : ID de l'enregistrement d'exécution.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Interroger le sous-graphique de traçabilité d'un contexte

Suivez les instructions ci-dessous pour interroger les artefacts et les exécutions du contexte spécifié, ainsi que les événements permettant de connecter les artefacts aux exécutions.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • LOCATION : votre région.
  • PROJECT : ID de votre projet ou numéro de projet.
  • METADATA_STORE : ID du magasin de métadonnées dans lequel l'exécution est créée. Le magasin de métadonnées par défaut s'appelle default.
  • CONTEXT_ID : ID de l'enregistrement du contexte.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Étape suivante