Detectar desvios e deslocamentos de recursos

Nesta página, descrevemos como criar, gerenciar e interpretar os resultados de jobs de monitoramento de modelos para modelos implantados em endpoints de previsão on-line. O Vertex AI Model Monitoring é compatível com a detecção de desvios e deslocamentos de recursos de entrada categóricos e numéricos.

Quando um modelo é implantado em produção com o monitoramento de modelos ativado, as solicitações de previsão recebidas são registradas em uma tabela do BigQuery no seu projeto do Google Cloud. Em seguida, os valores de recursos de entrada contidos nas solicitações registradas são analisados em busca de distorção ou desvio.

Para ativar a detecção de desvio, forneça o conjunto de dados de treinamento original do modelo. Caso contrário, habilite a detecção de deslocamento. Para mais informações, consulte Introdução ao Monitoramento de modelos com a Vertex AI.

Pré-requisitos

Para usar o monitoramento de modelos, siga estas etapas:

  1. Tenha um modelo disponível na Vertex AI que seja um AutoML tabular ou um tipo de treinamento personalizado tabular importado.

    • Se você estiver usando um endpoint atual, verifique se todos os modelos implantados nele são do tipo AutoML tabular ou de treinamento personalizado importados.

  2. Se você estiver ativando a detecção de distorção, faça o upload dos dados de treinamento para o Cloud Storage ou o BigQuery e receba o link do URI para os dados. Para a detecção de desvio, os dados de treinamento não são necessários.

  3. Opcional: para modelos com treinamento personalizado, faça upload do esquema de instância de análise do modelo no Cloud Storage. O monitoramento de modelos requer o esquema para iniciar o processo de monitoramento e calcular a distribuição de valor de referência para a detecção de distorção. Se você não fornecer o esquema durante a criação do job, ele permanecerá em estado pendente até que o monitoramento de modelos possa analisá-lo automaticamente a partir das primeiras 1.000 solicitações de previsão recebidas pelo modelo.

Criar um job de monitoramento de modelo

Para configurar a detecção de distorção ou de deslocamento, crie um job de monitoramento de implantação de modelo:

Console

Para criar um job de monitoramento de implantação de modelo usando o console do Google Cloud, crie um endpoint:

  1. No Console do Google Cloud, acesse a página Vertex AI Endpoints.

    Acessar o Endpoints

  2. Clique em Criar endpoint.

  3. No painel Novo endpoint, nomeie seu endpoint e defina uma região.

  4. Clique em Continuar.

  5. No campo Nome do modelo, selecione um treinamento personalizado importado ou um modelo tabular do AutoML.

  6. No campo Versão, selecione uma versão para o modelo.

  7. Clique em Continuar.

  8. No painel Monitoramento de modelos, verifique se a opção Ativar o monitoramento de modelos para este endpoint está ativada. Todas as configurações de monitoramento que você definir se aplicam a todos os modelos implantados no endpoint.

  9. Digite um Nome de exibição do job de monitoramento.

  10. Insira uma Duração da janela de monitoramento.

  11. Em E-mails de notificação, insira um ou mais endereços de e-mail separados por vírgula para receber alertas quando um modelo exceder um limite de alerta.

  12. Opcional: em Canais de notificação, adicione canais do Cloud Monitoring para receber alertas quando um modelo exceder um limite de alertas. Selecione canais existentes do Cloud Monitoring ou crie um novo clicando em Gerenciar canais de notificação. O Console é compatível com os canais de notificação PagerDuty, Slack e Pub/Sub.

  13. Insira uma Taxa de amostragem.

  14. Opcional: insira o Esquema de entrada de previsão e o Esquema de entrada da análise.

  15. Clique em Continuar. O painel Objetivo de monitoramento é aberto, com opções para detecção de distorção ou desvio:

    Detecção de desvio

    1. Selecione Detecção de desvio de treinamento/disponibilização.
    2. Em Fonte de dados de treinamento, forneça uma fonte de dados de treinamento.
    3. Em Coluna de destino, insira o nome da coluna dos dados de treinamento que o modelo é treinado para prever. Esse campo é excluído da análise de monitoramento.
    4. Opcional: em Limites de alerta, especifique limites para acionar alertas. Para informações sobre como formatar os limites, passe o cursor sobre o ícone de ajuda .
    5. Clique em Criar.

    Detecção de desvio

    1. Selecione Detecção de desvio de previsão.
    2. Opcional: em Limites de alerta, especifique limites para acionar alertas. Para informações sobre como formatar os limites, passe o cursor sobre o ícone de ajuda .
    3. Clique em Criar.

