Avaliar e iterar modelos de classificação de texto do AutoML

A partir de 15 de setembro de 2024, só será possível personalizar a classificação, a extração de entidades, e os objetivos de análise de sentimento por meio da migração para os comandos e os ajustes do Vertex AI Gemini. O treinamento ou atualização de modelos do AutoML na Vertex AI para classificação de texto, extração de entidades e objetivos de análise de sentimento não estarão mais disponíveis. É possível continuar usando os modelos de AutoML Text na Vertex AI até 15 de junho de 2025. Para uma comparação entre o AutoML Text e o Gemini, consulte Gemini para usuários de texto do AutoML. Para mais informações sobre como o Gemini oferece uma experiência do usuário aprimorada com recursos aprimorados de comandos, consulte Introdução aos ajustes. Para começar a ajustar, consulte Ajuste de modelos de texto do Gemini

.

Nesta página, você aprenderá a avaliar modelos de classificação de texto do AutoML para a iteração no modelo.

A Vertex AI fornece métricas de avaliação de modelo para ajudar você a determinar o desempenho dos seus modelos, como métricas de precisão e recall. A Vertex AI calcula as métricas de avaliação usando o conjunto de teste.

Como usar métricas de avaliação do modelo

As métricas de avaliação do modelo são medidas que avaliam o desempenho do seu modelo no conjunto de teste. A forma como você interpreta e usa essas métricas depende das necessidades do seu negócio e do problema que seu modelo é treinado para solucionar. Por exemplo, você pode ter uma tolerância menor a falsos positivos do que para falsos negativos ou vice-versa. Esses tipos de perguntas afetam as métricas que podem ser relevantes para você.

Para mais informações sobre como iterar seu modelo para melhorar o desempenho, consulte Como iterar no modelo.

Métricas de avaliação retornadas pela Vertex AI

A Vertex AI retorna várias métricas de avaliação, como limites de precisão, recall e confiança. As métricas retornadas pela Vertex AI dependem do objetivo do seu modelo. Por exemplo, a Vertex AI fornece métricas de avaliação diferentes para um modelo de classificação de imagens em comparação com um modelo de detecção de objetos de imagem.

Um arquivo de esquema, disponível para download em um local do Cloud Storage, determina quais métricas de avaliação a Vertex AI fornece para cada objetivo. As guias a seguir fornecem links para os arquivos de esquema e descrevem as métricas de avaliação para cada objetivo do modelo.

É possível visualizar e fazer o download de arquivos de esquema no seguinte local do Cloud Storage:
gs://google-cloud-aiplatform/schema/modelevaluation/

• AuPRC: a área sob a curva de precisão/recall (PR, na sigla em inglês), também conhecida como precisão média. Ela varia de zero a um. Um valor maior indica um modelo de melhor qualidade.
• Log Perda: a entropia cruzada entre as predições do modelo e os valores do objetivo. Ela varia de zero a infinito. Um valor menor indica um modelo de melhor qualidade.
• Limite de confiança: uma pontuação de confiança que determina quais previsões serão retornadas. Um modelo retorna previsões que têm esse valor ou um valor maior. Um limite de confiança maior aumenta a precisão, mas diminui o recall. A Vertex AI retorna métricas de confiança em valores de limite diferentes para mostrar como o limite afeta a precisão e o recall.
• Recall: a fração de predições com esta classe que o modelo previu corretamente. Também chamado de taxa de verdadeiro positivo.
• Recall em 1: o recall (taxa de verdadeiro positivo) ao considerar apenas o rótulo que tem a maior pontuação de previsão e não abaixo do limite de confiança de cada exemplo.
• Precisão: a fração de predições de classificação produzidas pelo modelo que estavam corretas.
• Precisão em 1: a precisão ao considerar apenas o rótulo que tem a maior pontuação de previsão e não abaixo do limite de confiança de cada exemplo.
• Pontuação F1: a média harmônica de precisão e recall. F1 é uma métrica útil quando você está procurando um equilíbrio entre precisão e recall e a distribuição de classes é desigual.
• Pontuação F1 em 1: a média harmônica de recall em 1 e precisão em 1.
• Matriz de confusão: uma matriz de confusão mostra com que frequência um modelo previu corretamente um resultado. Para resultados previstos incorretamente, a matriz mostra o que o modelo previu. A matriz de confusão ajuda a entender onde o modelo "confunde" dois resultados.

