Rastrear metadados do Vertex ML

Com o Vertex ML Metadata, é possível rastrear e analisar os metadados produzidos pelos fluxos de trabalho de machine learning (ML). Se você não estiver familiarizado com o Vertex ML Metadata, leia a introdução do Vertex ML Metadata para saber mais sobre como rastrear e analisar os metadados do fluxo de trabalho de ML.

Neste guia, você verá como registrar metadados usando o seguinte processo:

  1. Crie uma execução que represente uma etapa no fluxo de trabalho de ML.
  2. Procure artefatos para encontrar artefatos de entrada que já foram gravados no seu armazenamento de metadados.
  3. Crie artefatos para as entradas de execução que ainda não estão gravadas no armazenamento de metadados e quaisquer saídas produzidas por essa execução.
  4. Crie eventos para representar a relação entre sua execução e os artefatos de entrada e saída.

  5. Opcionalmente, adicione a execução e os artefatos a um contexto. Use um contexto para agrupar conjuntos de execuções e artefatos. Por exemplo, se você estiver tentando encontrar o melhor conjunto de hiperparâmetros para treinar um modelo, cada experimento poderá ser uma execução diferente com um conjunto de parâmetros e métricas próprio. Você pode comparar as execuções em um contexto para encontrar o experimento que produziu o melhor modelo.

    Antes de adicionar execução e artefatos a um contexto, crie um contexto.

Há duas maneiras de criar recursos de metadados da Vertex ML. É possível usar comandos REST ou o SDK da Vertex AI para Python. O SDK do Python simplifica a criação e a descoberta de vários tipos de recursos. Ao criar execuções usando Python, o payload não precisa ser construído manualmente.

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 você quiser criptografar seus metadados com uma chave de criptografia gerenciada pelo cliente (CMEK), crie seu armazenamento de metadados com uma 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.

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.

REST

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

  • LOCATION_ID: sua região.
  • PROJECT_ID: o ID 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: o ID do registro de execução. Se o ID de execução não for especificado, o Vertex ML Metadata cria 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. Este campo é gerenciado por aplicativos cliente. O Vertex ML Metadata não verifica a validade das transições de estado.
  • 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: (opcional) propriedades que descrevem a execução, como os parâmetros de execução.
  • DESCRIPTION: (opcional) Uma string legível por humanos, que descreve o propósito da execução a ser criada.
  • LABELS: opcional. (opcional): metadados definidos pelo usuário para organizar suas execuções.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/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
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "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

from typing import Any, Dict, List, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import execution_schema


