Crear y usar esquemas personalizados

Además de los esquemas de sistema predefinidos, Vertex ML Metadata proporciona un modelo de datos extensible mediante esquemas personalizados. Los esquemas personalizados son MetadataSchemas definidos por el usuario. Usa esquemas personalizados para verificar las propiedades de metadatos y consultar recursos por esquema, por ejemplo, “enumerar todos los artefactos de tipo MyCustomModel”.

Para definir un esquema personalizado, debes crear un recurso de MetadataSchemas dentro de un MetadataStore específico que describa el esquema esperado. El formato del esquema es un subconjunto de la especificación de OpenAPI 3.0{class: external}, con la restricción de que el esquema de nivel superior debe ser de tipo object. Todos los tipos de datos admitidos de OpenAPI 3.0 (por ejemplo, número entero, número, string, booleano, array, objeto) y se admiten como propiedades de este objeto de esquema de nivel superior. Una restricción es que cada campo de la sección de propiedades se puede asignar a un solo tipo de datos. No se admiten tipos mixtos. Tampoco se admiten los requisitos avanzados de datos, como los formatos mínimo, máximo, múltiplo y de string.

Cómo registrar tus propios esquemas personalizados

El proceso para crear un MetadataSchema personalizado es similar a crear recursos de metadatos nuevos. En las siguientes instrucciones, se muestra cómo crear un MetadataSchema de ejemplo. El alcance de los MetadataSchemas solo se aplica a los almacenes de metadatos asociados.

REST

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

  • LOCATION_ID: Es la región del MetadataSchema.
  • PROJECT_ID: el número o ID del proyecto.
  • METADATA_STORE: El ID del almacén de metadatos en el que se crea el MetadataSchema. El almacén de metadatos predeterminado se llama default. A menos que se requiera un nuevo MetadataStore, puedes usar el almacén predeterminado.
  • METADATA_SCHEMA_ID: El ID del registro de MetadataSchema (opcional). Si no se especifica el ID, Vertex ML Metadata crea un identificador único para este esquema de metadatos.
  • METADATA_SCHEMA_TITLE: Es el título del esquema que describe el campo de metadatos. El título del esquema debe cumplir con el formato “.”. El espacio de nombres debe comenzar con una letra minúscula, puede contener caracteres minúsculas y números, y puede tener entre dos y veinte caracteres. El nombre del esquema debe comenzar con una letra mayúscula, puede incluir letras y números, y tener entre 2 y 49 caracteres.
  • METADATA_SCHEMA_VERSION: (Opcional) Es la versión del esquema que describe el campo de metadatos. schema_version debe ser una string de 3 números separados por puntos, por ejemplo, 1.0.0, 1.0.1. Este formato ayuda a ordenar y comparar versiones.
  • METADATA_SCHEMA_TYPE: Tipo de recurso de metadatos al que se aplica el esquema creado. Los tipos son ARTIFACT_TYPE, EXECUTION_TYPE o CONTEXT_TYPE.
  • METADATA_SCHEMA: Es el esquema detallado que se creará.
  • DESCRIPTION: (Opcional) Una string legible que describe el propósito de la ejecución que se creará.
  • ARTIFACT_ID: (Opcional) El ID del registro del artefacto. Si no se especifica el ID del artefacto, Vertex ML Metadata crea un identificador único para este artefacto.
  • DISPLAY_NAME: (Opcional) Es el nombre definido por el usuario del artefacto.

HTTP method and URL: 

POST http://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STOREmetadataSchemas?metadata_schema_id=METADATA_SCHEMA_ID

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías ver un resultado similar al siguiente. Puedes usar METADATA_SCHEMA_ID como el ID del registro de 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"
}

Las llamadas posteriores para crear, obtener o enumerar artefactos pueden hacer referencia a este esquema si especificas el nombre (demo.Artifact) en el campo schema_title y la versión (0.0.1) en schema_version del recurso de artefacto. Si quieres obtener más información para crear, obtener o enumerar recursos de metadatos, consulta Realiza un seguimiento de Vertex ML Metadata.

Crea una versión de tus esquemas

Todos los recursos del MetadataSchema tienen versiones. Un usuario puede crear un esquema que use el mismo schema_title que otro esquema, pero un esquema schema.version diferente. Para crear un recurso de MetadataSchema con una versión diferente, un usuario puede proporcionar un número de versión diferente y el contenido del esquema modificado.

En el siguiente ejemplo, se crea una versión 0.0.2 del esquema 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)

Los campos del esquema siempre se consideran opcionales, por lo que no hay retrocompatibilidad con versiones anteriores del mismo schema_title. Los usuarios aún pueden usar el schema_title a fin de filtrar y agrupar recursos para el análisis. Si deseas obtener más información para usar las funciones de filtro, consulta Analiza Vertex ML Metadata.

¿Qué sigue?