Exportar modelos tabulares do AutoML

Nesta página, descrevemos como usar o Vertex AI para exportar seu modelo tabular do AutoML para o Cloud Storage, fazer o download do modelo em um servidor local ou um servidor hospedado por outro provedor de nuvem e usar o Docker para deixar o modelo disponível para previsões.

Para informações sobre como exportar modelos do Edge e de imagens e vídeos, consulte Exportar modelos do AutoML Edge.

Depois de exportar o modelo tabular, se você quiser importá-lo novamente para o Vertex AI, consulte Importar modelos para o Vertex AI.

Limitações

A exportação de modelos tabulares do AutoML tem as seguintes limitações:

• É possível exportar somente modelos de classificação e regressão tabulares do AutoML. Não há como exportar modelos de previsão tabular do AutoML.

• O Explainable AI não está disponível usando modelos tabulares exportados. Se você precisar usar a Explainable AI, exiba previsões de um modelo hospedado pela Vertex AI.

• O modelo tabular exportado só pode ser executado em CPUs de arquitetura x86 compatíveis com conjuntos de instruções Advanced Vector Extensions (AVX).

Processo de exportação

As etapas para a exportação do modelo são:

1. Configure o ambiente.
2. Exportar o modelo.
3. Extrair e executar o servidor de modelo.
4. Solicitar previsões.

Antes de começar

Antes de concluir esta tarefa, é preciso que você tenha concluído as seguintes tarefas:

• Configure o projeto conforme descrito em Como configurar o ambiente de nuvem.
• Treinar o modelo de que você quer fazer o download.
• Instale e inicialize a Google Cloud CLI no servidor que você usará para executar o modelo exportado.
• Instalar o Docker no seu servidor.

Exportar o modelo

Console

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

   Acessar a página de modelos

2. Clique no modelo tabular que você quer exportar para abrir a página de detalhes.

3. Clique em Exportar na barra de botões para exportar o modelo.

4. Selecione ou crie uma pasta do Cloud Storage no local desejado.

   O bucket precisa atender aos requisitos de bucket.

   Não é possível exportar um modelo para um bucket de nível superior. Você precisa usar pelo menos um nível de pasta.

   Para melhores resultados, crie uma nova pasta vazia. Você copiará todo o conteúdo da pasta.

5. Clique em Exportar.

   Você fará o download do modelo exportado para seu servidor na próxima seção.

REST

Você usa o método models.export para exportar um modelo para o Cloud Storage.

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

• LOCATION: sua região.
• PROJECT: o ID do projeto.
• MODEL_ID: o ID do modelo que você quer exportar.
• GCS_DESTINATION: a pasta de destino no Cloud Storage. Por exemplo, gs://export-bucket/exports.

  Não é possível exportar um modelo para um bucket de nível superior. Você precisa usar pelo menos um nível de pasta.

  A pasta precisa estar em conformidade com os requisitos de bucket.

  Para melhores resultados, crie uma nova pasta. Você copiará todo o conteúdo da pasta.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models/MODEL_ID:export

Corpo JSON da solicitação:

{
  "outputConfig": {
    "exportFormatId": "tf-saved-model",
    "artifactDestination": {
      "outputUriPrefix": "GCS_DESTINATION"
    }
  }
}

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/models/MODEL_ID:export"

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/models/MODEL_ID:export" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.ExportModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-10-12T20:53:40.130785Z",
      "updateTime": "2020-10-12T20:53:40.130785Z"
    },
    "outputInfo": {
      "artifactOutputUri": "gs://OUTPUT_BUCKET/model-MODEL_ID/EXPORT_FORMAT/YYYY-MM-DDThh:mm:ss.sssZ"
    }
  }
}

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.ExportModelOperationMetadata;
import com.google.cloud.aiplatform.v1.ExportModelRequest;
import com.google.cloud.aiplatform.v1.ExportModelResponse;
import com.google.cloud.aiplatform.v1.GcsDestination;
import com.google.cloud.aiplatform.v1.ModelName;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ExportModelTabularClassificationSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String gcsDestinationOutputUriPrefix = "gs://your-gcs-bucket/destination_path";
    String project = "YOUR_PROJECT_ID";
    String modelId = "YOUR_MODEL_ID";
    exportModelTableClassification(gcsDestinationOutputUriPrefix, project, modelId);
  }

  static void exportModelTableClassification(
      String gcsDestinationOutputUriPrefix, String project, String modelId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    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";
      ModelName modelName = ModelName.of(project, location, modelId);

      GcsDestination.Builder gcsDestination = GcsDestination.newBuilder();
      gcsDestination.setOutputUriPrefix(gcsDestinationOutputUriPrefix);
      ExportModelRequest.OutputConfig outputConfig =
          ExportModelRequest.OutputConfig.newBuilder()
              .setExportFormatId("tf-saved-model")
              .setArtifactDestination(gcsDestination)
              .build();

      OperationFuture<ExportModelResponse, ExportModelOperationMetadata> exportModelResponseFuture =
          modelServiceClient.exportModelAsync(modelName, outputConfig);
      System.out.format(
          "Operation name: %s\n", exportModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      ExportModelResponse exportModelResponse =
          exportModelResponseFuture.get(300, TimeUnit.SECONDS);
      System.out.format(
          "Export Model Tabular Classification Response: %s", exportModelResponse.toString());
    }
  }
}

