Gerenciar metadados de ML

Este guia demonstra como gerenciar seus metadados de ML.

Antes de começar

Na primeira vez que você usa os metadados do Vertex ML em um projeto do Google Cloud, o Vertex AI cria o armazenamento de metadados do seu projeto.

Se quiser que seus metadados sejam criptografados com uma chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês), será preciso criar seu armazenamento de metadados com um CMEK antes de usar o Vertex ML Metadata para rastrear ou analisar metadados. Use criar um armazenamento de metadados que use uma CMEK para configurar o armazenamento de metadados do seu projeto.

Gerenciamento de artefatos

Criar um artefato

Use as instruções a seguir para criar um artefato.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o artefato é criado. O armazenamento de metadados padrão é denominado default.
  • ARTIFACT_ID: opcional. O ID do registro de artefato. Se o ID do artefato não for especificado, os metadados do ML do Vertex criaram um identificador exclusivo para esse artefato.
  • DISPLAY_NAME: o nome de exibição do artefato. Esse campo pode conter até 128 caracteres Unicode.
  • URI: opcional. O local onde o artefato é armazenado.
  • ARTIFACT_STATE: opcional. Um valor da enumeração de estado que representa o estado atual do artefato. Este campo é gerenciado por aplicativos cliente. Os metadados do Vertex ML não verificam a validade das transições de estado.
  • METADATA_SCHEMA_TITLE: o título do esquema que descreve o campo de metadados.
  • METADATA_SCHEMA_VERSION: opcional. A versão do esquema que descreve o campo de metadados.
  • METADATA: opcional. Propriedades que descrevem o artefato, como o tipo de conjunto de dados.
  • DESCRIPTION: opcional. Uma descrição da execução.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts?artifactId=ARTIFACT_ID

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME",
  "uri": "URI",
  "state": "ARTIFACT_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "description": "DESCRIPTION"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact",
  "displayName": "Example artifact",
  "uri": "gs://your_bucket_name/artifacts/dataset.csv",
  "etag": "67891011",
  "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."
}

Pesquisar um artefato existente

Os artefatos representam dados usados ou produzidos pelo fluxo de trabalho de ML, como conjuntos de dados e modelos. Use as instruções a seguir para procurar um artefato existente.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o artefato é criado. O armazenamento de metadados padrão é denominado default.
  • PAGE_SIZE: opcional. O número máximo de artefatos a serem retornados. Se esse valor não for especificado, um máximo de 100 registros será retornado.
  • PAGE_TOKEN: opcional. Um token de página de uma chamada anterior de MetadataService.ListArtifacts. Especifique esse token para ver a próxima página de resultados.
  • FILTER: especifica as condições necessárias para incluir um artefato no conjunto de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

Você receberá uma resposta JSON semelhante a esta:

{
  "artifacts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact",
      "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/12345/locations/us-central1/metadataStores/default/artifacts/example-artifact-2",
      "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."
    }
  ]
}

Excluir um artefato existente

Use as instruções a seguir para excluir um artefato.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o artefato foi criado. O armazenamento de metadados padrão é chamado de default
  • ARTIFACT_ID: o ID do registro de artefato a ser excluído.

Método HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID/operations/85544",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2021-07-21T20:05:30.179713Z",
      "updateTime": "2021-07-21T20:05:30.179713Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Limpar artefatos

Use as instruções a seguir para excluir vários artefatos com base em uma condição de filtro.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que os artefatos foram criados. O armazenamento de metadados padrão é chamado de default
  • FILTER: especifica as condições exigidas pelos artefatos a serem excluídos. Por exemplo:
    • Filtros para todos os artefatos que contêm exemplo no nome de exibição: "display_name = \"*example*\"".
    • Filtros para todos os artefatos criados antes de 2020-11-19T11:30:00-04:00: "create_time < \"2020-11-19T11:30:00-04:00\"".
  • FORCE: indica se a limpeza real será executada ou não. Se a sinalização for definida como falsa, o método retornará uma amostra de nomes de artefatos que seriam excluídos.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/artifacts:purge

Corpo JSON da solicitação:

