Criar e usar esquemas personalizados

Além dos esquemas predefinidos do sistema, os metadados de ML da Vertex fornecem um modelo de dados extensível por meio de esquemas personalizados. Os esquemas personalizados são MetadataSchemas definidos pelo usuário. Use esquemas personalizados para verificar propriedades de metadados do tipo e consultar recursos por esquema. Por exemplo: "listar todos os artefatos do tipo MyCustomModel".

Para definir um esquema personalizado, é necessário criar um recurso MetadataSchema em um MetadataStore específico que descreva o esquema esperado. O formato do esquema é um subconjunto da especificação OpenAPI 3.0 {class: external}, com a restrição de que o esquema de nível superior precisa ser do tipo object. Todos os tipos de dados compatíveis com OpenAPI 3.0 (por exemplo, número inteiro, número, string, booleano, matriz, objeto) são compatíveis como propriedades desse objeto de esquema de nível superior. Uma restrição é que cada campo na seção de propriedades pode ser atribuído a apenas um tipo de dados. Tipos mistos não são compatíveis. Requisitos de dados avançados, como mínimo, máximo, múltiplos e strings, também não são compatíveis.

Como registrar seus próprios esquemas personalizados

O processo de criação de um MetadataSchema personalizado é semelhante à criação de novos recursos de metadados. As instruções a seguir mostram como criar um MetadataSchema de amostra. O escopo dos metadados de metadados é definido apenas para o MetadataStore associado.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION_ID: a região do seu MetadataStore;
  • PROJECT_ID: ID ou número do projeto.
  • METADATA_STORE: o ID de armazenamento de metadados em que o MetadataSchema é criado. O armazenamento de metadados padrão é chamado de default. A menos que um novo MetadataStore seja necessário, você pode usar o armazenamento padrão.
  • METADATA_SCHEMA_ID: opcional: o ID do registro do MetadataSchema. Se o ID não for especificado, o Vertex ML Metadata criarão um identificador exclusivo para esse MetadataSchema .
  • METADATA_SCHEMA_TITLE: o título do esquema que descreve o campo de metadados. O título do esquema precisa atender ao formato ".". O namespace precisa começar com uma letra minúscula, pode conter caracteres minúsculos e números e pode ter de dois a vinte caracteres. O nome do esquema precisa começar com uma letra maiúscula, incluir letras e números e ter de 2 a 49 caracteres.
  • METADATA_SCHEMA_VERSION: (opcional): a versão do esquema que descreve o campo de metadados. schema_version precisa ser uma string com três números separados por pontos, por exemplo, 1.0.0, 1.0.1. Esse formato ajuda a ordenar e comparar versões.
  • METADATA_SCHEMA_TYPE: o tipo de recurso de metadados a que o esquema criado se aplica. Os tipos são: ARTIFACT_TYPE, EXECUTION_TYPE ou CONTEXT_TYPE.
  • METADATA_SCHEMA: o esquema detalhado a ser criado.
  • DESCRIPTION: (opcional) uma string legível que descreve a finalidade da execução a ser criada.
  • ARTIFACT_ID: (opcional) o ID do registro de artefato. Se o ID do artefato não for especificado, os Vertex ML Metadata cria um identificador exclusivo para esse artefato.
  • DISPLAY_NAME: (opcional) o nome definido pelo usuário para o artefato.

Método HTTP e 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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Será exibido um código semelhante a este. É possível usar METADATA_SCHEMA_ID, que é o ID do registro do 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"
}

As chamadas subsequentes para criar, receber ou listar artefatos podem se referir a esse esquema especificando o nome (demo.Artifact) no campo schema_title e a versão (0.0.1) no schema_version do recurso Artifact. Para mais informações sobre como criar, receber ou listar recursos de metadados, consulte Rastrear Vertex ML Metadata.

Controle da versão dos esquemas

Todos os recursos de MetadataSchema têm versões. Um usuário pode criar um esquema que usa o mesmo schema_title de outro esquema, mas um schema_version diferente. Para criar um recurso metadataSchema com uma versão diferente, um usuário pode fornecer um número de versão diferente e um conteúdo de esquema modificado.

O exemplo a seguir cria uma versão 0.0.2 do 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)

Os campos no esquema são sempre considerados opcionais. Portanto, não há compatibilidade com versões anteriores do mesmo schema_title. Os usuários ainda podem usar o schema_title para filtrar e agrupar recursos para análise. Para mais informações sobre como usar as funções de filtro, consulte Como analisar metadados do Vertex ML.

A seguir