gcloud

Para criar um job de monitoramento de implantação de modelo usando a CLI gcloud, primeiro implante o modelo em um endpoint:

Uma configuração de job de monitoramento se aplica a todos os modelos implantados em um endpoint.

Execute o comando gcloud ai model-monitoring-jobs create.

gcloud ai model-monitoring-jobs create \
  --project=PROJECT_ID \
  --region=REGION \
  --display-name=MONITORING_JOB_NAME \
  --emails=EMAIL_ADDRESS_1,EMAIL_ADDRESS_2 \
  --endpoint=ENDPOINT_ID \
  [--feature-thresholds=FEATURE_1=THRESHOLD_1, FEATURE_2=THRESHOLD_2] \
  [--prediction-sampling-rate=SAMPLING_RATE] \
  [--monitoring-frequency=MONITORING_FREQUENCY] \
  [--analysis-instance-schema=ANALYSIS_INSTANCE_SCHEMA] \
  --target-field=TARGET_FIELD \
  --bigquery-uri=BIGQUERY_URI

onde:

  • PROJECT_ID é o ID do seu projeto do Google Cloud. Por exemplo, my-project.

  • REGION é o local do job de monitoramento. Por exemplo, us-central1.

  • MONITORING_JOB_NAME é o nome do job de monitoramento. Por exemplo, my-job.

  • EMAIL_ADDRESS é o endereço de e-mail em que você quer receber alertas do monitoramento de modelos. Por exemplo, example@example.com.

  • ENDPOINT_ID é o ID do endpoint em que o modelo é implantado. Por exemplo, 1234567890987654321.

  • FEATURE_1=THRESHOLD_1: e : é o limite de alerta para cada recurso que você quer monitorar. Por exemplo, se você especificar Age=0.4, o monitoramento de modelos registrará um alerta quando a distância estatística entre as distribuições de entrada e referência para o recurso Age exceder 0,4. Por padrão, todos os atributos categóricos e numéricos são monitorados com valores limite de 0,3.

  • Opcional: SAMPLING_RATE é a fração das solicitações de previsão recebidas que você quer registrar. Por exemplo, 0.5. Se não for especificado, o monitoramento de modelos registrará todas as solicitações de previsão.

  • Opcional: MONITORING_FREQUENCY é a frequência com que você quer que o job de monitoramento seja executado nas entradas registradas recentemente. A granularidade mínima é de uma hora. O padrão é 24 horas. Por exemplo, 2.

  • Opcional: ANALYSIS_INSTANCE_SCHEMA é o URI do Cloud Storage para o arquivo de esquema que descreve o formato dos dados de entrada. Por exemplo, gs://test-bucket/schema.yaml.

  • (obrigatório apenas para a detecção de distorção) TARGET_FIELD é o campo que está sendo previsto pelo modelo. Esse campo é excluído da análise de monitoramento. Por exemplo, housing-price.

  • (obrigatório apenas para detecção de distorção) BIGQUERY_URI é o link para o conjunto de dados de treinamento armazenado no BigQuery, usando o seguinte formato:

    bq://\PROJECT.\DATASET.\TABLE

    Por exemplo, bq://\my-project.\housing-data.\san-francisco

    É possível substituir a sinalização bigquery-uri por links alternativos ao conjunto de dados de treinamento:

    • Para um arquivo CSV armazenado em um bucket do Cloud Storage, use --data-format=csv --gcs-uris=gs://BUCKET_NAME/OBJECT_NAME.

    • Para um arquivo TFRecord armazenado em um bucket do Cloud Storage, use --data-format=tf-record --gcs-uris=gs://BUCKET_NAME/OBJECT_NAME.

    • Para um conjunto de dados gerenciado do AutoML em tabela, use --dataset=DATASET_ID.