{
  "filter": "FILTER",
  "force": FORCE
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/operations/11531",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.PurgeArtifactsMetadata",
    "genericMetadata": {
      "createTime": "2021-07-21T21:02:33.757991Z",
      "updateTime": "2021-07-21T21:02:33.757991Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.PurgeArtifactsResponse",
    "purgeCount": "15"
  }
}

Gerenciamento de execução

Criar execução

As execuções representam uma etapa do seu fluxo de trabalho de ML. Use as instruções a seguir para criar uma execução.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução é criada. O armazenamento de metadados padrão é chamado de default.
  • EXECUTION_ID: opcional. O ID do registro de execução. Se o ID de execução não for especificado, o Vertex ML Metadata criou um identificador exclusivo para essa execução.
  • DISPLAY_NAME: o nome de exibição da execução. Esse campo pode conter até 128 caracteres Unicode.
  • EXECUTION_STATE: opcional. Um valor da enumeração de estado que representa o estado atual da execução. Esse campo é gerenciado por aplicativos clientes. Os metadados do Vertex ML não verificam a validade das transições de estado.
  • METADATA_SCHEMA_TITLE: o título do esquema que descreve o campo de metadados.
  • METADATA_SCHEMA_VERSION: opcional. A versão do esquema que descreve o campo de metadados.
  • METADATA: opcional. Propriedades que descrevem a execução, como os parâmetros de execução.
  • DESCRIPTION: opcional. Uma descrição da execução.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions?executionId=EXECUTION_ID

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME",
  "state": "EXECUTION_STATE",
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "description": "DESCRIPTION"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution",
  "displayName": "Example Execution",
  "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."
}

Procurar uma execução existente

Use as instruções a seguir para procurar uma execução existente.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução é criada. O armazenamento de metadados padrão é chamado de default.
  • PAGE_SIZE: opcional. O número máximo de execuções a serem retornadas. Se esse valor não for especificado, um máximo de 100 registros será retornado.
  • PAGE_TOKEN: opcional. Um token de página de uma chamada MetadataService.ListExecutions anterior. Especifique esse token para receber a próxima página de resultados.
  • FILTER: especifica as condições necessárias para incluir uma execução no conjunto de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

Você receberá uma resposta JSON semelhante a esta:

{
  "executions": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-1",
      "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": "Descrption of the example execution."
    },
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/executions/example-execution-2",
      "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": "Descrption of the example execution."
    }
  ]
}

Excluir uma execução existente

Use as instruções a seguir para excluir uma execução.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução foi criado. O armazenamento de metadados padrão é chamado de default
  • EXECUTION_ID: o ID do registro de execução a ser excluído.

Método HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID/operations/85544",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2021-07-21T20:05:30.179713Z",
      "updateTime": "2021-07-21T20:05:30.179713Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Limpar execuções

Use as instruções a seguir para excluir várias execuções com base em uma condição de filtro.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que as execuções são criadas. O armazenamento de metadados padrão é chamado de default
  • FILTER: especifica as condições exigidas pelas execuções a serem excluídas. Por exemplo:
    • Filtros para todos as execuções que contêm exemplo no nome de exibição: "display_name = \"*example*\"".
    • Filtros para todas as execuções criadas antes de 2020-11-19T11:30:00-04:00: "create_time < \"2020-11-19T11:30:00-04:00\"".
  • FORCE: indica se a limpeza real será executada ou não. Se a sinalização for definida como falsa, o método retornará uma amostra de nomes de execuções que seriam excluídas.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/executions:purge

Corpo JSON da solicitação:

{
  "filter": "FILTER",
  "force": FORCE
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/operations/11531",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.PurgeExecutionsMetadata",
    "genericMetadata": {
      "createTime": "2021-07-21T21:02:45.757991Z",
      "updateTime": "2021-07-21T21:02:45.757991Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.PurgeExecutionsResponse",
    "purgeCount": "2"
  }
}

Gerenciamento de contexto

Criar um contexto