Como receber métricas de avaliação

É possível receber um conjunto agregado de métricas de avaliação para o modelo e, para alguns objetivos, métricas de avaliação de uma classe ou rótulo específico. As métricas de avaliação de uma classe ou rótulo específico também são conhecidas como fração de avaliação. O conteúdo a seguir descreve como receber métricas de avaliação agregadas e frações de avaliação usando o Console ou a API do Google Cloud.

Console do Google Cloud

1. No console do Google Cloud, na seção da Vertex AI, acesse a página Registro de modelos.

   Acessar a página "Modelo de registro"

2. Na lista suspensa Região, selecione a região em que seu modelo está localizado.

3. Na lista de modelos, clique no seu modelo para abrir a guia Avaliar.

   Na guia Avaliar, é possível visualizar as métricas agregadas de avaliação do modelo, como Precisão média e Recall.

   Se o objetivo do modelo tiver frações de avaliação, o console mostrará uma lista de rótulos. Clique em um rótulo para visualizar as métricas de avaliação, conforme mostrado no exemplo a seguir:

   

API

As solicitações de API para receber métricas de avaliação são as mesmas para cada tipo de dado e objetivo, mas as saídas são diferentes. Os exemplos a seguir mostram a mesma solicitação, mas saídas diferentes.

Como receber métricas agregadas de avaliação de modelo

As métricas agregadas de avaliação de modelo fornecem informações sobre o modelo como um todo. Para ver informações sobre uma fração específica, liste as frações de avaliação do modelo.

Para visualizar as métricas agregadas de avaliação do modelo, use o método projects.locations.models.evaluations.get.

A Vertex AI retorna uma matriz de métricas de confiança. Cada elemento mostra métricas de avaliação em um valor confidenceThreshold diferente (começando em 0 e indo até 1). Ao visualizar diferentes valores de limite, é possível ver como o limite afeta outras métricas, como precisão e recall.

Selecione uma guia que corresponda ao seu idioma ou ambiente:

REST

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

• LOCATION: região onde seu modelo é armazenado.
• PROJECT: o ID do projeto.
• MODEL_ID: o ID do recurso do modelo.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.
• EVALUATION_ID: ID da avaliação do modelo (aparece na resposta).

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations

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

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "modelEvaluations": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID",
      "metricsSchemaUri": "gs://google-cloud-aiplatform/schema/modelevaluation/classification_metrics_1.0.0.yaml",
      "metrics": {
        "auPrc": 0.9569226,
        "logLoss": 0.08399241,
        "confidenceMetrics": [
          {
            "recall": 1,
            "precision": 0.14285715,
            "f1Score": 0.25,
            "recallAt1": 0.88270044,
            "precisionAt1": 0.88270044,
            "f1ScoreAt1": 0.88270044
          },
          {
            "confidenceThreshold": 0.05,
            "recall": 0.9772152,
            "precision": 0.6852071,
            "f1Score": 0.80556524,
            "recallAt1": 0.88270044,
            "precisionAt1": 0.88270044,
            "f1ScoreAt1": 0.88270044
          },
          {
            "confidenceThreshold": 0.1,
            "recall": 0.9662447,
            "precision": 0.75032765,
            "f1Score": 0.8447067,
            "recallAt1": 0.88270044,
            "precisionAt1": 0.88270044,
            "f1ScoreAt1": 0.88270044
          },
          ...
        ],
        "confusionMatrix": {
          "annotationSpecs": [
            {
              "id": "1349461407095062528",
              "displayName": "affection"
            },
            {
              "id": "2502382911701909504",
              "displayName": "nature"
            },
            {
              "id": "3655304416308756480",
              "displayName": "enjoy_the_moment"
            },
            {
              "id": "4808225920915603456",
              "displayName": "achievement"
            },
            {
              "id": "5961147425522450432",
              "displayName": "exercise"
            },
            {
              "id": "7114068930129297408",
              "displayName": "bonding"
            },
            {
              "id": "8266990434736144384",
              "displayName": "leisure"
            }
          ],
          "rows": [
            [
              404,
              0,
              6,
              12,
              0,
              1,
              0
            ],
            [
              1,
              20,
              0,
              4,
              0,
              1,
              0
            ],
            [
              5,
              0,
              104,
              23,
              2,
              1,
              5
            ],
            [
              18,
              1,
              14,
              334,
              2,
              2,
              6
            ],
            [
              0,
              0,
              0,
              1,
              19,
              0,
              0
            ],
            [
              8,
              0,
              0,
              5,
              0,
              117,
              0
            ],
            [
              2,
              0,
              10,
              8,
              0,
              1,
              48
            ]
          ]
        }
      },
      "createTime": "2020-08-29T03:05:14.099479Z",
      "sliceDimensions": [
        "annotationSpec"
      ]
    }
  ]
}

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.aiplatform.v1.ModelEvaluation;
import com.google.cloud.aiplatform.v1.ModelEvaluationName;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import java.io.IOException;

public class GetModelEvaluationTextClassificationSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // To obtain evaluationId run the code block below after setting modelServiceSettings.
    //
    // try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings))
    // {
    //   String location = "us-central1";
    //   ModelName modelFullId = ModelName.of(project, location, modelId);
    //   ListModelEvaluationsRequest modelEvaluationsrequest =
    //   ListModelEvaluationsRequest.newBuilder().setParent(modelFullId.toString()).build();
    //   for (ModelEvaluation modelEvaluation :
    //     modelServiceClient.listModelEvaluations(modelEvaluationsrequest).iterateAll()) {
    //       System.out.format("Model Evaluation Name: %s%n", modelEvaluation.getName());
    //   }
    // }
    String project = "YOUR_PROJECT_ID";
    String modelId = "YOUR_MODEL_ID";
    String evaluationId = "YOUR_EVALUATION_ID";

    getModelEvaluationTextClassificationSample(project, modelId, evaluationId);
  }

  static void getModelEvaluationTextClassificationSample(
      String project, String modelId, String evaluationId) throws IOException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";

      ModelEvaluationName modelEvaluationName =
          ModelEvaluationName.of(project, location, modelId, evaluationId);
      ModelEvaluation modelEvaluation = modelServiceClient.getModelEvaluation(modelEvaluationName);

      System.out.println("Get Model Evaluation Text Classification Response");
      System.out.format("\tModel Name: %s\n", modelEvaluation.getName());
      System.out.format("\tMetrics Schema Uri: %s\n", modelEvaluation.getMetricsSchemaUri());
      System.out.format("\tMetrics: %s\n", modelEvaluation.getMetrics());
      System.out.format("\tCreate Time: %s\n", modelEvaluation.getCreateTime());
      System.out.format("\tSlice Dimensions: %s\n", modelEvaluation.getSliceDimensionsList());
    }
  }
}

Node.js

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample
 * (not necessary if passing values as arguments). To obtain evaluationId,
 * instantiate the client and run the following the commands.
 */
// const parentName = `projects/${project}/locations/${location}/models/${modelId}`;
// const evalRequest = {
//   parent: parentName
// };
// const [evalResponse] = await modelServiceClient.listModelEvaluations(evalRequest);
// console.log(evalResponse);

