Receber previsões e explicações on-line

Nesta página, mostramos como receber previsões on-line (em tempo real) de modelos tabulares de classificação ou regressão usando o Console do Google Cloud ou a API Vertex AI.

Uma predição on-line é uma solicitação síncrona, em vez de uma previsão em lote, que é uma solicitação assíncrona. Use predições on-line ao fazer solicitações em resposta à entrada do aplicativo ou em outras situações em que você precisa de inferência em tempo hábil.

Implante um modelo em um endpoint antes de ele ser usado para exibir previsões on-line. A implantação de um modelo associa recursos físicos ao modelo para que ele possa exibir previsões on-line com baixa latência.

Os temas abordados são os seguintes:

  1. Implantar um modelo em um endpoint
  2. Fazer uma previsão on-line usando o modelo implantado
  3. Receba uma explicação on-line usando seu modelo implantado

Antes de começar

Antes de receber previsões on-line, é necessário treinar um modelo de classificação ou regressão e avaliá-lo para maior precisão.

Implantar um modelo em um endpoint

É possível implantar mais de um modelo em um endpoint, além de ser possível implantar um modelo em mais de um endpoint. Para mais informações sobre opções e casos de uso de implantação de modelos, consulte Sobre a implantação de modelos.

Use um dos seguintes métodos para implantar um modelo:

Console do Google Cloud

  1. No Console do Google Cloud, na seção "Vertex AI", acesse a página Modelos.

    Acessar a página de modelos

  2. Clique no nome do modelo que você quer implantar para abrir a página de detalhes.

  3. Selecione a guia Implantar e testar.

    Caso seu modelo já esteja implantado em um endpoint, o endpoint estará listado na seção Implantar seu modelo.

  4. Clique em Implantar no endpoint.

  5. Na página Definir seu endpoint, configure o seguinte:

    1. É possível implantar o modelo em um endpoint novo ou atual.

      • Para implantar o modelo em um novo endpoint, selecione Criar novo endpoint e dê um nome a ele.
      • Para implantar o modelo em um endpoint atual, selecione Adicionar a um endpoint atual e escolha o endpoint na lista suspensa.
      • É possível adicionar mais de um modelo a um endpoint, além de ser possível adicionar um modelo a mais de um endpoint. Saiba mais.

    2. Clique em Continuar.

  6. Na página Detalhes do modelo, configure o seguinte:

    1. Se você estiver implantando seu modelo em um novo endpoint, aceite 100 para a divisão de tráfego. Se você implantar o modelo em um endpoint atual que tem um ou mais modelos implantados, é necessário atualizar a porcentagem de divisão de tráfego do modelo que você está implantando, bem como a dos modelos já implantados para que todas as porcentagens totalizem 100%.

    2. Insira o número mínimo de nós de computação que você quer fornecer ao modelo.

      Esse é o número de nós disponíveis para este modelo em todos os momentos. Você é cobrado pelos nós usados, seja para processar a carga de previsão ou por nós de espera (mínimo), mesmo sem tráfego de previsão. Consulte a página de preços.

    3. Selecione o Tipo de máquina.

      Recursos maiores de máquina aumentarão o desempenho da previsão e os custos.

    4. Saiba como alterar as configurações padrão para a geração de registros de previsão.

    5. Clique em Continuar.

  7. Na página Monitoramento de modelo, clique em Continuar.

  8. Na página Objetivos do Monitoring, configure o seguinte:

    1. Insira o local dos dados de treinamento.
    2. Digite o nome do serviço de destino.

  9. Clique em Implantar para implantar o modelo no endpoint.

API

Ao implantar um modelo usando a API Vertex AI, siga estas etapas:

  1. Crie um endpoint, se necessário.
  2. Receba o ID do endpoint.
  3. Implantar o modelo no endpoint.

Criar um endpoint

Pule a etapa abaixo se você estiver implantando um modelo em um endpoint existente.

gcloud

O exemplo a seguir usa o comando gcloud ai endpoints create:

  gcloud ai endpoints create \
    --region=LOCATION \
    --display-name=ENDPOINT_NAME

Substitua:

  • LOCATION_ID: a região em que você está usando a Vertex AI.

  • ENDPOINT_NAME: o nome de exibição do endpoint.

    A ferramenta CLI do Google Cloud pode levar alguns segundos para criar o endpoint.

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.
  • ENDPOINT_NAME: o nome de exibição do endpoint.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints

Corpo JSON da solicitação:

{
  "display_name": "ENDPOINT_NAME"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-11-05T17:45:42.812656Z",
      "updateTime": "2020-11-05T17:45:42.812656Z"
    }
  }
}
Faça a sondagem do status da operação até que a resposta inclua "done": true.

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.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.CreateEndpointOperationMetadata;
import com.google.cloud.aiplatform.v1.Endpoint;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.LocationName;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateEndpointSample {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String endpointDisplayName = "YOUR_ENDPOINT_DISPLAY_NAME";
    createEndpointSample(project, endpointDisplayName);
  }

  static void createEndpointSample(String project, String endpointDisplayName)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    EndpointServiceSettings endpointServiceSettings =
        EndpointServiceSettings.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 (EndpointServiceClient endpointServiceClient =
        EndpointServiceClient.create(endpointServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);
      Endpoint endpoint = Endpoint.newBuilder().setDisplayName(endpointDisplayName).build();

      OperationFuture<Endpoint, CreateEndpointOperationMetadata> endpointFuture =
          endpointServiceClient.createEndpointAsync(locationName, endpoint);
      System.out.format("Operation name: %s\n", endpointFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      Endpoint endpointResponse = endpointFuture.get(300, TimeUnit.SECONDS);

      System.out.println("Create Endpoint Response");
      System.out.format("Name: %s\n", endpointResponse.getName());
      System.out.format("Display Name: %s\n", endpointResponse.getDisplayName());
      System.out.format("Description: %s\n", endpointResponse.getDescription());
      System.out.format("Labels: %s\n", endpointResponse.getLabelsMap());
      System.out.format("Create Time: %s\n", endpointResponse.getCreateTime());
      System.out.format("Update Time: %s\n", endpointResponse.getUpdateTime());
    }
  }
}

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)
 */