Node.js

Antes de testar essa amostra, siga as instruções de configuração para Node.js Guia de início rápido da Vertex AI: 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 gcsDestinationOutputUriPrefix ='YOUR_GCS_DESTINATION_\
// OUTPUT_URI_PREFIX'; eg. "gs://<your-gcs-bucket>/destination_path"
// const modelId = 'YOUR_MODEL_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 exportModelTabularClassification() {
  // Configure the name resources
  const name = `projects/${project}/locations/${location}/models/${modelId}`;
  // Configure the outputConfig resources
  const outputConfig = {
    exportFormatId: 'tf-saved-model',
    artifactDestination: {
      outputUriPrefix: gcsDestinationOutputUriPrefix,
    },
  };
  const request = {
    name,
    outputConfig,
  };

  // Export Model request
  const [response] = await modelServiceClient.exportModel(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  console.log(`Export model response : ${JSON.stringify(response.result)}`);
}
exportModelTabularClassification();

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_v1beta1

def export_model_tabular_classification_sample(
    project: str,
    model_id: str,
    gcs_destination_output_uri_prefix: str,
    location: str = "us-central1",
    api_endpoint: str = "us-central1-aiplatform.googleapis.com",
    timeout: int = 300,
):
    # 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_v1beta1.ModelServiceClient(client_options=client_options)
    gcs_destination = {"output_uri_prefix": gcs_destination_output_uri_prefix}
    output_config = {
        "artifact_destination": gcs_destination,
        "export_format_id": "tf-saved-model",
    }
    name = client.model_path(project=project, location=location, model=model_id)
    response = client.export_model(name=name, output_config=output_config)
    print("Long running operation:", response.operation.name)
    print("output_info:", response.metadata.output_info)
    export_model_response = response.result(timeout=timeout)
    print("export_model_response:", export_model_response)

Ver o status de uma operação de exportaçã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.

Extrair e executar o servidor de modelo

Nesta tarefa, você fará o download do modelo exportado do Cloud Storage e iniciará o contêiner do Docker para que seu modelo esteja pronto para receber solicitações de previsão.

Para extrair e executar o servidor de modelo:

1. Na máquina que você executará o modelo, mude para o diretório em que você quer salvar o modelo exportado.

2. Faça o download do modelo exportado:

   gsutil cp -r <var>gcs-destination</var> .
   

   Em que gcs-destination é o caminho para o local do modelo exportado no Cloud Storage.

   O modelo é copiado para o diretório atual, no seguinte caminho:

   ./model-<model-id>/tf-saved-model/<export-timestamp>

   O caminho pode conter tf-saved-model ou custom-trained.

3. Renomeie o diretório para que o carimbo de data/hora seja removido.

   mv model-<model-id>/tf-saved-model/<export-timestamp> model-<model-id>/tf-saved-model/<new-dir-name>
   

   O carimbo de data/hora torna o diretório inválido para o Docker.

4. Extraia a imagem Docker do servidor de modelo.

   sudo docker pull MODEL_SERVER_IMAGE
   

   A imagem do servidor de modelo a ser extraída está localizada no arquivo environment.json no diretório do modelo exportado. Ele precisa ter o seguinte caminho:

   ./model-<model-id>/tf-saved-model/<new-dir-name>/environment.json

   Se nenhum arquivoenvironment.json estiver presente, use:

   MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1

   Substitua MULTI_REGION por us, europe ou asia para selecionar de qual repositório do Docker você quer extrair a imagem do Docker. Cada repositório fornece a mesma imagem do Docker, mas escolher a multirregião do Artifact Registry mais próxima da máquina em que você está executando o Docker pode reduzir a latência.

5. Inicie o contêiner do Docker usando o nome do diretório que você acabou de criar:

   docker run -v `pwd`/model-<model-id>/tf-saved-model/<new-dir-name>:/models/default -p 8080:8080 -it MODEL_SERVER_IMAGE
   