SDK do Python

Para informações sobre o fluxo de trabalho completo da API Modelo Monitoring, consulte o exemplo de notebook.

API REST

  1. Implante o modelo em um endpoint, se ainda não tiver feito isso. Durante a etapa Receber o ID do endpoint nas instruções de implantação do modelo, anote o valor deployedModels.id na resposta JSON para uso posterior:

  2. Criar uma solicitação de job de monitoramento de modelo. As instruções abaixo mostram como criar um job básico de monitoramento para detecção de deslocamento. Para personalizar a solicitação JSON, consulte a Referência de jobs do Monitoring.

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

    • PROJECT_ID é o ID do seu projeto do Google Cloud. Por exemplo, my-project.
    • LOCATION: é o local do job de monitoramento. Por exemplo, us-central1.
    • MONITORING_JOB_NAME: é o nome do job de monitoramento. Por exemplo, my-job.
    • PROJECT_NUMBER: é o número do projeto do Google Cloud. Por exemplo, 1234567890.
    • ENDPOINT_ID é o ID do endpoint em que o modelo é implantado. Por exemplo, 1234567890.
    • DEPLOYED_MODEL_ID: é o ID do modelo implantado.
    • FEATURE:VALUE e : é o limite de alerta para cada recurso que você quer monitorar. Por exemplo, se você especificar "Age": {"value": 0.4}, o monitoramento de modelos registrará um alerta quando a distância estatística entre as distribuições de entrada e referência para o recurso Age exceder 0,4. Por padrão, todos os atributos categóricos e numéricos são monitorados com valores limite de 0,3.
    • EMAIL_ADDRESS é o endereço de e-mail em que você quer receber alertas do monitoramento de modelos. Por exemplo, example@example.com.
    • NOTIFICATION_CHANNELS: uma lista de canais de notificação do Cloud Monitoring em que você quer receber alertas do monitoramento de modelos. Use os nomes dos recursos para os canais de notificação, que podem ser recuperados por meio da listagem dos canais de notificação em seu projeto. Por exemplo, "projects/my-project/notificationChannels/1355376463305411567", "projects/my-project/notificationChannels/1355376463305411568".
    • Opcional: ANALYSIS_INSTANCE_SCHEMA é o URI do Cloud Storage para o arquivo de esquema que descreve o formato dos dados de entrada. Por exemplo, gs://test-bucket/schema.yaml.

    Corpo JSON da solicitação:

    {
  "displayName":"MONITORING_JOB_NAME",
  "endpoint":"projects/PROJECT_NUMBER/locations/LOCATION/endpoints/ENDPOINT_ID",
  "modelDeploymentMonitoringObjectiveConfigs": {
     "deployedModelId": "DEPLOYED_MODEL_ID",
     "objectiveConfig":  {
        "predictionDriftDetectionConfig": {
            "driftThresholds": {
              "FEATURE_1": {
                "value": VALUE_1
               },
              "FEATURE_2": {
                "value": VALUE_2
               }
            }
         },
      },
  },
  "loggingSamplingStrategy": {
     "randomSampleConfig":  {
        "sampleRate":  0.5,
     },
  },
  "modelDeploymentMonitoringScheduleConfig": {
     "monitorInterval": {
        "seconds": 3600,
     },
  },
  "modelMonitoringAlertConfig": {
     "emailAlertConfig": {
        "userEmails": ["EMAIL_ADDRESS"],
     },
     "notificationChannels": [NOTIFICATION_CHANNELS]
  },
  "analysisInstanceSchemaUri": ANALYSIS_INSTANCE_SCHEMA
}

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

    Você receberá uma resposta JSON semelhante a esta:

    {
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/modelDeploymentMonitoringJobs/MONITORING_JOB_NUMBER",
  ...
  "state": "JOB_STATE_PENDING",
  "scheduleState": "OFFLINE",
  ...
  "bigqueryTables": [
    {
      "logSource": "SERVING",
      "logType": "PREDICT",
      "bigqueryTablePath": "bq://PROJECT_ID.model_deployment_monitoring_8451189418714202112.serving_predict"
    }
  ],
  ...
}