// const endpointDisplayName = 'YOUR_ENDPOINT_DISPLAY_NAME';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

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

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

// Instantiates a client
const endpointServiceClient = new EndpointServiceClient(clientOptions);

async function createEndpoint() {
  // Configure the parent resource
  const parent = `projects/${project}/locations/${location}`;
  const endpoint = {
    displayName: endpointDisplayName,
  };
  const request = {
    parent,
    endpoint,
  };

  // Get and print out a list of all the endpoints for this resource
  const [response] = await endpointServiceClient.createEndpoint(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  const result = response.result;

  console.log('Create endpoint response');
  console.log(`\tName : ${result.name}`);
  console.log(`\tDisplay name : ${result.displayName}`);
  console.log(`\tDescription : ${result.description}`);
  console.log(`\tLabels : ${JSON.stringify(result.labels)}`);
  console.log(`\tCreate time : ${JSON.stringify(result.createTime)}`);
  console.log(`\tUpdate time : ${JSON.stringify(result.updateTime)}`);
}
createEndpoint();

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. 

def create_endpoint_sample(
    project: str,
    display_name: str,
    location: str,
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint.create(
        display_name=display_name,
        project=project,
        location=location,
    )

    print(endpoint.display_name)
    print(endpoint.resource_name)
    return endpoint

Receber o ID do endpoint

Você precisa do ID do endpoint para implantar o modelo.

gcloud

O exemplo a seguir usa o comando gcloud ai endpoints list:

  gcloud ai endpoints list \
    --region=LOCATION \
    --filter=display_name=ENDPOINT_NAME

Substitua:

  • LOCATION_ID: a região em que você está usando a Vertex AI.

  • ENDPOINT_NAME: o nome de exibição do endpoint.

    Anote o número que aparece na coluna ENDPOINT_ID. Use esse ID na etapa a seguir.

REST

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

  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • PROJECT_ID: o ID do projeto.
  • ENDPOINT_NAME: o nome de exibição do endpoint.

Método HTTP e URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME

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

Você receberá uma resposta JSON semelhante a esta:

{
  "endpoints": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID",
      "displayName": "ENDPOINT_NAME",
      "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx",
      "createTime": "2020-04-17T18:31:11.585169Z",
      "updateTime": "2020-04-17T18:35:08.568959Z"
    }
  ]
}
Confira o ENDPOINT_ID.

Implantar o modelo

Selecione a guia abaixo para seu idioma ou ambiente:

gcloud

Os exemplos a seguir usam o comando gcloud ai endpoints deploy-model.

O exemplo a seguir implanta um Model em um Endpoint sem usar GPUs para acelerar a exibição da previsão e sem dividir o tráfego entre vários recursos DeployedModel:

Antes de usar os dados do comando abaixo, faça estas substituições:

  • ENDPOINT_ID: o ID do endpoint.
  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • MODEL_ID: o ID do modelo a ser implantado.
  • DEPLOYED_MODEL_NAME: um nome para DeployedModel. Também é possível usar o nome de exibição do Model para o DeployedModel.
  • MACHINE_TYPE: opcional. Os recursos de máquina usados para cada nó desta implantação. A configuração padrão é n1-standard-2. Saiba mais sobre tipos de máquinas.
  • MIN_REPLICA_COUNT: o número mínimo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de previsão, até o número máximo de nós e nunca menos que esse número. O valor precisa ser maior ou igual a 1. Se a sinalização --min-replica-count for omitida, o valor padrão será 1.
  • MAX_REPLICA_COUNT: o número máximo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de previsão, até esse número de nós e nunca menos que o número mínimo de nós. Se você omitir a sinalização --max-replica-count, o número máximo de nós será definido como o valor de --min-replica-count.

Execute o comando gcloud ai endpoints deploy-model:

Linux, macOS ou Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=100

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME `
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=100

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME ^
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=100
  

Divisão de tráfego

A sinalização --traffic-split=0=100 nos exemplos anteriores envia 100% do tráfego de previsão que Endpoint recebe para o novo DeployedModel, que é representado pelo ID temporário 0. Se a Endpoint já tiver outros recursos DeployedModel, será possível dividir o tráfego entre o novo DeployedModel e os antigos. Por exemplo, para enviar 20% do tráfego para o novo DeployedModel e 80% para um mais antigo, execute o seguinte comando.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • OLD_DEPLOYED_MODEL_ID: o ID do DeployedModel existente.

Execute o comando gcloud ai endpoints deploy-model:

Linux, macOS ou Cloud Shell

gcloud ai endpoints deploy-model ENDPOINT_ID\
  --region=LOCATION_ID \
  --model=MODEL_ID \
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE \
  --min-replica-count=MIN_REPLICA_COUNT \
  --max-replica-count=MAX_REPLICA_COUNT \
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows (PowerShell)

gcloud ai endpoints deploy-model ENDPOINT_ID`
  --region=LOCATION_ID `
  --model=MODEL_ID `
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE `
  --min-replica-count=MIN_REPLICA_COUNT `
  --max-replica-count=MAX_REPLICA_COUNT `
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80

Windows (cmd.exe)

gcloud ai endpoints deploy-model ENDPOINT_ID^
  --region=LOCATION_ID ^
  --model=MODEL_ID ^
  --display-name=DEPLOYED_MODEL_NAME \ 
  --machine-type=MACHINE_TYPE ^
  --min-replica-count=MIN_REPLICA_COUNT ^
  --max-replica-count=MAX_REPLICA_COUNT ^
  --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
  

REST

Use o método endpoints.predict para solicitar uma predição on-line.

Implantar o modelo.

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

  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • PROJECT_ID: o ID do projeto.
  • ENDPOINT_ID: o ID do endpoint.
  • MODEL_ID: o ID do modelo a ser implantado.
  • DEPLOYED_MODEL_NAME: um nome para DeployedModel. Também é possível usar o nome de exibição do Model para o DeployedModel.
  • MACHINE_TYPE: opcional. Os recursos de máquina usados para cada nó desta implantação. A configuração padrão é n1-standard-2. Saiba mais sobre tipos de máquinas.
  • ACCELERATOR_TYPE: o tipo de acelerador a ser anexado à máquina. Opcional se ACCELERATOR_COUNT não for especificado ou for zero. Não recomendado para modelos AutoML ou modelos treinados personalizados que usem imagens que não sejam de GPU. Saiba mais.
  • ACCELERATOR_COUNT: o número de aceleradores a serem usados por cada réplica. Opcional. Deve ser zero ou não especificado para modelos do AutoML ou modelos treinados personalizados que usam imagens que não sejam de GPU.
  • MIN_REPLICA_COUNT: o número mínimo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de previsão, até o número máximo de nós e nunca menos que esse número. O valor precisa ser maior ou igual a 1.
  • MAX_REPLICA_COUNT: o número máximo de nós para esta implantação. A contagem de nós pode ser aumentada ou reduzida conforme necessário pela carga de previsão, até esse número de nós e nunca menos que o número mínimo de nós.
  • TRAFFIC_SPLIT_THIS_MODEL: a porcentagem do tráfego de previsão para esse endpoint que será roteada para o modelo que está sendo implantado com esta operação. O padrão é 100. A soma de todas as porcentagens de tráfego precisam totalizar 100. Saiba mais sobre as divisões de tráfego.
  • DEPLOYED_MODEL_ID_N: opcional. Se outros modelos forem implantados nesse endpoint, será necessário atualizar as porcentagens de divisão de tráfego para que todas as porcentagens somem 100.
  • TRAFFIC_SPLIT_MODEL_N: o valor da porcentagem da divisão de tráfego para a chave de ID do modelo implantado.
  • PROJECT_NUMBER: o número do projeto gerado automaticamente

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:deployModel

Corpo JSON da solicitação:

{
  "deployedModel": {
    "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID",
    "displayName": "DEPLOYED_MODEL_NAME",
    "dedicatedResources": {
       "machineSpec": {
         "machineType": "MACHINE_TYPE",
         "acceleratorType": "ACCELERATOR_TYPE",
         "acceleratorCount": "ACCELERATOR_COUNT"
       },
       "minReplicaCount": MIN_REPLICA_COUNT,
       "maxReplicaCount": MAX_REPLICA_COUNT
     },
  },
  "trafficSplit": {
    "0": TRAFFIC_SPLIT_THIS_MODEL,
    "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1,
    "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2
  },
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-10-19T17:53:16.502088Z",
      "updateTime": "2020-10-19T17:53:16.502088Z"
    }
  }
}

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.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.DedicatedResources;
import com.google.cloud.aiplatform.v1.DeployModelOperationMetadata;
import com.google.cloud.aiplatform.v1.DeployModelResponse;
import com.google.cloud.aiplatform.v1.DeployedModel;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.EndpointServiceClient;
import com.google.cloud.aiplatform.v1.EndpointServiceSettings;
import com.google.cloud.aiplatform.v1.MachineSpec;
import com.google.cloud.aiplatform.v1.ModelName;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ExecutionException;

public class DeployModelCustomTrainedModelSample {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "PROJECT";
    String endpointId = "ENDPOINT_ID";
    String modelName = "MODEL_NAME";
    String deployedModelDisplayName = "DEPLOYED_MODEL_DISPLAY_NAME";
    deployModelCustomTrainedModelSample(project, endpointId, modelName, deployedModelDisplayName);
  }

  static void deployModelCustomTrainedModelSample(
      String project, String endpointId, String model, String deployedModelDisplayName)
      throws IOException, ExecutionException, InterruptedException {
    EndpointServiceSettings settings =
        EndpointServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();
    String location = "us-central1";

    // 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 (EndpointServiceClient client = EndpointServiceClient.create(settings)) {
      MachineSpec machineSpec = MachineSpec.newBuilder().setMachineType("n1-standard-2").build();
      DedicatedResources dedicatedResources =
          DedicatedResources.newBuilder().setMinReplicaCount(1).setMachineSpec(machineSpec).build();

      String modelName = ModelName.of(project, location, model).toString();
      DeployedModel deployedModel =
          DeployedModel.newBuilder()
              .setModel(modelName)
              .setDisplayName(deployedModelDisplayName)
              // `dedicated_resources` must be used for non-AutoML models
              .setDedicatedResources(dedicatedResources)
              .build();
      // key '0' assigns traffic for the newly deployed model
      // Traffic percentage values must add up to 100
      // Leave dictionary empty if endpoint should not accept any traffic
      Map<String, Integer> trafficSplit = new HashMap<>();
      trafficSplit.put("0", 100);
      EndpointName endpoint = EndpointName.of(project, location, endpointId);
      OperationFuture<DeployModelResponse, DeployModelOperationMetadata> response =
          client.deployModelAsync(endpoint, deployedModel, trafficSplit);

      // You can use OperationFuture.getInitialFuture to get a future representing the initial
      // response to the request, which contains information while the operation is in progress.
      System.out.format("Operation name: %s\n", response.getInitialFuture().get().getName());

      // OperationFuture.get() will block until the operation is finished.
      DeployModelResponse deployModelResponse = response.get();
      System.out.format("deployModelResponse: %s\n", deployModelResponse);
    }
  }
}

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. 

def deploy_model_with_dedicated_resources_sample(
    project,
    location,
    model_name: str,
    machine_type: str,
    endpoint: Optional[aiplatform.Endpoint] = None,
    deployed_model_display_name: Optional[str] = None,
    traffic_percentage: Optional[int] = 0,
    traffic_split: Optional[Dict[str, int]] = None,
    min_replica_count: int = 1,
    max_replica_count: int = 1,
    accelerator_type: Optional[str] = None,
    accelerator_count: Optional[int] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    metadata: Optional[Sequence[Tuple[str, str]]] = (),
    sync: bool = True,
):
    """
    model_name: A fully-qualified model resource name or model ID.
          Example: "projects/123/locations/us-central1/models/456" or
          "456" when project and location are initialized or passed.
    """

    aiplatform.init(project=project, location=location)

    model = aiplatform.Model(model_name=model_name)

    # The explanation_metadata and explanation_parameters should only be
    # provided for a custom trained model and not an AutoML model.
    model.deploy(
        endpoint=endpoint,
        deployed_model_display_name=deployed_model_display_name,
        traffic_percentage=traffic_percentage,
        traffic_split=traffic_split,
        machine_type=machine_type,
        min_replica_count=min_replica_count,
        max_replica_count=max_replica_count,
        accelerator_type=accelerator_type,
        accelerator_count=accelerator_count,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        metadata=metadata,
        sync=sync,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    return model

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. 

const automl = require('@google-cloud/automl');
const client = new automl.v1beta1.AutoMlClient();

/**
 * Demonstrates using the AutoML client to create a model.
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = '[PROJECT_ID]' e.g., "my-gcloud-project";
// const computeRegion = '[REGION_NAME]' e.g., "us-central1";
// const datasetId = '[DATASET_ID]' e.g., "TBL2246891593778855936";
// const tableId = '[TABLE_ID]' e.g., "1991013247762825216";
// const columnId = '[COLUMN_ID]' e.g., "773141392279994368";
// const modelName = '[MODEL_NAME]' e.g., "testModel";
// const trainBudget = '[TRAIN_BUDGET]' e.g., "1000",
// `Train budget in milli node hours`;

// A resource that represents Google Cloud Platform location.
const projectLocation = client.locationPath(projectId, computeRegion);

// Get the full path of the column.
const columnSpecId = client.columnSpecPath(
  projectId,
  computeRegion,
  datasetId,
  tableId,
  columnId
);

// Set target column to train the model.
const targetColumnSpec = {name: columnSpecId};

// Set tables model metadata.
const tablesModelMetadata = {
  targetColumnSpec: targetColumnSpec,
  trainBudgetMilliNodeHours: trainBudget,
};

// Set datasetId, model name and model metadata for the dataset.
const myModel = {
  datasetId: datasetId,
  displayName: modelName,
  tablesModelMetadata: tablesModelMetadata,
};

// Create a model with the model metadata in the region.
client
  .createModel({parent: projectLocation, model: myModel})
  .then(responses => {
    const initialApiResponse = responses[1];
    console.log(`Training operation name: ${initialApiResponse.name}`);
    console.log('Training started...');
  })
  .catch(err => {
    console.error(err);
  });

Saiba como alterar as configurações padrão para a geração de registros de previsão.

Receber status da operação

Algumas solicitações iniciam operações de longa duração que exigem tempo para serem concluídas. Essas solicitações retornam um nome de operação, que pode ser usado para ver o status da operação ou cancelá-la. A Vertex AI oferece métodos auxiliares para realizar chamadas em operações de longa duração. Para mais informações, consulte Como trabalhar com operações de longa duração.

Receber uma previsão on-line usando o modelo implantado

Para fazer uma previsão on-line, envie um ou mais itens de teste para um modelo para análise, e o modelo retornará resultados baseados no objetivo do modelo. Use o Console do Google Cloud ou a API Vertex AI para solicitar uma previsão on-line.

Console do Google Cloud

  1. No Console do Google Cloud, na seção "Vertex AI", acesse a página Modelos.

    Acessar a página de modelos

  2. Na lista de modelos, clique no nome do modelo para solicitar previsões.

  3. Selecione a guia Implantar e testar.

  4. Na seção Testar o modelo, adicione itens de teste para solicitar uma predição. Os dados de previsão do valor de referência são preenchidos para você, ou insira seus próprios dados de previsão e clique em Prever.

    Após a conclusão da previsão, a Vertex AI retorna os resultados no console.

API: classificação

gcloud

  1. Crie um arquivo chamado request.json com o seguinte conteúdo: 

          {
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

    Substitua:

    • PREDICTION_DATA_ROW: um objeto JSON com chaves como os nomes e valores de recursos como os valores de recurso correspondentes. Por exemplo, para um conjunto de dados com um número, uma matriz de strings e uma categoria, a linha de dados pode ser semelhante à seguinte solicitação de exemplo:

      "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

      É necessário incluir um valor para cada recurso incluído no treinamento. O formato dos dados usados para previsão precisa corresponder ao formato usado para treinamento. Consulte Formato de dados para previsões para mais detalhes.

  2. Execute este comando:

    gcloud ai endpoints predict ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION_ID: a região em que você está usando a Vertex AI.

REST

Use o método endpoints.predict para solicitar uma predição on-line.

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

  • LOCATION_ID: região em que o endpoint está localizado. Por exemplo, us-central1.
  • PROJECT_ID: o ID do projeto.
  • ENDPOINT_ID: o ID do endpoint.

  • PREDICTION_DATA_ROW: um objeto JSON com chaves como os nomes e valores de recursos como os valores de recurso correspondentes. Por exemplo, para um conjunto de dados com um número, uma matriz de strings e uma categoria, a linha de dados pode ser semelhante à seguinte solicitação de exemplo:

    "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

    É necessário incluir um valor para cada recurso incluído no treinamento. O formato dos dados usados para previsão precisa corresponder ao formato usado para treinamento. Consulte Formato de dados para previsões para mais detalhes.

  • DEPLOYED_MODEL_ID: saída pelo método predict e aceita como entrada pelo método explain. O ID do modelo usado para gerar a previsão. Se você precisar solicitar explicações para uma previsão solicitada anteriormente e tiver mais de um modelo implantado, use esse ID para garantir que as explicações sejam retornadas para o mesmo modelo que forneceu a previsão anterior.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict

Corpo JSON da solicitação:

{
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

   {
     "predictions": [
      {
         "scores": [
           0.96771615743637085,
           0.032283786684274673
         ],
         "classes": [
           "0",
           "1"
         ]
      }
     ]
     "deployedModelId": "2429510197"
   }

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.util.ValueConverter;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.cloud.aiplatform.v1.schema.predict.prediction.TabularClassificationPredictionResult;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictTabularClassificationSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictTabularClassification(instance, project, endpointId);
  }

  static void predictTabularClassification(String instance, String project, String endpointId)
      throws IOException {
    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.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 (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      String location = "us-central1";
      EndpointName endpointName = EndpointName.of(project, location, endpointId);

      ListValue.Builder listValue = ListValue.newBuilder();
      JsonFormat.parser().merge(instance, listValue);
      List<Value> instanceList = listValue.getValuesList();

      Value parameters = Value.newBuilder().setListValue(listValue).build();
      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instanceList, parameters);
      System.out.println("Predict Tabular Classification Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());

      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        TabularClassificationPredictionResult.Builder resultBuilder =
            TabularClassificationPredictionResult.newBuilder();
        TabularClassificationPredictionResult result =
            (TabularClassificationPredictionResult)
                ValueConverter.fromValue(resultBuilder, prediction);

        for (int i = 0; i < result.getClassesCount(); i++) {
          System.out.printf("\tClass: %s", result.getClasses(i));
          System.out.printf("\tScore: %f", result.getScores(i));
        }
      }
    }
  }
}

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)
 */

// const endpointId = 'YOUR_ENDPOINT_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const aiplatform = require('@google-cloud/aiplatform');
const {prediction} =
  aiplatform.protos.google.cloud.aiplatform.v1.schema.predict;

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = aiplatform;

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

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictTablesClassification() {
  // Configure the endpoint resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = helpers.toValue({});

  const instance = helpers.toValue({
    petal_length: '1.4',
    petal_width: '1.3',
    sepal_length: '5.1',
    sepal_width: '2.8',
  });

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict tabular classification response');
  console.log(`\tDeployed model id : ${response.deployedModelId}\n`);
  const predictions = response.predictions;
  console.log('Predictions :');
  for (const predictionResultVal of predictions) {
    const predictionResultObj =
      prediction.TabularClassificationPredictionResult.fromValue(
        predictionResultVal
      );
    for (const [i, class_] of predictionResultObj.classes.entries()) {
      console.log(`\tClass: ${class_}`);
      console.log(`\tScore: ${predictionResultObj.scores[i]}\n\n`);
    }
  }
}
predictTablesClassification();

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. 

def predict_tabular_classification_sample(
    project: str,
    location: str,
    endpoint_name: str,
    instances: List[Dict],
):
    """
    Args
        project: Your project ID or project number.
        location: Region where Endpoint is located. For example, 'us-central1'.
        endpoint_name: A fully qualified endpoint name or endpoint ID. Example: "projects/123/locations/us-central1/endpoints/456" or
               "456" when project and location are initialized or passed.
        instances: A list of one or more instances (examples) to return a prediction for.
    """
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_name)

    response = endpoint.predict(instances=instances)

    for prediction_ in response.predictions:
        print(prediction_)

API: regressão

gcloud

  1. Crie um arquivo chamado request.json com este conteúdo: 

          {
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

    Substitua:

    • PREDICTION_DATA_ROW: um objeto JSON com chaves como os nomes e valores de recursos como os valores de recurso correspondentes. Por exemplo, para um conjunto de dados com um número, uma matriz de números e uma categoria, a linha de dados pode ser semelhante à seguinte solicitação de exemplo:

      "age":3.6,
"sq_ft":5392,
"code": "90331"

      É necessário incluir um valor para cada recurso incluído no treinamento. O formato dos dados usados para previsão precisa corresponder ao formato usado para treinamento. Consulte Formato de dados para previsões para mais detalhes.

  2. Execute este comando:

    gcloud ai endpoints predict ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION_ID: a região em que você está usando a Vertex AI.

REST

Use o método endpoints.predict para solicitar uma predição on-line.

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

  • LOCATION_ID: região em que o endpoint está localizado. Por exemplo, us-central1.
  • PROJECT_ID: o ID do projeto.
  • ENDPOINT_ID: o ID do endpoint.

  • PREDICTION_DATA_ROW: um objeto JSON com chaves como os nomes e valores de recursos como os valores de recurso correspondentes. Por exemplo, para um conjunto de dados com um número, uma matriz de números e uma categoria, a linha de dados pode ser semelhante à seguinte solicitação de exemplo:

    "age":3.6,
"sq_ft":5392,
"code": "90331"

    É necessário incluir um valor para cada recurso incluído no treinamento. O formato dos dados usados para previsão precisa corresponder ao formato usado para treinamento. Consulte Formato de dados para previsões para mais detalhes.

  • DEPLOYED_MODEL_ID: saída pelo método predict e aceita como entrada pelo método explain. O ID do modelo usado para gerar a previsão. Se você precisar solicitar explicações para uma previsão solicitada anteriormente e tiver mais de um modelo implantado, use esse ID para garantir que as explicações sejam retornadas para o mesmo modelo que forneceu a previsão anterior.

Método HTTP e URL: 

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict

Corpo JSON da solicitação:

{
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:


{
  "predictions": [
    [
      {
        "value": 65.14233,
        "lower_bound": 4.6572,
        "upper_bound": 164.0279
      }
    ]
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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.util.ValueConverter;
import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.cloud.aiplatform.v1.schema.predict.prediction.TabularRegressionPredictionResult;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictTabularRegressionSample {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictTabularRegression(instance, project, endpointId);
  }

  static void predictTabularRegression(String instance, String project, String endpointId)
      throws IOException {
    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.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 (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      String location = "us-central1";
      EndpointName endpointName = EndpointName.of(project, location, endpointId);

      ListValue.Builder listValue = ListValue.newBuilder();
      JsonFormat.parser().merge(instance, listValue);
      List<Value> instanceList = listValue.getValuesList();

      Value parameters = Value.newBuilder().setListValue(listValue).build();
      PredictResponse predictResponse =
          predictionServiceClient.predict(endpointName, instanceList, parameters);
      System.out.println("Predict Tabular Regression Response");
      System.out.format("\tDisplay Model Id: %s\n", predictResponse.getDeployedModelId());

      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        TabularRegressionPredictionResult.Builder resultBuilder =
            TabularRegressionPredictionResult.newBuilder();

        TabularRegressionPredictionResult result =
            (TabularRegressionPredictionResult) ValueConverter.fromValue(resultBuilder, prediction);

        System.out.printf("\tUpper bound: %f\n", result.getUpperBound());
        System.out.printf("\tLower bound: %f\n", result.getLowerBound());
        System.out.printf("\tValue: %f\n", result.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)
 */

// const endpointId = 'YOUR_ENDPOINT_ID';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const aiplatform = require('@google-cloud/aiplatform');
const {prediction} =
  aiplatform.protos.google.cloud.aiplatform.v1.schema.predict;

// Imports the Google Cloud Prediction service client
const {PredictionServiceClient} = aiplatform.v1;

// Import the helper module for converting arbitrary protobuf.Value objects.
const {helpers} = aiplatform;

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

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictTablesRegression() {
  // Configure the endpoint resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = helpers.toValue({});

  // TODO (erschmid): Make this less painful
  const instance = helpers.toValue({
    BOOLEAN_2unique_NULLABLE: false,
    DATETIME_1unique_NULLABLE: '2019-01-01 00:00:00',
    DATE_1unique_NULLABLE: '2019-01-01',
    FLOAT_5000unique_NULLABLE: 1611,
    FLOAT_5000unique_REPEATED: [2320, 1192],
    INTEGER_5000unique_NULLABLE: '8',
    NUMERIC_5000unique_NULLABLE: 16,
    STRING_5000unique_NULLABLE: 'str-2',
    STRUCT_NULLABLE: {
      BOOLEAN_2unique_NULLABLE: false,
      DATE_1unique_NULLABLE: '2019-01-01',
      DATETIME_1unique_NULLABLE: '2019-01-01 00:00:00',
      FLOAT_5000unique_NULLABLE: 1308,
      FLOAT_5000unique_REPEATED: [2323, 1178],
      FLOAT_5000unique_REQUIRED: 3089,
      INTEGER_5000unique_NULLABLE: '1777',
      NUMERIC_5000unique_NULLABLE: 3323,
      TIME_1unique_NULLABLE: '23:59:59.999999',
      STRING_5000unique_NULLABLE: 'str-49',
      TIMESTAMP_1unique_NULLABLE: '1546387199999999',
    },
    TIMESTAMP_1unique_NULLABLE: '1546387199999999',
    TIME_1unique_NULLABLE: '23:59:59.999999',
  });

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict tabular regression response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const predictionResultVal of predictions) {
    const predictionResultObj =
      prediction.TabularRegressionPredictionResult.fromValue(
        predictionResultVal
      );
    console.log(`\tUpper bound: ${predictionResultObj.upper_bound}`);
    console.log(`\tLower bound: ${predictionResultObj.lower_bound}`);
    console.log(`\tLower bound: ${predictionResultObj.value}`);
  }
}
predictTablesRegression();

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. 

def predict_tabular_regression_sample(
    project: str,
    location: str,
    endpoint_name: str,
    instances: List[Dict],
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_name)

    response = endpoint.predict(instances=instances)

    for prediction_ in response.predictions:
        print(prediction_)

Interpretar resultados de previsão

Classificação

Os modelos de classificação retornam uma pontuação de confiança.

A pontuação de confiança informa o quanto o modelo associa cada classe ou rótulo a um item de teste. Quanto maior o número, maior a confiança do modelo de que o rótulo precisa ser aplicado a esse item. Você decide o nível de confiança necessário para aceitar os resultados do modelo.

Regressão

Os modelos de regressão retornam um valor de previsão. Para destinos do BigQuery, eles também retornam um intervalo de previsão. O intervalo de previsão fornece um intervalo de valores em que o modelo que tem confiança de 95% contém o resultado real.

Receba uma explicação on-line usando seu modelo implantado

É possível solicitar uma previsão com explicações, também chamadas de atribuições de recursos, para ver como o modelo chegou a uma previsão. Os valores de importância do atributo local informam quanto cada atributo contribuiu para o resultado da previsão. As atribuições de recursos são incluídas nas previsões da Vertex AI pelo Explainable AI.

Console

Quando você usa o Console do Cloud para solicitar uma previsão on-line, os valores de importância do recurso local são retornados automaticamente.

Se você usou os valores de previsão preenchidos automaticamente, os valores de importância do recurso local são todos zero. Isso ocorre porque os valores pré-preenchidos são os dados de previsão do valor de referência, portanto, a previsão retornada é o valor de previsão do valor de referência.

gcloud

  1. Crie um arquivo chamado request.json com o seguinte conteúdo:

    {
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ]
}

    Substitua:

    • PREDICTION_DATA_ROW: um objeto JSON com chaves como os nomes e valores de recursos como os valores de recurso correspondentes. Por exemplo, para um conjunto de dados com um número, uma matriz de strings e uma categoria, a linha de dados pode ser semelhante à seguinte solicitação de exemplo:

      "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

      É necessário incluir um valor para cada recurso incluído no treinamento. O formato dos dados usados para previsão precisa corresponder ao formato usado para treinamento. Consulte Formato de dados para previsões para mais detalhes.

  2. Execute este comando:

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json

    Substitua:

    • ENDPOINT_ID: o ID do endpoint.
    • LOCATION_ID: a região em que você está usando a Vertex AI.

    Opcionalmente, se você quiser enviar uma solicitação de explicação para um DeployedModel específico em Endpoint, especifique a sinalização --deployed-model-id:

    gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION \
  --deployed-model-id=DEPLOYED_MODEL_ID \
  --json-request=request.json

    Além dos marcadores de posição descritos anteriormente, substitua o seguinte:

    • DEPLOYED_MODEL_ID (opcional): o ID do modelo implantado que você quer receber explicações. O ID está incluído na resposta do método predict. Se você precisar solicitar explicações para um modelo específico e tiver mais de um modelo implantado no mesmo endpoint, use esse ID para garantir que as explicações sejam retornadas.

REST

Veja no exemplo a seguir uma solicitação de previsão on-line para um modelo de classificação tabular com atribuições de recursos locais. O formato da solicitação é o mesmo para modelos de regressão.

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

  • LOCATION: região em que o endpoint está localizado. Por exemplo, us-central1.
  • PROJECT: o ID do projeto.
  • ENDPOINT_ID: o ID do endpoint.

  • PREDICTION_DATA_ROW: um objeto JSON com chaves como os nomes e valores de recursos como os valores de recurso correspondentes. Por exemplo, para um conjunto de dados com um número, uma matriz de strings e uma categoria, a linha de dados pode ser semelhante à seguinte solicitação de exemplo:

    "length":3.6,
"material":"cotton",
"tag_array": ["abc","def"]

    É necessário incluir um valor para cada recurso incluído no treinamento. O formato dos dados usados para previsão precisa corresponder ao formato usado para treinamento. Consulte Formato de dados para previsões para mais detalhes.

  • DEPLOYED_MODEL_ID (opcional): o ID do modelo implantado que você quer obter explicações. O ID está incluído na resposta do método predict. Se você precisar solicitar explicações para um modelo específico e tiver mais de um modelo implantado no mesmo endpoint, use esse ID para garantir que as explicações sejam retornadas.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain

Corpo JSON da solicitação:

{
  "instances": [
    {
      PREDICTION_DATA_ROW
    }
  ],
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

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

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
 

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. 

def explain_sample(project: str, location: str, endpoint_id: str, instance_dict: Dict):

    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_id)

    response = endpoint.explain(instances=[instance_dict], parameters={})

    for explanation in response.explanations:
        print(" explanation")
        # Feature attributions.
        attributions = explanation.attributions
        for attribution in attributions:
            print("  attribution")
            print("   baseline_output_value:", attribution.baseline_output_value)
            print("   instance_output_value:", attribution.instance_output_value)
            print("   output_display_name:", attribution.output_display_name)
            print("   approximation_error:", attribution.approximation_error)
            print("   output_name:", attribution.output_name)
            output_index = attribution.output_index
            for output_index in output_index:
                print("   output_index:", output_index)

    for prediction in response.predictions:
        print(prediction)

Receber explicações de uma previsão retornada anteriormente

Como as explicações aumentam o uso de recursos, talvez seja necessário reservar o pedido de explicação para situações em que você precise delas especificamente. Às vezes, pode ser útil solicitar explicações para um resultado de previsão que você já recebeu, talvez porque a previsão era um outlier ou não fazia sentido.

Se todas as suas previsões forem provenientes do mesmo modelo, basta simplesmente reenviar os dados da solicitação, com explicações solicitadas dessa vez. No entanto, se houver vários modelos retornando previsões, certifique-se de enviar a solicitação de explicação ao modelo correto. Para ver explicações de um modelo específico, inclua o ID deployedModelID do modelo implantado na solicitação, que está incluído na resposta da solicitação de previsão original. O ID do modelo implantado é diferente do ID do modelo.

Interpretar os resultados da explicação

Para calcular a importância do recurso local, primeiramente, é calculada a pontuação de previsão do valor de referência. Os valores de referência são calculados com base nos dados de treinamento e a utilização do valor mediano para atributos numéricos e do modo para atributos categóricos. A previsão gerada a partir dos valores de referência é a pontuação de previsão dos valores de referência. Os valores de referência são calculados uma vez para um modelo e não são alterados.

Para uma previsão específica, a importância do atributo local de cada atributo informa quanto esse atributo foi adicionado ou subtraído do resultado, em comparação com a pontuação de previsão dos valores de referência. A soma de todos os valores de importância do atributo é igual à diferença entre a pontuação de previsão dos valores de referência e o resultado da previsão.

Para modelos de classificação, a pontuação está sempre entre 0,0 e 1,0 (inclusos). Portanto, os valores de importância de recursos locais para modelos de classificação estão sempre entre -1,0 e 1,0 (inclusos).

Para ver exemplos de consultas de atribuição de recursos e saber mais, consulte Atribuições de recursos para classificação e regressão.

Exemplo de saída para previsões e explicações

Classificação

O payload de retorno de uma previsão on-line de um modelo de classificação tabular com a importância do recurso é semelhante ao exemplo a seguir.

O instanceOutputValue de 0.928652400970459 é a pontuação de confiança da classe de maior pontuação, neste caso class_a. O campo baselineOutputValue contém a pontuação de previsão do valor de referência, 0.808652400970459. O recurso que mais contribuiu para esse resultado foi feature_3.

{
"predictions": [
  {
    "scores": [
      0.928652400970459,
      0.071347599029541
    ],
    "classes": [
      "class_a",
      "class_b"
    ]
  }
]
"explanations": [
  {
    "attributions": [
      {
        "baselineOutputValue": 0.808652400970459,
        "instanceOutputValue": 0.928652400970459,
        "approximationError":  0.0058915703929231,
        "featureAttributions": {
          "feature_1": 0.012394922231235,
          "feature_2": 0.050212341234556,
          "feature_3": 0.057392736534209,
        },
        "outputIndex": [
          0
        ],
        "outputName": "scores"
      }
    ],
  }
]
"deployedModelId": "234567"
}

Regressão

O payload de retorno de uma previsão on-line com importância do recurso de um modelo de regressão tabular é semelhante ao exemplo JSON a seguir.

O instanceOutputValue de 1795.1246466281819 é o valor previsto, com os campos lower_bound e upper_bound que fornecem o intervalo de confiança de 95%. O campo baselineOutputValue contém a pontuação de previsão do valor de referência, 1788.7423095703125. O recurso que mais contribuiu para esse resultado foi feature_3.

{
"predictions": [
  {
    "value": 1795.1246466281819,
    "lower_bound": 246.32196807861328,
    "upper_bound": 8677.51904296875
  }
]
"explanations": [
  {
    "attributions": [
      {
        "baselineOutputValue": 1788.7423095703125,
        "instanceOutputValue": 1795.1246466281819,
        "approximationError": 0.0038215703911553,
        "featureAttributions": {
          "feature_1": 0.123949222312359,
          "feature_2": 0.802123412345569,
          "feature_3": 5.456264423211472,
        },
        "outputIndex": [
          -1
        ]
      }
    ]
  }
],
"deployedModelId": "345678"
}

A seguir