É possível parar o servidor de modelo a qualquer momento, basta usar Ctrl-C.

Atualizar o contêiner do Docker do servidor de modelos

Como você faz o download do contêiner do servidor do modelo ao exportar o modelo, é necessário atualizar explicitamente o servidor do modelo para receber atualizações e correções de bugs. Atualize o servidor de modelos periodicamente usando o seguinte comando:

docker pull MODEL_SERVER_IMAGE

Verifique se o URI da imagem do Docker corresponde ao URI da imagem do Docker que você extraiu anteriormente.

Receber previsões do modelo exportado

O servidor de modelo no contêiner de imagem da Vertex AI lida com solicitações de previsão e retorna resultados de previsão.

A previsão em lote não está disponível para modelos exportados.

Formato de dados de previsão

Você fornece os dados (campo payload) para sua solicitação de previsão no seguinte formato JSON:

{ "instances": [ { "column_name_1": value, "column_name_2": value, … } , … ] }

Observação: os modelos exportados da Vertex AI não validam o formato de dados das solicitações de previsão. Isso significa que uma solicitação de previsão bem formatada com colunas ausentes, erros nos nomes das colunas ou até mesmo uma solicitação para um modelo completamente diferente retorna uma previsão (com falha ou potencialmente sem sentido). Verifique se as solicitações de previsão para modelos exportados estão corretas.

O exemplo a seguir mostra uma solicitação com três colunas: uma coluna categórica, uma matriz numérica e uma struct. A solicitação inclui duas linhas.

{
  "instances": [
    {
      "categorical_col": "mouse",
      "num_array_col": [
        1,
        2,
        3
      ],
      "struct_col": {
        "foo": "piano",
        "bar": "2019-05-17T23:56:09.05Z"
      }
    },
    {
      "categorical_col": "dog",
      "num_array_col": [
        5,
        6,
        7
      ],
      "struct_col": {
        "foo": "guitar",
        "bar": "2019-06-17T23:56:09.05Z"
      }
    }
  ]
}

Fazer a solicitação de previsão

1. Coloque os dados da solicitação em um arquivo de texto, por exemplo, tmp/request.json.

   O número de linhas de dados na solicitação de previsão, chamado de tamanho de minilote, afeta a latência de previsão e a capacidade. Quanto maior o tamanho do minilote, maior a latência e a capacidade. Para reduzir a latência, use um minilote menor. Para maior capacidade, aumente o tamanho do minilote. Os tamanhos de minilote mais usados são 1, 32, 64, 128, 256, 512 e 1024.

2. Solicite a previsão:

   curl -X POST --data @/tmp/request.json http://localhost:8080/predict
   

Formato dos resultados de previsão

O formato dos resultados depende do objetivo do seu modelo.

Resultados do modelo de classificação

Os resultados de previsão para modelos de classificação (binários e multiclasses) retornam uma pontuação de probabilidade para cada valor potencial da coluna de destino. Você precisa determinar como quer usar as pontuações. Por exemplo, para receber uma classificação binária a partir das pontuações fornecidas, você identificaria um valor limite. Se houver duas classes, "A" e "B", classifique o exemplo como "A" se a pontuação de "A" for maior que o limite escolhido, e como "B" se for menor. Em conjuntos de dados desequilibrados, o limite pode se aproximar de 100% ou de 0%.

O payload de resultados de um modelo de classificação é semelhante a este exemplo:

{
  "predictions": [
    {
      "scores": [
        0.539999994635582,
        0.2599999845027924,
        0.2000000208627896
      ],
      "classes": [
        "apple",
        "orange",
        "grape"
      ]
    },
    {
      "scores": [
        0.23999999463558197,
        0.35999998450279236,
        0.40000002086278963
      ],
      "classes": [
        "apple",
        "orange",
        "grape"
      ]
    }
  ]
}

Resultados do modelo de regressão

Um valor previsto é retornado para cada linha válida da solicitação de previsão. Os intervalos de previsão não são retornados para modelos exportados.

O payload de resultados de um modelo de regressão é semelhante a este exemplo:

{
  "predictions": [
    {
      "value": -304.3663330078125,
      "lower_bound": -56.32196807861328,
      "upper_bound": 126.51904296875
    },
    {
      "value": -112.3663330078125,
      "lower_bound": 16.32196807861328,
      "upper_bound": 255.51904296875
    }
  ]
}

A seguir

• Saiba como importar seu modelo tabular exportado para o Vertex AI.