def create_execution_sample(
    display_name: str,
    input_artifacts: List[aiplatform.Artifact],
    output_artifacts: List[aiplatform.Artifact],
    project: str,
    location: str,
    execution_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    with execution_schema.ContainerExecution(
        display_name=display_name,
        execution_id=execution_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create() as execution:
        execution.assign_input_artifacts(input_artifacts)
        execution.assign_output_artifacts(output_artifacts)
        return execution
  • display_name: o nome de exibição da execução. Esse campo pode conter até 128 caracteres Unicode.
  • input_artifacts: uma lista de uma ou mais instâncias do aiplatform.Artifact que representa um artefato de entrada.
  • output_artifacts: uma lista de uma ou mais instâncias do aiplatform.Artifact que representa um artefato de saída.
  • project: o ID do projeto. Esses IDs estão na página de boas-vindas do console do Google Cloud.
  • location: Consulte a Lista de locais disponíveis.
  • execution_id: o ID do registro de execução. Se o ID de execução não for especificado, o Vertex ML Metadata cria um identificador exclusivo para essa execução.
  • metadata: propriedades que descrevem a execução, como os parâmetros de execução.
  • schema_version: a versão do esquema que descreve o campo de metadados.
  • description: (opcional) uma string legível que descreve a finalidade da execução a ser criada.

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.

REST

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

  • LOCATION_ID: sua região.
  • PROJECT_ID: o ID do projeto.
  • METADATA_STORE: o ID do armazenamento de metadados em que o artefato é criado. O armazenamento de metadados padrão é chamado de default.
  • PAGE_SIZE: (opcional) o número máximo de artefatos a serem retornados. Se esse valor não for especificado, o serviço retornará no máximo 100 registros.
  • PAGE_TOKEN: (opcional) um token de página de uma chamada anterior 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN&filter=FILTER

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

Será exibido um código semelhante a este. ARTIFACT_ID é o ID do registro de artefato.

{
  "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

from typing import Optional

from google.cloud import aiplatform


def list_artifact_sample(
    project: str,
    location: str,
    display_name_filter: Optional[str] = "display_name=\"my_model_*\"",
    create_date_filter: Optional[str] = "create_time>\"2022-06-11\"",
    order_by: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    combined_filters = f"{display_name_filter} AND {create_date_filter}"
    return aiplatform.Artifact.list(
        filter=combined_filters,
        order_by=order_by,
    )
  • project: o ID do projeto. Esses IDs estão na página de boas-vindas do console do Google Cloud.
  • location: Consulte a Lista de locais disponíveis.
  • display_name_filter: filtro a ser aplicado no nome de exibição, listando os recursos com o formato "display_name=\"my_filter\"".
  • create_date_filter: filtro a ser aplicado no nome create_date, listando os recursos com o formato "create_time>\"2022-06-11T12:30:00-08:00\"",.

Criar um artefato

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

REST

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

  • LOCATION_ID: sua região.
  • PROJECT_ID: o ID do projeto.
  • METADATA_STORE: o ID do armazenamento de metadados em que o artefato é criado. O armazenamento de metadados padrão é chamado de default.
  • 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.
  • 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. O Vertex ML Metadata não verifica a validade das transições de estado.
  • 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: opcional. Propriedades que descrevem o artefato, como o tipo de conjunto de dados.
  • DESCRIPTION: (opcional) uma string legível que descreve a finalidade da execução a ser criada.
  • LABELS: opcional. Metadados definidos pelo usuário para organizar seus artefatos.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/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
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "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

from typing import Dict, Optional

from google.cloud.aiplatform.metadata.schema.system import artifact_schema


def create_artifact_sample(
    project: str,
    location: str,
    uri: Optional[str] = None,
    artifact_id: Optional[str] = None,
    display_name: Optional[str] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
    metadata: Optional[Dict] = None,
):
    system_artifact_schema = artifact_schema.Artifact(
        uri=uri,
        artifact_id=artifact_id,
        display_name=display_name,
        schema_version=schema_version,
        description=description,
        metadata=metadata,
    )
    return system_artifact_schema.create(project=project, location=location,)
  • project: o ID do projeto. Esses IDs estão na página de boas-vindas do console do Google Cloud.
  • location: Consulte a Lista de locais disponíveis.
  • uri: (opcional) o identificador uniforme de recurso do arquivo de artefato, se houver. Poderá estar vazio se não houver um arquivo de artefato real.
  • 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.
  • schema_version: A versão do esquema que descreve o campo de metadados.
  • description: (opcional) uma string legível que descreve a finalidade do artefato a ser criado.
  • metadata: propriedades que descrevem o artefato, como os parâmetros dele.

Criar eventos para vincular artefatos a uma execução

Os eventos representam a relação entre uma execução, as entradas e os artefatos de saída. Use as instruções a seguir para criar eventos e vincular artefatos a uma execução.

REST

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

  • LOCATION_ID: sua região.
  • PROJECT_ID: o ID 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: o ID do registro de execução.

  • ARTIFACT: o nome do recurso do artefato. O nome do recurso é criado da seguinte maneira: projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID

  • EVENT_TYPE: (opcional) um valor de enumeração EventType que especifica se o artefato é uma entrada ou saída da execução.

Método HTTP e URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:addExecutionEvents

Corpo JSON da solicitação:

{
  "events": [
    {
      "artifact": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID",
      "type": "EVENT_TYPE"
    }
  ]
}

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

Você receberá um código de status de êxito (2xx) e uma resposta vazia.

Python

Python

from typing import Any, Dict, List, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import execution_schema


def create_execution_sample(
    display_name: str,
    input_artifacts: List[aiplatform.Artifact],
    output_artifacts: List[aiplatform.Artifact],
    project: str,
    location: str,
    execution_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    with execution_schema.ContainerExecution(
        display_name=display_name,
        execution_id=execution_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create() as execution:
        execution.assign_input_artifacts(input_artifacts)
        execution.assign_output_artifacts(output_artifacts)
        return execution
  • input_artifacts: uma lista de uma ou mais instâncias do aiplatform.Artifact que representa um artefato de entrada.
  • output_artifacts: uma lista de uma ou mais instâncias do aiplatform.Artifact que representa um artefato de saída.
  • project: o ID do projeto. Esses IDs estão na página de boas-vindas do console do Google Cloud.
  • location: Consulte a Lista de locais disponíveis.
  • execution_id: o ID do registro de execução. Se o ID de execução não for especificado, o Vertex ML Metadata cria um identificador exclusivo para essa execução.
  • metadata: propriedades que descrevem a execução, como os parâmetros de execução.
  • schema_version: A versão do esquema que descreve o campo de metadados.
  • description: (opcional) uma string legível que descreve a finalidade da execução a ser criada.

Criar um contexto

Os contextos permitem agrupar conjuntos de artefatos e execuções. Use as instruções a seguir para criar um contexto. Os experimentos da Vertex AI criam um contexto que registra automaticamente artefatos e execuções nesse contexto. Consulte Criar ou excluir um experimento.

REST

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

  • LOCATION_ID: sua região.
  • PROJECT_ID: o ID 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.
  • PARENT_CONTEXT: especifique o nome do recurso 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. 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: propriedades que descrevem o contexto, como os parâmetros.
  • DESCRIPTION: (opcional) uma string legível que descreve a finalidade da execução a ser criada.
  • LABELS: opcional. Metadados definidos pelo usuário para organizar seus contextos.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/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
  },
  "labels": {"LABEL_1":"LABEL_2"},
  "description": "DESCRIPTION"

}

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

Será exibido um código semelhante a este. CONTEXT_ID é o ID do registro de contexto.

{
  "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

from typing import Any, Dict, Optional

from google.cloud import aiplatform
from google.cloud.aiplatform.metadata.schema.system import context_schema


def create_context_sample(
    display_name: str,
    project: str,
    location: str,
    context_id: Optional[str] = None,
    metadata: Optional[Dict[str, Any]] = None,
    schema_version: Optional[str] = None,
    description: Optional[str] = None,
):
    aiplatform.init(project=project, location=location)

    return context_schema.Experiment(
        display_name=display_name,
        context_id=context_id,
        metadata=metadata,
        schema_version=schema_version,
        description=description,
    ).create()
  • display_name: o nome de exibição do contexto. Esse campo pode conter até 128 caracteres Unicode.
  • project: o ID do projeto. Esses IDs estão na página de boas-vindas do console do Google Cloud.
  • location: Consulte a Lista de locais disponíveis.
  • context_id (opcional): o ID do registro de contexto.
  • metadata: propriedades que descrevem o contexto, como os parâmetros.
  • schema_version: A versão do esquema que descreve o campo de metadados.
  • description: (opcional) uma string legível que descreve a finalidade do contexto a ser criado.

Adicionar artefatos e execuções a um contexto

Use as instruções a seguir para adicionar artefatos e execuções a um contexto.

REST

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

  • LOCATION_ID: sua região.
  • PROJECT_ID: o ID 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 (opcional): o ID do registro de contexto.

  • Especifique o nome do recurso ARTIFACT dos artefatos que você quer adicionar a esse contexto. O nome do recurso tem o seguinte formato:

    projects/PROJECT_ID/locations/location/metadataStores/metadata-store/artifacts/artifact

  • Especifique o nome do recurso EXECUTION para todas as execuções que você quiser adicionar a esse contexto. O nome do recurso tem o seguinte formato:

    projects/PROJECT_ID/locations/location/metadataStores/metadata-store/executions/execution

Método HTTP e URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT:addContextArtifactsAndExecutions

Corpo JSON da solicitação:

{
  "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"
  ]
}

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

Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.

Notebooks

A seguir