Depois que o job de monitoramento é criado, o monitoramento de modelos registra as solicitações de previsão recebidas em uma tabela gerada do BigQuery chamada PROJECT_ID.model_deployment_monitoring_ENDPOINT_ID.serving_predict. Se a geração de registros de solicitação/resposta estiver ativada, o monitoramento de modelos registrará as solicitações recebidas na mesma tabela do BigQuery usada para a geração de registros de solicitação/resposta.

(Opcional) Configurar alertas para o job de monitoramento de modelos

É possível monitorar e depurar o job de monitoramento de modelos por meio de alertas. O monitoramento de modelos notifica automaticamente sobre atualizações de jobs por e-mail, mas também é possível configurar alertas por meio dos canais de notificação do Cloud Logging e do Cloud Monitoring.

E-mail

Para os eventos a seguir, o monitoramento de modelos envia uma notificação por e-mail para cada endereço de e-mail especificado ao criar o job de monitoramento de modelos:

  • quando a detecção de distorção ou desvio é configurada;
  • sempre que uma configuração de job de monitoramento de modelos é atualizada.
  • Exibido sempre que a execução de um pipeline de monitoramento programado falha.

Cloud Logging

Para ativar os registros de execuções programadas do pipeline de monitoramento, defina o campo enableMonitoringPipelineLogs na configuração modelDeploymentMonitoringJobs como true. Os registros de depuração são gravados no Cloud Logging quando o job de monitoramento é configurado e em cada intervalo de monitoramento.

Os registros de depuração são gravados no Cloud Logging com o nome de registro: model_monitoring. Exemplo:

logName="projects/model-monitoring-demo/logs/aiplatform.googleapis.com%2Fmodel_monitoring" resource.labels.model_deployment_monitoring_job=6680511704087920640

Veja um exemplo de uma entrada de registro do progresso do job: 

{
"insertId": "e2032791-acb9-4d0f-ac73-89a38788ccf3@a1",
"jsonPayload": {
  "@type": "type.googleapis.com/google.cloud.aiplatform.logging.ModelMonitoringPipelineLogEntry",
  "statusCode": {
    "message": "Scheduled model monitoring pipeline finished successfully for job projects/677687165274/locations/us-central1/modelDeploymentMonitoringJobs/6680511704087920640"
  },
  "modelDeploymentMonitoringJob": "projects/677687165274/locations/us-central1/modelDeploymentMonitoringJobs/6680511704087920640"
},
"resource": {
  "type": "aiplatform.googleapis.com/ModelDeploymentMonitoringJob",
  "labels": {
    "model_deployment_monitoring_job": "6680511704087920640",
    "location": "us-central1",
    "resource_container": "projects/677687165274"
  }
},
"timestamp": "2022-02-04T15:33:54.778883Z",
"severity": "INFO",
"logName": "projects/model-monitoring-demo/logs/staging-aiplatform.sandbox.googleapis.com%2Fmodel_monitoring",
"receiveTimestamp": "2022-02-04T15:33:56.343298321Z"
}

Canais de notificação

Sempre que a execução de um pipeline de monitoramento programado falha, o monitoramento de modelos envia uma notificação aos canais de notificação do Cloud Monitoring que você especificou ao criar o job de monitoramento de modelos.

Configurar alertas para anomalias de recursos

