É possível usar o Vertex ML Metadata para rastrear e analisar os metadados produzidos pelos sistemas de machine learning (ML). Ao acompanhar esses metadados, fica mais fácil analisar o comportamento do seu sistema de ML. Isso pode ajudar a entender as mudanças no desempenho do sistema ou a comparar os artefatos produzidos pelo sistema de ML.
Se você está começando a usar o Vertex ML Metadata, leia a introdução sobre o Vertex ML Metadata para saber mais sobre como rastrear e analisar os metadados do fluxo de trabalho de ML.
Saiba como consultar os metadados de Vertex ML que você quer analisar das seguintes maneiras:
- Consulte todos os artefatos, execuções ou contextos que correspondem aos critérios de filtragem.
- Consulte os artefatos de entrada e saída de uma execução junto com os eventos usados para conectar os artefatos à execução.
- Consulte o subgráfico de linhagem de um contexto. Essa consulta retorna artefatos e execuções de um contexto, além dos eventos que conectam artefatos às execuções.
Consultar artefatos, execuções e contextos
É possível usar o SDK Vertex AI para Python ou a API REST para consultar artefatos, execuções e registros de contextos usando filtros para criar consultas como as seguintes:
- Quais versões de um modelo treinado atingiram um determinado limite de qualidade?
- Qual conjunto de dados é usado em um determinado pipeline?
As seções a seguir demonstram comocriar filtros e como consultarartefatos .Execuções econtextos.
Visão geral da sintaxe de filtros
As seções a seguir descrevem como usar filtros para consultar artefatos, execuções e contextos.
Campos
Os campos a seguir são compatíveis com a filtragem de artefatos, execuções e contextos.
Artefato | Execução | Contexto | |
---|---|---|---|
name |
|||
display_name |
|||
schema_title |
|||
create_time |
|||
update_time |
|||
metadata |
|||
state |
|||
uri |
Seu filtro precisa ser colocado entre aspas, e todas as aspas que fazem parte do filtro precisam ser escapadas com uma barra invertida.
Operadores de comparação
É possível usar os seguintes operadores de comparação nos filtros: =
, !=
, <
, >
, >=
, <=
.
Por exemplo, os filtros a seguir para encontrar todos os artefatos em que o nome de exibição é my_artifact.
REST
display_name=\"my_artifact\"
Python
"display_name=\"my_artifact\""
Para campos de string, é possível usar a filtragem de caracteres curinga com o caractere *
.
Para campos de carimbo de data/hora, como create_time
e update_time
, formate a data usando o formato RFC 3339, por exemplo:
REST
create_time=\"2021-05-11T12:30:00-08:00\"
Python
"create_time=\"2021-05-11T12:30:00-08:00\""
Operadores lógicos
Use os operadores lógicos AND
e OR
para combinar filtros e criar uma consulta complexa.
O exemplo a seguir demonstra como consultar artefatos do tipo ai_platform.model
e um campo metadata
precision
com um valor numérico maior que 0,9.
REST
schema_title=\"ai_platform.Model\"+AND+metadata.precision.number_value>0.9
Python
"create_time=\"schema_title=\"ai_platform.Model\" AND metadata.precision.number_value>0.9"
Filtrar por metadados usando o operador de travessia
O campo metadata
é uma instância de google.protobuf.Struct
com o formato definido no esquema especificado no campo schema_title
. google.protobuf.Struct
é uma estrutura de dados que mapeia chaves para instâncias google.protobuf.Value
. A estrutura de dados de google.protobuf.Value
armazena
valores em campos diferentes, dependendo do tipo de dados. Por exemplo:
- strings são armazenadas como
metadata.FIELD_NAME.string_value
; - números são armazenados como
metadata.FIELD_NAME.number_value
; - booleanos são armazenados como
metadata.FIELD_NAME.bool_value
.
Para filtrar por metadata
, use o operador de passagem para percorrer o campo que você quer filtrar. O operador de travessia usa o formato a seguir.
REST
metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\"
Python
"metadata.FIELD_NAME.TYPE_NAME=\"FILTER_VALUE\""
Por exemplo, considere uma estrutura de metadados como esta:
{
"field_1": 5,
"field_2": "example",
"field_3": {
...
},
"field_4": [],
"field_5": true,
}
As consultas a seguir ilustram como usar o operador de travessia para filtrar esses metadados de exemplo.
Filtre os registros que tenham
metadata.field_1
com um valor menor que 5.
REST
metadata.field_1.number_value<5
Python
"metadata.field_1.number_value<5"
Filtre por registros que tenham
metadata.field_2
com um valor igual ao example.
REST
metadata.field_2.string_value=\"example\"
Python
"metadata.field_2.string_value=\"example\""
Filtre por registros que tenham
metadata.field_5
com um valor igual a true.
REST
metadata.field_5.bool_value=true
Python
"metadata.field_5.bool_value=true"
Filtrar contextos pelos relacionamentos pai e filho
Você pode usar o operador has para encontrar contextos que sejam pai ou filho de um contexto especificado.
O operador has usa o seguinte formato:
"parent_contexts:\"CONTEXT_RESOURCE_NAME\""
"child_contexts:\"CONTEXT_RESOURCE_NAME\""
O nome do contexto precisa ser o nome completo do recurso do contexto, como: project/PROJECT/locations/LOCATION/metadataStores/METADATA-STORE/contexts/CONTEXT
.
Os filtros a seguir demonstram como usar o operador "contém":
Filtre todos os contextos que são filhos do pipeline especificado.
REST
parent_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\"
Python
"parent_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""
Filtre todos os contextos que são pai do pipeline especificado.
REST
child_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\"
Python
"child_contexts:\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\""
Filtrar contextos, execuções e artefatos por associação e atribuição
Use a função in_context()
para filtrar artefatos ou execuções que estão associados a um contexto. É possível usar a função with_execution()
para filtrar artefatos ou contextos específicos associados a uma
execução. Da mesma forma, é possível usar a função with_artifact()
para filtrar execuções ou contextos específicos associados a um artefato.
As funções de filtro são usadas no seguinte formato.
"in_context(\"CONTEXT_RESOURCE_NAME\")"
"with_execution(\"EXECUTION_RESOURCE_NAME\")"
"with_artifact(\"ARTIFACT_RESOURCE_NAME\")"
O contexto, a execução e os nomes do artefato precisam ser o nome completo do recurso, como o seguinte.
project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/contexts/CONTEXT
project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/executions/EXECUTION
project/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA-STORE/artifacts/ARTIFACT
O exemplo a seguir demonstra como filtrar objetos que estão no pipeline especificado.
REST
in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")
Python
"in_context(\"project/12345/locations/us-central1/metadataStores/default/contexts/pipeline_1\")"
Você pode usar um caractere curinga *
nas funções de filtro para refinar os parâmetros de
cada recurso. Por exemplo, é possível usar o filtro a seguir para filtrar todas as execuções que funcionam em um tipo de artefato system.model
.
REST
with_artifact(\"*\",\"schema_title='name.model'\")
Python
"with_artifact(\"*\",\"schema_title='name.model'\")"
Veja outros parâmetros compatíveis que podem ser filtrados:
input=true/false
: filtra tipos de artefatos de entrada ou saída.event_time
: filtra os tempos dos eventos de execuções ou artefatos.- Todos os outros campos de filtro compatíveis
É possível combinar os campos com Operandos lógicos para criar consultas de filtro complexas. A profundidade máxima permitida da função aninhada é 5.
Consultar artefatos
Os artefatos, como conjuntos de dados e modelos, representam dados usados ou produzidos pelo fluxo de trabalho de ML. Use as instruções a seguir para consultar artefatos.
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
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\"",.
Consultar execuções
As execuções representam uma etapa no fluxo de trabalho de ML, como o pré-processamento de dados ou o treinamento de um modelo. Use as instruções a seguir para consultar execuções.
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
. - 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 uma execução 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/executions?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. EXECUTION_ID é o ID do registro de execução.
{ "executions": [ { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "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": "Description of the example execution." }, { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "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": "Description of the example execution." } ] }
Python
Python
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\"",.
Consultar contextos
Os contextos permitem agrupar conjuntos de execuções, artefatos e outros contextos. Use as instruções a seguir para consultar contextos.
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 contexto é 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 contexto 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/contexts?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. CONTEXT_ID é o ID do registro de contexto.
{ "contexts": [ { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID", "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/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID", "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": {} } ] }
Consultar artefatos de entrada e saída de uma execução
Use as instruções a seguir para consultar os artefatos e execuções no contexto especificado, além dos eventos que conectam artefatos às execuções.
SDK da Vertex AI para Python
Artefatos de entrada
Esta amostra de SDK do Python envolve a consulta de artefatos de entrada de uma execução.
Python
Artefatos de saída
Esta amostra de SDK do Python envolve a consulta de artefatos de saída de uma execução.
Python
REST
Esta amostra REST inclui a consulta de artefatos de entrada e saída de 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.
Método HTTP e URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID:queryExecutionInputsAndOutputs
Para enviar a solicitação, expanda uma destas opções:
Será exibido um código semelhante a este. EXECUTION_ID é 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. ARTIFACT_ID é o ID do registro de artefato.
{ "artifacts": [ { "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "displayName": "Example artifact", "uri": "gs://your_bucket_name/artifacts/dataset.csv", "etag": "678901011", "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." }, { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "displayName": "Example artifact 2", "uri": "gs://your_bucket_name/artifacts/dataset.csv", "etag": "678901011", "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." } ], "executions": [ { "name": "projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "displayName": "Example execution 1", "etag": "678901011", "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." } ], "events": [ { "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "INPUT", }, { "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "OUTPUT", } ] }
Consultar o subgráfico de linhagem de um contexto
Use as instruções a seguir para consultar os artefatos e execuções no contexto especificado, além dos eventos que conectam artefatos às execuções.
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.
Método HTTP e URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataStores/METADATA_STORE/contexts/CONTEXT_ID:queryContextLineageSubgraph
Para enviar a solicitação, expanda uma destas opções:
Será exibido um código semelhante a este. EXECUTION_ID é 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. ARTIFACT_ID é o ID do registro de artefato.
{ "artifacts": [ { "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "displayName": "Example artifact", "uri": "gs://your_bucket_name/artifacts/dataset.csv", "etag": "678901011", "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." }, { "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "displayName": "Example artifact 2", "uri": "gs://your_bucket_name/artifacts/dataset.csv", "etag": "678901011", "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." } ], "executions": [ { "name": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "displayName": "Example execution 1", "etag": "678901011", "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." } ], "events": [ { "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "INPUT", }, { "artifact": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/artifacts/ARTIFACT_ID", "execution": "projects/PROJECT_ID/locations/LOCATION/metadataStores/METADATA_STORE/executions/EXECUTION_ID", "eventTime": "2021-05-18T00:04:49.659Z",, "type": "OUTPUT", } ] }