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 l'évolution des 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.
Découvrez les différentes manières de définir des requêtes concernant les ressources Vertex ML Metadata que vous souhaitez analyser :
- Interroger l'ensemble des artefacts, exécutions ou un contexte qui correspondent à vos critères de filtrage.
- Interroger les artefacts d'entrée et de sortie d'une exécution, ainsi que les événements utilisés pour associer les artefacts à l'exécution.
- Interroger un sous-graphe de traçabilité d'un contexte. Cette requête renvoie les artefacts et les exécutions d'un contexte, ainsi que les événements permettant d'associer les artefacts aux exécutions.
Interroger des artefacts, des exécutions et des contextes
Vous pouvez utiliser le SDK Vertex AI pour Python ou l'API REST pour interroger des artefacts, des exécutions et des 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é ?
- Quel ensemble de données est utilisé dans un pipeline donné ?
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 | Context | |
---|---|---|---|
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.
REST
display_name=\"my_artifact\"
Python
"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 :
REST
create_time=\"2021-05-11T12:30:00-08:00\"
Python
"create_time=\"2021-05-11T12:30:00-08:00\""
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.
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"
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. Exemple :
- Les chaînes sont stockées au format
metadata.FIELD_NAME.string_value
. - Les numéros sont stockés au format
metadata.FIELD_NAME.number_value
. - Les valeurs booléennes sont stockées au format
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.
REST
metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\"
Python
"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.
REST
metadata.field_1.number_value<5
Python
"metadata.field_1.number_value<5"
Filtrez les enregistrements dont la valeur
metadata.field_2
est example.
REST
metadata.field_2.string_value=\"example\"
Python
"metadata.field_2.string_value=\"example\""
Filtrez les enregistrements dont la valeur
metadata.field_5
est true.
REST
metadata.field_5.bool_value=true
Python
"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é.
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\""
Filtre pour tous les contextes parents du pipeline spécifié.
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\""
Filtrer les contextes, exécutions et artefacts par association et attribution
Vous pouvez utiliser la fonction in_context()
pour filtrer les artefacts ou les exécutions associés à un contexte. Vous pouvez utiliser la fonction with_execution()
pour filtrer des artefacts ou des contextes spécifiques associés à une exécution. De même, vous pouvez utiliser la fonction with_artifact()
pour filtrer les exécutions ou les contextes spécifiques associés à un artefact.
Les fonctions de filtre sont utilisées au format suivant.
"in_context(\"CONTEXT_RESOURCE_NAME\")"
"with_execution(\"EXECUTION_RESOURCE_NAME\")"
"with_artifact(\"ARTIFACT_RESOURCE_NAME\")"
Le nom du contexte, de l'exécution et de l'artefact doit être le nom complet de la ressource, comme illustré ci-dessous.
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
L'exemple suivant montre comment filtrer les objets qui se trouvent dans le pipeline spécifié.
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\")"
Vous pouvez utiliser un caractère générique *
dans les fonctions de filtre pour filtrer les paramètres de chaque ressource. Par exemple, vous pouvez utiliser les éléments suivants pour filtrer toutes les exécutions qui agissent sur un type d'artefact system.model
.
REST
with_artifact(\"*\",\"schema_title='name.model'\")
Python
"with_artifact(\"*\",\"schema_title='name.model'\")"
Les autres paramètres compatibles que vous pouvez filtrer sont les suivants :
input=true/false
: filtre les types d'artefacts d'entrée ou de sortie.event_time
: filtre les heures des événements d'exécutions ou d'artefacts.- Tous les autres champs de filtre compatibles
Vous pouvez combiner les champs avec des opérandes logiques pour construire des requêtes de filtre complexes. Notez que la profondeur maximale de la fonction imbriquée acceptée est de 5.
Requête d'artefacts
Les artefacts, tels que les ensembles de données et les modèles, représentent des données utilisées ou produites par votre workflow de ML. Suivez les instructions ci-dessous pour interroger des artefacts.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : votre région.
- PROJECT_ID : l'ID de votre 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, le service renvoie un maximum de 100 enregistrements.
- PAGE_TOKEN : (facultatif) jeton de page reçu d'un appel de 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER
Pour envoyer votre requête, développez l'une des options suivantes :
Des résultats semblables aux lignes suivantes devraient s'afficher : ARTIFACT_ID est l'ID de l'enregistrement de l'artefact.
{ "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
project
: l'ID de votre projet. Vous pouvez trouver ces ID sur la page d'accueil de la console Google Cloud.location
: Consultez la liste des emplacements disponibles.display_name_filter
: filtre à appliquer au nom à afficher lors de la création d'une liste des ressources au format "display_name=\"my_filter\".create_date_filter
: filtre à appliquer au nom create_date lors de la création d'une liste des ressources au format "create_time>\"2022-06-11T12:30:00-08:00\".
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.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : votre région.
- PROJECT_ID : l'ID de votre 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'artefacts à renvoyer. Si cette valeur n'est pas spécifiée, le service renvoie un maximum de 100 enregistrements.
- PAGE_TOKEN : (facultatif) jeton de page reçu d'un appel de 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 une exécution dans l'ensemble de résultats.
Méthode HTTP et URL :
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
Pour envoyer votre requête, développez l'une des options suivantes :
Des résultats semblables aux lignes suivantes devraient s'afficher : EXECUTION_ID est l'ID de l'enregistrement d'exécution.
{ "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
project
: l'ID de votre projet. Vous pouvez trouver ces ID sur la page d'accueil de la console Google Cloud.location
: Consultez la liste des emplacements disponibles.display_name_filter
: filtre à appliquer au nom à afficher lors de la création d'une liste des ressources au format "display_name=\"my_filter\".create_date_filter
: filtre à appliquer au nom create_date lors de la création d'une liste des ressources au format "create_time>\"2022-06-11T12:30:00-08:00\".
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.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : votre région.
- PROJECT_ID : l'ID de votre 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 d'artefacts à renvoyer. Si cette valeur n'est pas spécifiée, le service renvoie un maximum de 100 enregistrements.
- PAGE_TOKEN : (facultatif) jeton de page reçu d'un appel de 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 contexte dans l'ensemble de résultats.
Méthode HTTP et URL :
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
Pour envoyer votre requête, développez l'une des options suivantes :
Des résultats semblables aux lignes suivantes devraient s'afficher : CONTEXT_ID est l'ID de l'enregistrement du contexte.
{ "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": {} } ] }
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.
SDK Vertex AI pour Python
Artefacts d'entrée
Cet exemple de SDK Python implique d'interroger les artefacts d'entrée d'une exécution.
Python
Artefacts de sortie
Cet exemple de SDK Python implique d'interroger les artefacts de sortie d'une exécution.
Python
REST
Cet exemple REST inclut l'interrogation des artefacts d'entrée et de sortie d'une exécution.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : votre région.
- PROJECT_ID : l'ID de votre 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:queryExecutionInputsAndOutputs
Pour envoyer votre requête, développez l'une des options suivantes :
Des résultats semblables aux lignes suivantes devraient s'afficher : EXECUTION_ID : ID de l'enregistrement d'exécution. Si l'ID d'exécution n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour cette exécution. ARTIFACT_ID : ID de l'enregistrement de l'artefact.
{ "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", } ] }
Interroger le sous-graphe 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.
REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- LOCATION_ID : votre région.
- PROJECT_ID : l'ID de votre 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 : (facultatif) ID de l'enregistrement du contexte.
Méthode HTTP et URL :
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID:queryContextLineageSubgraph
Pour envoyer votre requête, développez l'une des options suivantes :
Des résultats semblables aux lignes suivantes devraient s'afficher : EXECUTION_ID : ID de l'enregistrement d'exécution. Si l'ID d'exécution n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour cette exécution. ARTIFACT_ID : ID de l'enregistrement de l'artefact.
{ "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", } ] }