O monitoramento de modelos detecta uma anomalia quando o limite definido para um atributo é excedido. O monitoramento de modelos notifica automaticamente sobre anomalias detectadas por e-mail, mas também é possível configurar alertas pelos canais de notificação do Cloud Logging e do Cloud Monitoring.

E-mail

Em cada intervalo de monitoramento, se o limite de pelo menos um atributo exceder o limite, o monitoramento de modelos enviará um alerta por e-mail para cada endereço de e-mail especificado ao criar o job de monitoramento. A mensagem de e-mail inclui o seguinte:

  • o horário em que o job de monitoramento foi executado.
  • o nome do atributo com distorção ou desvio.
  • O limite de alerta, bem como a medida de distância estatística registrada.

Cloud Logging

Para ativar os alertas do Cloud Logging, defina o campo enableLogging da configuração ModelMonitoringAlertConfig como true.

Em cada intervalo de monitoramento, um registro de anomalia será gravado no Cloud Logging se a distribuição de pelo menos um atributo exceder o limite dele. É possível encaminhar registros para qualquer serviço compatível com o Cloud Logging, como o Pub/Sub.

As anomalias são gravadas no Cloud Logging com o nome de registro: model_monitoring_anomaly. Exemplo:

logName="projects/model-monitoring-demo/logs/aiplatform.googleapis.com%2Fmodel_monitoring_anomaly" resource.labels.model_deployment_monitoring_job=6680511704087920640

Confira um exemplo de entrada de registro de anomalia: 

{
"insertId": "b0e9c0e9-0979-4aff-a5d3-4c0912469f9a@a1",
"jsonPayload": {
  "anomalyObjective": "RAW_FEATURE_SKEW",
  "endTime": "2022-02-03T19:00:00Z",
  "featureAnomalies": [
    {
      "featureDisplayName": "age",
      "deviation": 0.9,
      "threshold": 0.7
    },
    {
      "featureDisplayName": "education",
      "deviation": 0.6,
      "threshold": 0.3
    }
  ],
  "totalAnomaliesCount": 2,
  "@type": "type.googleapis.com/google.cloud.aiplatform.logging.ModelMonitoringAnomaliesLogEntry",
  "startTime": "2022-02-03T18:00:00Z",
  "modelDeploymentMonitoringJob": "projects/677687165274/locations/us-central1/modelDeploymentMonitoringJobs/6680511704087920640",
  "deployedModelId": "1645828169292316672"
},
"resource": {
  "type": "aiplatform.googleapis.com/ModelDeploymentMonitoringJob",
  "labels": {
    "model_deployment_monitoring_job": "6680511704087920640",
    "location": "us-central1",
    "resource_container": "projects/677687165274"
  }
},
"timestamp": "2022-02-03T19:00:00Z",
"severity": "WARNING",
"logName": "projects/model-monitoring-demo/logs/staging-aiplatform.sandbox.googleapis.com%2Fmodel_monitoring_anomaly",
"receiveTimestamp": "2022-02-03T19:59:52.121398388Z"
}

Canais de notificação

Em cada intervalo de monitoramento, se o limite de pelo menos um atributo exceder o limite, o monitoramento de modelos enviará um alerta para os canais de notificação do Cloud Monitoring que você especificou ao criar o job de monitoramento de modelos. O alerta inclui informações sobre o job de monitoramento de modelos que acionou o alerta.

Atualizar um job de monitoramento de modelos

É possível visualizar, atualizar, pausar e excluir um job de monitoramento de modelos. É preciso pausar um job antes de excluí-lo.

Console

Não é possível pausar e excluir no console do Google Cloud. use a gcloud CLI.

Para atualizar parâmetros de um job de monitoramento de modelos:

  1. No Console do Google Cloud, acesse a página Vertex AI Endpoints.

    Acessar o Endpoints

  2. Clique no nome do endpoint que você quer editar.

  3. Clique em Editar configurações.

  4. No painel Editar endpoint, selecione Monitoramento de modelo ou Objetivos do Monitoring.

  5. Atualize os campos que você quer mudar.

  6. Clique em Atualizar.

