Vertex ML Metadata permet de suivre et d'analyser les métadonnées produites par vos workflows de machine learning (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 d'un workflow de ML.
Ce guide explique comment consigner les métadonnées à l'aide du processus suivant :
- Créez une exécution qui représente une étape de votre workflow de ML.
- Recherchez des artefacts existants pour trouver les artefacts d'entrée déjà écrits dans votre magasin de métadonnées.
- Créez des artefacts pour les entrées de votre exécution qui ne sont pas déjà écrites dans votre magasin de métadonnées, ainsi que pour les sorties générées par cette exécution.
- Créez des événements permettant de représenter la relation entre votre exécution et ses artefacts d'entrée et de sortie.
Vous pouvez également ajouter votre exécution et vos artefacts à un contexte. Utilisez un contexte pour regrouper des ensembles d'exécutions et d'artefacts. Par exemple, si vous essayez de trouver le meilleur ensemble d'hyperparamètres pour entraîner un modèle, chaque test peut correspondre à une exécution différente avec son propre ensemble de paramètres et de métriques. Vous pouvez comparer les exécutions d'un contexte pour rechercher le test ayant généré le meilleur modèle.
Pour pouvoir ajouter une exécution et des artefacts à un contexte, vous devez créer un contexte.
Il existe deux façons de créer des éléments Vertex ML Metadata. Vous pouvez utiliser les commandes REST ou le SDK Vertex AI pour Python. Le SDK Python simplifie la création et la découverte de types d'éléments divers. Lorsque vous créez des exécutions à l'aide de Python, il n'est pas nécessaire de créer la charge utile manuellement.
Avant de commencer
La première fois que vous utilisez Vertex ML Metadata dans un projet Google Cloud, Vertex AI crée le magasin Vertex ML Metadata de votre projet.
Si vous souhaitez que vos métadonnées soient chiffrées à l'aide d'une clé de chiffrement gérée par le client (CMEK), vous devez créer votre magasin de métadonnées à l'aide d'une clé CMEK avant d'utiliser Vertex ML Metadata pour suivre ou analyser les métadonnées. Pour obtenir des instructions sur la configuration du magasin de métadonnées de votre projet, consultez la section Créer un magasin de métadonnées utilisant une clé CMEK.
Créer une exécution
Les exécutions représentent une étape de votre workflow de ML. Suivez les instructions ci-dessous pour créer 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. Si l'ID d'exécution n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour cette exécution.
- DISPLAY_NAME : nom à afficher de l'exécution. Ce champ peut contenir jusqu'à 128 caractères Unicode.
- EXECUTION_STATE : (facultatif) valeur de l'énumération State qui représente l'état actuel de l'exécution. Ce champ est géré par les applications clientes. Vertex ML Metadata ne vérifie pas la validité des transitions d'état.
- METADATA_SCHEMA_TITLE : titre du schéma décrivant le champ de métadonnées. Le titre du schéma doit respecter le format "
. ". L'espace de noms doit commencer par une lettre minuscule, peut contenir des lettres minuscules et des chiffres, et peut comporter de 2 à 20 caractères. Le nom du schéma doit commencer par une lettre majuscule, peut inclure des lettres et des chiffres, et peut comporter de 2 à 49 caractères. - METADATA_SCHEMA_VERSION : version du schéma décrivant le champ de métadonnées.
schema_version
doit être une chaîne de trois nombres séparés par des points, par exemple : 1.0.0, 1.0.1. Ce format permet de trier et de comparer les versions. - METADATA : (facultatif) propriétés décrivant l'exécution, telles que les paramètres d'exécution.
- DESCRIPTION : (facultatif) chaîne lisible qui décrit l'objectif de l'exécution à créer.
- LABELS : facultatif. Métadonnées définies par l'utilisateur pour l'organisation de vos exécutions.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID
Corps JSON de la requête :
{ "displayName": "DISPLAY_NAME", "state": "EXECUTION_STATE", "schemaTitle": "METADATA_SCHEMA_TITLE", "schemaVersion": "METADATA_SCHEMA_VERSION", "metadata": { METADATA }, "labels": {"LABEL_1":"LABEL_2"}, "description": "DESCRIPTION" }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "displayName": "Example Execution", "etag": "67891011", "labels": { "test_label": "test_label_value" }, "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
display_name
: nom à afficher de l'exécution. Ce champ peut contenir jusqu'à 128 caractères Unicode.input_artifacts
: liste d'une ou de plusieurs instances d'aiplatform.Artifact représentant un artefact d'entrée.output_artifacts
: liste d'une ou de plusieurs instances d'aiplatform.Artifact représentant un artefact de sortie.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.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.metadata
: propriétés décrivant l'exécution, telles que les paramètres d'exécution.schema_version
: version du schéma décrivant le champ de métadonnées.description
: (facultatif) chaîne lisible qui décrit l'objectif de l'exécution à créer.
Rechercher un artefact existant
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 rechercher un artefact existant.
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\".
Créer un artefact
Suivez les instructions ci-dessous pour créer un artefact.
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
. - ARTIFACT_ID : (facultatif) ID de l'enregistrement de l'artefact. Si l'ID d'artefact n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour cet artefact.
- DISPLAY_NAME : (facultatif) nom défini par l'utilisateur pour l'artefact.
- URI : (facultatif) emplacement de stockage de l'artefact.
- ARTIFACT_STATE : (facultatif) valeur de l'énumération State qui représente l'état actuel de l'artefact. Ce champ est géré par les applications clientes. Vertex ML Metadata ne vérifie pas la validité des transitions d'état.
- METADATA_SCHEMA_TITLE : titre du schéma décrivant le champ de métadonnées. Le titre du schéma doit respecter le format "
. ". L'espace de noms doit commencer par une lettre minuscule, peut contenir des lettres minuscules et des chiffres, et peut comporter de 2 à 20 caractères. Le nom du schéma doit commencer par une lettre majuscule, peut inclure des lettres et des chiffres, et peut comporter de 2 à 49 caractères. - METADATA_SCHEMA_VERSION : version du schéma décrivant le champ de métadonnées.
schema_version
doit être une chaîne de trois nombres séparés par des points, par exemple : 1.0.0, 1.0.1. Ce format permet de trier et de comparer les versions. - METADATA : (Facultatif) Propriétés décrivant l'artefact, telles que le type de l'ensemble de données.
- DESCRIPTION : (facultatif) chaîne lisible qui décrit l'objectif de l'exécution à créer.
- LABELS : facultatif. Métadonnées définies par l'utilisateur pour l'organisation de vos artefacts.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID
Corps JSON de la requête :
{ "displayName": "DISPLAY_NAME", "uri": "URI", "state": "ARTIFACT_STATE", "schemaTitle": "METADATA_SCHEMA_TITLE", "schemaVersion": "METADATA_SCHEMA_VERSION", "metadata": { METADATA }, "labels": {"LABEL_1":"LABEL_2"}, "description": "DESCRIPTION" }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "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", "labels": { "test_label": "test_label_value" }, "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." }
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.uri
(facultatif) : identifiant de ressource uniforme pour le fichier d'artefact, le cas échéant. Peut être vide s'il n'y a pas de fichier d'artefact.artifact_id
: (facultatif) ID de l'enregistrement de l'artefact. Si l'ID d'artefact n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour cet artefact.display_name
: (facultatif) nom défini par l'utilisateur pour l'artefact.schema_version
: version du schéma décrivant le champ de métadonnées.description
: (facultatif) chaîne lisible qui décrit l'objectif de l'artefact à créer.metadata
: propriétés décrivant l'artefact, telles que ses paramètres.
Créer des événements pour associer des artefacts à une exécution
Les événements représentent la relation entre une exécution et ses artefacts d'entrées et de sortie. Suivez les instructions ci-dessous pour créer des événements permettant d'associer des artefacts à 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.
ARTIFACT : nom de ressource de l'artefact. Le nom de la ressource est formaté de la façon suivante :
projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID
- EVENT_TYPE : (facultatif) valeur de l'énumération EventType qui spécifie si l'artefact est une entrée ou une sortie de l'exécution.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents
Corps JSON de la requête :
{ "events": [ { "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "type": "EVENT_TYPE" } ] }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.
Python
Python
input_artifacts
: liste d'une ou de plusieurs instances d'aiplatform.Artifact représentant un artefact d'entrée.output_artifacts
: liste d'une ou de plusieurs instances d'aiplatform.Artifact représentant un artefact de sortie.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.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.metadata
: propriétés décrivant l'exécution, telles que les paramètres d'exécution.schema_version
: version du schéma décrivant le champ de métadonnées.description
: (facultatif) chaîne lisible qui décrit l'objectif de l'exécution à créer.
Créer un contexte
Les contextes vous permettent de regrouper des ensembles d'artefacts et d'exécutions. Suivez les instructions ci-dessous pour créer un contexte. Notez que Vertex AI Experiments crée un contexte qui enregistre automatiquement les artefacts et les exécutions dans ce contexte (consultez la page Créer ou supprimer un test).
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. Si l'ID de contexte n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour ce contexte.
- DISPLAY_NAME : nom à afficher du contexte. Ce champ peut contenir jusqu'à 128 caractères Unicode.
- Spécifiez le nom de ressource PARENT_CONTEXT pour tout contexte parent. Un contexte ne peut pas contenir plus de 10 contextes parents.
- METADATA_SCHEMA_TITLE : titre du schéma décrivant le champ de métadonnées. Le titre du schéma doit respecter le format "
. ". L'espace de noms doit commencer par une lettre minuscule, peut contenir des lettres minuscules et des chiffres, et peut comporter de 2 à 20 caractères. Le nom du schéma doit commencer par une lettre majuscule, peut inclure des lettres et des chiffres, et peut comporter de 2 à 49 caractères. - METADATA_SCHEMA_VERSION : version du schéma décrivant le champ de métadonnées.
schema_version
doit être une chaîne de trois nombres séparés par des points, par exemple : 1.0.0, 1.0.1. Ce format permet de trier et de comparer les versions. - METADATA : propriétés décrivant le contexte, telles que les paramètres de contexte.
- DESCRIPTION : (facultatif) chaîne lisible qui décrit l'objectif de l'exécution à créer.
- LABELS : facultatif. Métadonnées définies par l'utilisateur pour l'organisation de vos contextes.
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID
Corps JSON de la requête :
{ "displayName": "DISPLAY_NAME:", "parentContexts": [ "PARENT_CONTEXT_1", "PARENT_CONTEXT_2" ], "schemaTitle": "METADATA_SCHEMA_TITLE", "schemaVersion": "METADATA_SCHEMA_VERSION", "metadata": { METADATA }, "labels": {"LABEL_1":"LABEL_2"}, "description": "DESCRIPTION" }
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.
{ "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID", "displayName": "Example context:", "etag": "67891011", "labels": { "test_label": "test_label_value" }, "createTime": "2021-05-18T01:52:51.642Z", "updateTime": "2021-05-18T01:52:51.642Z", "schemaTitle": "system.Experiment", "schemaVersion": "0.0.1", "metadata": {}, "description": "Description of the example context." }
Python
Python
display_name
: nom à afficher du contexte. Ce champ peut contenir jusqu'à 128 caractères Unicode.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.context_id
: (facultatif) ID de l'enregistrement du contexte.metadata
: propriétés décrivant le contexte, telles que les paramètres de contexte.schema_version
: version du schéma décrivant le champ de métadonnées.description
: (facultatif) chaîne lisible qui décrit l'objectif du contexte à créer.
Ajouter des artefacts et des exécutions à un contexte
Suivez les instructions ci-dessous pour ajouter des artefacts et des exécutions à un contexte.
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 : (facultatif) ID de l'enregistrement du contexte.
Spécifiez le nom de ressource ARTIFACT pour tous les artefacts que vous souhaitez ajouter à ce contexte. Le nom de la ressource est au format suivant :
projects/PROJECT_ID/locations/location/metadataStores/metadata-store/artifacts/artifact
Spécifiez le nom de ressource EXECUTION pour toutes les exécutions que vous souhaitez ajouter à ce contexte. Le nom de la ressource est au format suivant :
projects/PROJECT_ID/locations/location/metadataStores/metadata-store/executions/execution
Méthode HTTP et URL :
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions
Corps JSON de la requête :
{ "artifacts": [ "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID" ], "executions": [ "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID" ] }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.