Os contextos permitem agrupar conjuntos de artefatos e execuções. Use as instruções a seguir para criar um contexto.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que a execução é criada. O armazenamento de metadados padrão é chamado de default.
  • CONTEXT_ID: opcional. O ID do registro de contexto. Se o ID de contexto não for especificado, os metadados de ML do Vertex criaram um identificador exclusivo para esse contexto.
  • DISPLAY_NAME: o nome de exibição do contexto. Esse campo pode conter até 128 caracteres Unicode.
  • Especifique o nome do recurso PARENT_CONTEXT para qualquer contexto pai. Um contexto não pode ter mais de 10 contextos pai.
  • METADATA_SCHEMA_TITLE: o título do esquema que descreve o campo de metadados.
  • METADATA_SCHEMA_VERSION: opcional. A versão do esquema que descreve o campo de metadados.
  • METADATA: opcional. Propriedades que descrevem o contexto.
  • DESCRIPTION: opcional. Uma descrição da execução.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts?contextId=CONTEXT_ID

Corpo JSON da solicitação:

{
  "displayName": "DISPLAY_NAME:",
  "parentContexts": [
    "PARENT_CONTEXT_1",
    "PARENT_CONTEXT_2"
  ],
  "schemaTitle": "METADATA_SCHEMA_TITLE",
  "schemaVersion": "METADATA_SCHEMA_VERSION",
  "metadata": {
    METADATA
  },
  "description": "DESCRIPTION"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/12345/locations/us-central1/metadataStores/default/contexts/example-context",
  "displayName": "Example context:",
  "etag": "67891011",
  "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."
}

Pesquisar um contexto existente

Use as instruções a seguir para procurar um contexto existente.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o contexto é criado. O armazenamento de metadados padrão é denominado default.
  • PAGE_SIZE: opcional. O número máximo de contextos a serem retornados. Se esse valor não for especificado, serão retornados no máximo 100 registros.
  • PAGE_TOKEN: opcional. Um token de página de uma chamada MetadataService.ListExecutions anterior. Especifique esse token para ver a próxima página de resultados.
  • FILTER: especifica as condições necessárias para incluir um contexto no conjunto de resultados.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

Você receberá uma resposta JSON semelhante a esta:

{
  "contexts": [
    {
      "name": "projects/12345/locations/us-central1/metadataStores/default/contexts/experiment-1",
      "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/12345/locations/us-central1/metadataStores/default/contexts/pipeline-run-1",
      "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": {}
    }
  ]
}

Excluir um contexto existente

Use as instruções a seguir para excluir um contexto.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do armazenamento de metadados em que o contexto foi criado. O armazenamento de metadados padrão é chamado de default
  • CONTEXT_ID: o ID do registro de contexto a ser excluído.

Método HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts/CONTEXT_ID

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts/CONTEXT_ID/operations/85544",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2021-07-21T20:05:30.179713Z",
      "updateTime": "2021-07-21T20:05:30.179713Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Limpar contextos

Use as instruções a seguir para excluir vários contextos com base em uma condição de filtro.

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • METADATA_STORE: o ID do repositório de metadados em que os contextos foram criados. O armazenamento de metadados padrão é chamado de default
  • FILTER: especifica as condições exigidas pelos contextos a serem excluídos. Por exemplo:
    • Filtros para todos os contextos que contêm exemplo no nome de exibição: "display_name = \"*example*\"".
    • Filtros para todos os contextos criados antes de 2020-11-19T11:30:00-04:00: "create_time < \"2020-11-19T11:30:00-04:00\"".
  • FORCE: indica se a limpeza real será executada ou não. Se a sinalização for definida como falsa, o método retornará uma amostra de nomes de execuções que seriam excluídas.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/contexts:purge

Corpo JSON da solicitação:

{
  "filter": "FILTER",
  "force": FORCE
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT/locations/LOCATION/metadataStores/METADATA_STORE/operations/11531",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.PurgeContextsMetadata",
    "genericMetadata": {
      "createTime": "2021-07-21T21:02:40.757991Z",
      "updateTime": "2021-07-21T21:02:40.757991Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.PurgeContextsResponse",
    "purgeCount": "5"
  }
}

A seguir