// const modelId = 'YOUR_MODEL_ID';
// const evaluationId = 'YOUR_EVALUATION_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Model Service Client library
const {ModelServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function getModelEvaluationTextClassification() {
  // Configure the resources
  const name = `projects/${project}/locations/${location}/models/${modelId}/evaluations/${evaluationId}`;
  const request = {
    name,
  };

  // Get model evaluation request
  const [response] = await modelServiceClient.getModelEvaluation(request);

  console.log('Get model evaluation text classification response :');
  console.log(`\tName : ${response.name}`);
  console.log(`\tMetrics schema uri : ${response.metricsSchemaUri}`);
  console.log(`\tMetrics : ${JSON.stringify(response.metrics)}`);

  const modelExplanation = response.modelExplanation;
  console.log('\tModel explanation');
  if (modelExplanation === null) {
    console.log('\t\t{}');
  } else {
    const meanAttributions = modelExplanation.meanAttributions;
    if (meanAttributions === null) {
      console.log('\t\t\t []');
    } else {
      for (const meanAttribution of meanAttributions) {
        console.log('\t\tMean attribution');
        console.log(
          `\t\t\tBaseline output value : \
            ${meanAttribution.baselineOutputValue}`
        );
        console.log(
          `\t\t\tInstance output value : \
            ${meanAttribution.instanceOutputValue}`
        );
        console.log(
          `\t\t\tFeature attributions : \
            ${JSON.stringify(meanAttribution.featureAttributions)}`
        );
        console.log(`\t\t\tOutput index : ${meanAttribution.outputIndex}`);
        console.log(
          `\t\t\tOutput display name : \
            ${meanAttribution.outputDisplayName}`
        );
        console.log(
          `\t\t\tApproximation error : \
            ${meanAttribution.approximationError}`
        );
      }
    }
  }
}
getModelEvaluationTextClassification();

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

from google.cloud import aiplatform


def get_model_evaluation_text_classification_sample(
    project: str,
    model_id: str,
    evaluation_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    """
    To obtain evaluation_id run the following commands where LOCATION
    is the region where the model is stored, PROJECT is the project ID,
    and MODEL_ID is the ID of your model.

    model_client = aiplatform.gapic.ModelServiceClient(
        client_options={
            'api_endpoint':'LOCATION-aiplatform.googleapis.com'
            }
        )
    evaluations = model_client.list_model_evaluations(parent='projects/PROJECT/locations/LOCATION/models/MODEL_ID')
    print("evaluations:", evaluations)
    """
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.ModelServiceClient(client_options=client_options)
    name = client.model_evaluation_path(
        project=project, location=location, model=model_id, evaluation=evaluation_id
    )
    response = client.get_model_evaluation(name=name)
    print("response:", response)

Como listar todas as frações de avaliação

O método projects.locations.models.evaluations.slices.list lista todas as frações de avaliação do modelo. É necessário ter o ID de avaliação do modelo, que é possível conseguir ao visualizar as métricas agregadas de avaliação.

É possível usar frações de avaliação de modelo para determinar como foi o desempenho do modelo em um rótulo específico. O campo value informa para quais rótulos as métricas são usadas.

A Vertex AI retorna uma matriz de métricas de confiança. Cada elemento mostra métricas de avaliação em um valor confidenceThreshold diferente (começando em 0 e indo até 1). Ao visualizar diferentes valores de limite, é possível ver como o limite afeta outras métricas, como precisão e recall.

REST

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

• LOCATION: região onde o modelo está localizado. Por exemplo, us-central1.
• PROJECT: o ID do projeto.
• MODEL_ID: o ID do modelo.
• EVALUATION_ID: ID da avaliação do modelo que contém as frações de avaliação a serem listadas.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices

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

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "modelEvaluationSlices": [
    {
      "name": "projects/693884908213/locations/us-central1/models/4597084504010522624/evaluations/5327525262714208256/slices/28418181714804292",
      "slice": {
        "dimension": "annotationSpec",
        "value": "leisure"
      },
      "metricsSchemaUri": "gs://google-cloud-aiplatform/schema/modelevaluation/classification_metrics_1.0.0.yaml",
      "metrics": {
        "auPrc": 0.8596267,
        "logLoss": 0.07142017,
        "confidenceMetrics": [
          {
            "recall": 1,
            "precision": 0.05822785,
            "f1Score": 0.11004785
          },
          {
            "confidenceThreshold": 0.05,
            "recall": 0.95652175,
            "precision": 0.3882353,
            "f1Score": 0.5523013
          },
          {
            "confidenceThreshold": 0.1,
            "recall": 0.89855075,
            "precision": 0.53913045,
            "f1Score": 0.67391306
          },
          ...
        ]
      },
      "createTime": "2020-10-29T01:17:39.368890Z"
    },
    {
      "name": "projects/693884908213/locations/us-central1/models/4597084504010522624/evaluations/5327525262714208256/slices/177673261689801402",
      "slice": {
        "dimension": "annotationSpec",
        "value": "achievement"
      },
      "metricsSchemaUri": "gs://google-cloud-aiplatform/schema/modelevaluation/classification_metrics_1.0.0.yaml",
      "metrics": {
        "auPrc": 0.95337653,
        "logLoss": 0.17853451,
        "confidenceMetrics": [
          {
            "recall": 1,
            "precision": 0.31814346,
            "f1Score": 0.48271447
          },
          {
            "confidenceThreshold": 0.05,
            "recall": 0.9920424,
            "precision": 0.70433146,
            "f1Score": 0.8237885
          },
          ...

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.aiplatform.v1.ModelEvaluationName;
import com.google.cloud.aiplatform.v1.ModelEvaluationSlice;
import com.google.cloud.aiplatform.v1.ModelEvaluationSlice.Slice;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import java.io.IOException;

public class ListModelEvaluationSliceSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // To obtain evaluationId run the code block below after setting modelServiceSettings.
    //
    // try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings))
    // {
    //   String location = "us-central1";
    //   ModelName modelFullId = ModelName.of(project, location, modelId);
    //   ListModelEvaluationsRequest modelEvaluationsrequest =
    //   ListModelEvaluationsRequest.newBuilder().setParent(modelFullId.toString()).build();
    //   for (ModelEvaluation modelEvaluation :
    //     modelServiceClient.listModelEvaluations(modelEvaluationsrequest).iterateAll()) {
    //       System.out.format("Model Evaluation Name: %s%n", modelEvaluation.getName());
    //   }
    // }
    String project = "YOUR_PROJECT_ID";
    String modelId = "YOUR_MODEL_ID";
    String evaluationId = "YOUR_EVALUATION_ID";
    listModelEvaluationSliceSample(project, modelId, evaluationId);
  }

  static void listModelEvaluationSliceSample(String project, String modelId, String evaluationId)
      throws IOException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      ModelEvaluationName modelEvaluationName =
          ModelEvaluationName.of(project, location, modelId, evaluationId);

      for (ModelEvaluationSlice modelEvaluationSlice :
          modelServiceClient.listModelEvaluationSlices(modelEvaluationName).iterateAll()) {
        System.out.format("Model Evaluation Slice Name: %s\n", modelEvaluationSlice.getName());
        System.out.format("Metrics Schema Uri: %s\n", modelEvaluationSlice.getMetricsSchemaUri());
        System.out.format("Metrics: %s\n", modelEvaluationSlice.getMetrics());
        System.out.format("Create Time: %s\n", modelEvaluationSlice.getCreateTime());

        Slice slice = modelEvaluationSlice.getSlice();
        System.out.format("Slice Dimensions: %s\n", slice.getDimension());
        System.out.format("Slice Value: %s\n\n", slice.getValue());
      }
    }
  }
}

Node.js

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample
 * (not necessary if passing values as arguments). To obtain evaluationId,
 * instantiate the client and run the following the commands.
 */
// const parentName = `projects/${project}/locations/${location}/models/${modelId}`;
// const evalRequest = {
//   parent: parentName
// };
// const [evalResponse] = await modelServiceClient.listModelEvaluations(evalRequest);
// console.log(evalResponse);

// const modelId = 'YOUR_MODEL_ID';
// const evaluationId = 'YOUR_EVALUATION_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Model Service Client library
const {ModelServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function listModelEvaluationSlices() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}/models/${modelId}/evaluations/${evaluationId}`;
  const request = {
    parent,
  };

  // Get and print out a list of all the evaluation slices for this resource
  const [response] =
    await modelServiceClient.listModelEvaluationSlices(request);
  console.log('List model evaluation response', response);
  console.log(response);
}
listModelEvaluationSlices();

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

from google.cloud import aiplatform


def list_model_evaluation_slices_sample(
    project: str,
    model_id: str,
    evaluation_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    """
    To obtain evaluation_id run the following commands where LOCATION
    is the region where the model is stored, PROJECT is the project ID,
    and MODEL_ID is the ID of your model.

    model_client = aiplatform.gapic.ModelServiceClient(
        client_options={
            'api_endpoint':'LOCATION-aiplatform.googleapis.com'
            }
        )
    evaluations = model_client.list_model_evaluations(parent='projects/PROJECT/locations/LOCATION/models/MODEL_ID')
    print("evaluations:", evaluations)
    """
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.ModelServiceClient(client_options=client_options)
    parent = client.model_evaluation_path(
        project=project, location=location, model=model_id, evaluation=evaluation_id
    )
    response = client.list_model_evaluation_slices(parent=parent)
    for model_evaluation_slice in response:
        print("model_evaluation_slice:", model_evaluation_slice)

Como receber métricas para uma única fração

Para visualizar as métricas de avaliação de uma única fração, use o método projects.locations.models.evaluations.slices.get. É necessário ter o ID da fração, que é fornecido quando você lista todas as frações. A amostra a seguir se aplica a todos os tipos de dados e objetivos.

REST

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

• LOCATION: região onde o modelo está localizado. Por exemplo: us-central1.
• PROJECT: o ID do projeto.
• MODEL_ID: o ID do modelo.
• EVALUATION_ID: ID da avaliação do modelo que contém a fração de avaliação a ser recuperada.
• SLICE_ID: ID de uma fração de avaliação a ser recebida.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.
• EVALUATION_METRIC_SCHEMA_FILE_NAME: o nome de um arquivo de esquema que define as métricas de avaliação a serem retornadas, como classification_metrics_1.0.0.

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices/SLICE_ID

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

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices/SLICE_ID"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices/SLICE_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/evaluations/EVALUATION_ID/slices/SLICE_ID",
  "slice": {
    "dimension": "annotationSpec",
    "value": "a particular class or label"
  },
  "metricsSchemaUri": "gs://google-cloud-aiplatform/schema/modelevaluation/EVALUATION_METRIC_SCHEMA_FILE_NAME.yaml",
  "metrics": {
    evaluation metrics for the slice
  },
  "createTime": "2020-10-08T23:35:54.770876Z"
}

Java

Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.aiplatform.v1.ModelEvaluationSlice;
import com.google.cloud.aiplatform.v1.ModelEvaluationSlice.Slice;
import com.google.cloud.aiplatform.v1.ModelEvaluationSliceName;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import java.io.IOException;

public class GetModelEvaluationSliceSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // To obtain evaluationId run the code block below after setting modelServiceSettings.
    //
    // try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings))
    // {
    //   String location = "us-central1";
    //   ModelName modelFullId = ModelName.of(project, location, modelId);
    //   ListModelEvaluationsRequest modelEvaluationsrequest =
    //   ListModelEvaluationsRequest.newBuilder().setParent(modelFullId.toString()).build();
    //   for (ModelEvaluation modelEvaluation :
    //     modelServiceClient.listModelEvaluations(modelEvaluationsrequest).iterateAll()) {
    //       System.out.format("Model Evaluation Name: %s%n", modelEvaluation.getName());
    //   }
    // }
    String project = "YOUR_PROJECT_ID";
    String modelId = "YOUR_MODEL_ID";
    String evaluationId = "YOUR_EVALUATION_ID";
    String sliceId = "YOUR_SLICE_ID";
    getModelEvaluationSliceSample(project, modelId, evaluationId, sliceId);
  }

  static void getModelEvaluationSliceSample(
      String project, String modelId, String evaluationId, String sliceId) throws IOException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      ModelEvaluationSliceName modelEvaluationSliceName =
          ModelEvaluationSliceName.of(project, location, modelId, evaluationId, sliceId);

      ModelEvaluationSlice modelEvaluationSlice =
          modelServiceClient.getModelEvaluationSlice(modelEvaluationSliceName);

      System.out.println("Get Model Evaluation Slice Response");
      System.out.format("Model Evaluation Slice Name: %s\n", modelEvaluationSlice.getName());
      System.out.format("Metrics Schema Uri: %s\n", modelEvaluationSlice.getMetricsSchemaUri());
      System.out.format("Metrics: %s\n", modelEvaluationSlice.getMetrics());
      System.out.format("Create Time: %s\n", modelEvaluationSlice.getCreateTime());

      Slice slice = modelEvaluationSlice.getSlice();
      System.out.format("Slice Dimensions: %s\n", slice.getDimension());
      System.out.format("Slice Value: %s\n", slice.getValue());
    }
  }
}

Node.js

Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

/**
 * TODO(developer): Uncomment these variables before running the sample
 * (not necessary if passing values as arguments). To obtain evaluationId,
 * instantiate the client and run the following the commands.
 */
// const parentName = `projects/${project}/locations/${location}/models/${modelId}`;
// const evalRequest = {
//   parent: parentName
// };
// const [evalResponse] = await modelServiceClient.listModelEvaluations(evalRequest);
// console.log(evalResponse);

// const modelId = 'YOUR_MODEL_ID';
// const evaluationId = 'YOUR_EVALUATION_ID';
// const sliceId = 'YOUR_SLICE_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

// Imports the Google Cloud Model Service client library
const {ModelServiceClient} = require('@google-cloud/aiplatform');
// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};
// Specifies the location of the api endpoint
const modelServiceClient = new ModelServiceClient(clientOptions);

async function getModelEvaluationSlice() {
  // Configure the parent resource
  const name = `projects/${project}/locations/${location}/models/${modelId}/evaluations/${evaluationId}/slices/${sliceId}`;
  const request = {
    name,
  };

  // Get and print out a list of all the endpoints for this resource
  const [response] =
    await modelServiceClient.getModelEvaluationSlice(request);

  console.log('Get model evaluation slice');
  console.log(`\tName : ${response.name}`);
  console.log(`\tMetrics_Schema_Uri : ${response.metricsSchemaUri}`);
  console.log(`\tMetrics : ${JSON.stringify(response.metrics)}`);
  console.log(`\tCreate time : ${JSON.stringify(response.createTime)}`);

  console.log('Slice');
  const slice = response.slice;
  console.log(`\tDimension :${slice.dimension}`);
  console.log(`\tValue :${slice.value}`);
}
getModelEvaluationSlice();

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

from google.cloud import aiplatform


def get_model_evaluation_slice_sample(
    project: str,
    model_id: str,
    evaluation_id: str,
    slice_id: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
):
    """
    To obtain evaluation_id run the following commands where LOCATION
    is the region where the model is stored, PROJECT is the project ID,
    and MODEL_ID is the ID of your model.

    model_client = aiplatform.gapic.ModelServiceClient(
        client_options={
            'api_endpoint':'LOCATION-aiplatform.googleapis.com'
            }
        )
    evaluations = model_client.list_model_evaluations(parent='projects/PROJECT/locations/LOCATION/models/MODEL_ID')
    print("evaluations:", evaluations)
    """
    # The AI Platform services require regional API endpoints.
    client_options = {"api_endpoint": api_endpoint}
    # Initialize client that will be used to create and send requests.
    # This client only needs to be created once, and can be reused for multiple requests.
    client = aiplatform.gapic.ModelServiceClient(client_options=client_options)
    name = client.model_evaluation_slice_path(
        project=project,
        location=location,
        model=model_id,
        evaluation=evaluation_id,
        slice=slice_id,
    )
    response = client.get_model_evaluation_slice(name=name)
    print("response:", response)

Iterar o modelo

As métricas de avaliação do modelo são um ponto de partida para depurar o modelo quando ele não atende às suas expectativas. Por exemplo, pontuações baixas de precisão e recall podem indicar que o modelo precisa de dados de treinamento extras ou tem rótulos inconsistentes. A precisão e o recall perfeitos podem indicar que os dados de teste são muito fáceis de prever e podem não generalizar bem.

É possível iterar os dados de treinamento e criar um novo modelo. Depois de criar um novo modelo, é possível comparar as métricas de avaliação entre o modelo atual e o novo.

As sugestões a seguir podem ajudar a melhorar modelos que rotulam itens, como modelos de classificação ou de detecção:

• Adicione mais exemplos ou uma variedade maior de exemplos nos dados de treinamento.
• Considere remover classes ou rótulos que não tenham muitos exemplos. Exemplos insuficientes impedem que o modelo faça previsões consistentes e confiáveis sobre essas classes ou rótulos.
• Amplie seus dados com mais exemplos de verdadeiros positivos e verdadeiros negativos, especialmente exemplos próximos de uma fronteira de decisão para reduzir a confusão de modelos.
• Especifique sua própria divisão de dados (treinamento, validação e teste). A Vertex AI atribui itens aleatoriamente para cada conjunto. Portanto, quase duplicadas podem ser alocadas nos conjuntos de treinamento e validação, o que pode levar a um overfitting e desempenho insatisfatório no conjunto de teste. Para mais informações sobre como configurar sua própria divisão de dados, consulte Sobre divisões de dados para modelos do AutoML.
• Se as métricas de avaliação do modelo incluírem uma matriz de confusão, será possível ver se o modelo está confundindo dois rótulos, onde o modelo está prevendo um rótulo específico bem mais do que o rótulo verdadeiro. Revise os dados e verifique se os exemplos estão rotulados corretamente.
• Se você teve pouco tempo de treinamento (baixo número máximo de horas de uso do nó), poderá receber um modelo de maior qualidade, permitindo que ele seja treinado por um período maior (maior número máximo de horas de uso do nó).