Para visualizar métricas, alertas e propriedades de monitoramento de um modelo:

  1. No Console do Google Cloud, acesse a página Vertex AI Endpoints.

    Acessar o Endpoints

  2. Clique no nome do endpoint.

  3. Na coluna Monitoramento do modelo que você quer visualizar, clique em Ativado.

gcloud

Execute este comando:

gcloud ai model-monitoring-jobs COMMAND MONITORING_JOB_ID \
  --PARAMETER=VALUE --project=PROJECT_ID --region=LOCATION

onde:

  • COMMAND é o comando que você quer executar no job de monitoramento. Por exemplo, update, pause, resume ou delete. Para mais informações, consulte a referência da CLI gcloud.

  • MONITORING_JOB_ID é o ID do job de monitoramento. Por exemplo, 123456789. Para encontrar o ID, [recupere as informações do endpoint][retrieve-id] ou confira as propriedades do Monitoring de um modelo no console do Google Cloud. O ID é incluído no nome do recurso do job de monitoramento no formato projects/PROJECT_NUMBER/locations/LOCATION/modelDeploymentMonitoringJobs/MONITORING_JOB_ID.

  • (opcional) PARAMETER=VALUE é o parâmetro que você quer atualizar. Essa sinalização é necessária somente ao usar o comando update. Por exemplo, monitoring-frequency=2. Para ver uma lista de parâmetros que podem ser atualizados, consulte a referência da CLI da gcloud.

  • PROJECT_ID é o ID do seu projeto do Google Cloud; Por exemplo, my-project.

  • LOCATION é o local do job de monitoramento. Por exemplo, us-central1.

API REST

Pausar um job

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

  • PROJECT_NUMBER: o nome do seu projeto do Google Cloud. Por exemplo, 1234567890.
  • LOCATION: local do job de monitoramento. Por exemplo, us-central1.
  • MONITORING_JOB_ID: ID do job de monitoramento. Por exemplo, 0987654321.

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

Você receberá uma resposta JSON semelhante a esta:

{}

Excluir um job

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

  • PROJECT_NUMBER: o nome do seu projeto do Google Cloud. Por exemplo, my-project.
  • LOCATION: local do job de monitoramento. Por exemplo, us-central1.
  • MONITORING_JOB_ID: ID do job de monitoramento. Por exemplo, 0987654321.

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/MONITORING_JOB_ID",
  ...
  "done": true,
  ...
}

Analisar dados de distorção e desvio

Use o console do Google Cloud para ver as distribuições de cada recurso monitorado e saber quais alterações causaram distorções ou desvios ao longo do tempo. É possível ver as distribuições de valores do recurso como um histograma.

Console

  1. Para navegar até os histogramas de distribuição de recursos no Console do Cloud, acesse a página Endpoints.

    Acessar o Endpoints

  2. Na página Endpoints, clique no endpoint que você quer analisar.

  3. Na página de detalhes do endpoint selecionado, há uma lista de todos os modelos implantados nesse endpoint. Clique no nome de um modelo a ser analisado.

  4. A página de detalhes do modelo lista os recursos de entrada do modelo, além das informações pertinentes, como o limite de alerta de cada recurso e o número de alertas anteriores do recurso.

  5. Para analisar um recurso, clique no nome dele. Uma página exibe os histogramas de distribuição de recursos desse recurso.

    Para cada recurso monitorado, é possível ver as distribuições dos 50 jobs de monitoramento mais recentes no Console do Cloud. Para a detecção de distorções, a distribuição dos dados de treinamento é exibida ao lado da distribuição dos dados de entrada:

    Histogramas mostrando um exemplo de distribuição de dados de entrada e distribuição de dados de treinamento para detecção de distorções.

    A visualização da distribuição de dados como histogramas permite que você se concentre rapidamente nas alterações que ocorreram nos dados. Depois, ajuste o pipeline de geração de recursos ou treine novamente o modelo.

A seguir