Créer et utiliser des schémas personnalisés

En plus des schémas système prédéfinis, Vertex ML Metadata fournit un modèle de données extensible via des schémas personnalisés. Les schémas personnalisés sont des MetadataSchema définis par l'utilisateur. Utilisez des schémas personnalisés pour vérifier les types de propriétés des métadonnées et interroger les ressources par schéma (par exemple "répertorier tous les artefacts de type MyCustomModel").

Pour définir un schéma personnalisé, vous devez créer une ressource MetadataSchema dans un magasin de métadonnées spécifique qui décrit le schéma attendu. Le format de schéma est un sous-ensemble de la spécification OpenAPI 3.0{class: external}, avec la restriction que le schéma de premier niveau doit être de type object. Tous les types de données compatibles avec OpenAPI 3.0 (par exemple, entier, nombre, chaîne, booléen, tableau, objet) sont acceptés en tant que propriétés de cet objet de schéma de premier niveau. Une restriction est imposée : chaque champ situé sous la section "properties" ne peut être attribué qu'à un seul type de données. Les types mixtes ne sont pas acceptés. Les exigences de données avancées telles que le format minimal, maximal, multiple et la chaîne ne sont pas compatibles.

Enregistrer vos propres schémas personnalisés

Le processus de création d'un MetadataSchema personnalisé est semblable au processus de création de ressources de métadonnées. Les instructions suivantes montrent comment créer un exemple de MetadataSchema. Les MetadataSchema sont limités à leur MetadataStore associé.

REST

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

  • LOCATION_ID : région de votre MetadataStore.
  • PROJECT_ID : ID ou numéro de votre projet.
  • METADATA_STORE : ID du magasin de métadonnées dans lequel le MetadataSchema est créé. Le magasin de métadonnées par défaut s'appelle default. À moins qu'un nouveau MetadataStore ne soit requis, vous pouvez utiliser le magasin par défaut.
  • METADATA_SCHEMA_ID : (facultatif) ID de l'enregistrement MetadataSchema. Si l'ID n'est pas spécifié, Vertex ML Metadata crée un identifiant unique pour ce MetadataSchema.
  • 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_SCHEMA_TYPE : type de ressource de métadonnées auquel le schéma créé s'applique. Les types sont les suivants : ARTIFACT_TYPE, EXECUTION_TYPE ou CONTEXT_TYPE.
  • METADATA_SCHEMA : schéma détaillé à créer.
  • DESCRIPTION : (facultatif) chaîne lisible qui décrit l'objectif de l'exécution à créer.
  • 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.

Méthode HTTP et URL :

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID

Corps JSON de la requête :

{
    "schemaVersion": "0.0.1",
    "schema": "title: test.Experiment\ntype: object",
    "schemaType": "CONTEXT_TYPE",
}

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

Des résultats semblables aux lignes suivantes devraient s'afficher : Vous pouvez utiliser METADATA_SCHEMA_ID avec l'ID de l'enregistrement MetadataSchema.

{
  "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/metadataSchemas/METADATA_SCHEMA_ID",
  "schemaVersion": "0.0.1",
  "schema": "title: test.Experiment\ntype: object",
  "schemaType": "CONTEXT_TYPE",
  "createTime": "2021-04-06T05:24:04.575481815Z"
}

Les appels suivants pour créer, obtenir ou répertorier les artefacts peuvent ensuite faire référence à ce schéma en spécifiant le nom (demo.Artifact) dans le champ schema_title et la version (0.0.1) dans le champ schema_version de la ressource d'artefact. Pour en savoir plus sur la création, l'obtention ou l'affichage des ressources de métadonnées, consultez la page Effectuer le suivi des ressources Vertex ML Metadata.

Gérer les versions de vos schémas

Toutes les ressources MetadataSchema sont avec versions gérées. Un utilisateur peut créer un schéma qui utilise le même schéma schema_title qu'un autre schéma, mais un schéma schema_version différent. Pour créer une ressource metadataSchema avec une version différente, un utilisateur peut fournir un numéro de version différent et un contenu de schéma modifié.

L'exemple suivant crée une version 0.0.2 du schéma demo.Artifact :

sample_schema_versioned = aip.MetadataSchema()
sample_schema_versioned.schema_type = aip.MetadataSchema.MetadataSchemaType.ARTIFACT_TYPE
sample_schema_versioned.schema ="title: demo.Artifact\ntype: object\nproperties:\n  framework:\n    type: string\n    description: \"The framework type\"\n  model_version:\n    type: integer\n    description: \"The version of the model\""
sample_schema_versioned.schema_version = "0.0.2"
sample_schema_versioned.description = "sample schema 2"

store_client.create_metadata_schema(parent=metadata_store.name, metadata_schema=sample_schema_versioned)

Les champs du schéma sont toujours considérés comme facultatifs. Il n'y a donc pas de rétrocompatibilité ni de compatibilité ascendante entre les versions du même schema_title. Les utilisateurs peuvent toujours utiliser le schema_title pour filtrer et regrouper des ressources à des fins d'analyse. Pour en savoir plus sur l'utilisation des fonctions de filtre, consultez la page Analyser les métadonnées de Vertex ML.

Étapes suivantes