Importar modelos para a Vertex AI

Neste guia, descrevemos como importar modelos para o Registro de modelos. Depois de importar o modelo, ele ficará visível no Registro de modelos. No Model Registry, é possível implantar seu modelo importado em um endpoint e executar previsões.

Funções exigidas

Para receber as permissões necessárias para importar modelos, peça ao administrador para conceder a você o papel do IAM de Usuário da Vertex AI (roles/aiplatform.user) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Contêineres pré-criados ou personalizados

Ao importar um modelo, você o associa a um contêiner para que na Vertex AI, execute solicitações de previsão. É possível usar contêineres pré-criados fornecidos pela Vertex AI ou usar seus próprios contêineres personalizados que você cria e envia para o Artifact Registry.

Use um contêiner pré-criado se seu modelo atender aos requisitos a seguir:

Se você estiver importando um modelo do AutoML tabular exportado anteriormente, use um contêiner personalizado específico fornecido pelo Vertex AI.

Caso contrário, crie um novo contêiner personalizado ou use um que você já tem no Artifact Registry.

Fazer upload de artefatos de modelo no Cloud Storage

Armazene os artefatos do modelo em um bucket do Cloud Storage, em que a região do bucket corresponde ao endpoint regional que você está usando.

Se o bucket do Cloud Storage estiver em um projeto diferente do Google Cloud, você precisará conceder acesso à Vertex AI, para ler os artefatos do modelo.

Se você estiver usando um contêiner pré-criado, verifique se os artefatos do modelo têm nomes de arquivo que correspondem exatamente aos seguintes exemplos:

  • SavedModel do TensorFlow: saved_model.pb
  • PyTorch: model.mar
  • scikit-learn: model.joblib ou model.pkl
  • XGBoost: model.bst, model.joblib ou model.pkl

Saiba mais sobre como exportar artefatos de modelo para predição.

Importar um modelo usando o console do Google Cloud

Para importar um modelo usando o console do Google Cloud:

  1. No console do Google Cloud, acesse a página Modelos da Vertex AI.

    Acessar a página de modelos

  2. Clique em Importar.

  3. Selecione Importar como novo modelo para importar um novo modelo.

  4. Selecione Importar como nova versão para importar um modelo como uma versão de um modelo atual. Para saber mais sobre o controle de versões de modelos, consulte Controle de versões de modelos.

  5. Nome e região: insira um nome para seu modelo. Selecione a região que corresponde à região do seu bucket e ao endpoint regional da Vertex AI,que você está usando. Clique em Continuar.

  6. Se você expandir as Opções avançadas, poderá optar por adicionar uma chave de criptografia gerenciada pelo cliente.

Dependendo do tipo de contêiner que você está usando, selecione a guia apropriada abaixo.

Contêiner pré-criado

  1. Selecione Importar artefatos de modelo em um novo contêiner predefinido.

  2. Selecione o Framework de modelo e Versão do framework de modelo usados para treinar o modelo.

  3. Se você quiser usar GPUs para exibir previsões, defina o Tipo de acelerador como GPUs.

    Você seleciona o tipo de GPU posteriormente, quando implanta o modelo em um endpoint.

  4. Especifique o caminho do Cloud Storage para o diretório que contém os artefatos do modelo.

    Exemplo: gs://BUCKET_NAME/models/.

  5. Deixe o Predict schemata em branco.

  6. Para importar o modelo sem as configurações da Vertex Explainable AI, clique em Importar.

    Após a conclusão da importação, seu modelo aparece na página Modelos.

    Caso contrário, continue configurando o modelo inserindo as configurações de explicabilidade na guia Explicação. Saiba mais sobre as configurações de explicabilidade.

Contêiner personalizado

  1. Selecione Importar um contêiner personalizado existente.

  2. Defina o URI da imagem do contêiner.

  3. Se você quiser fornecer artefatos de modelo além de uma imagem de contêiner, especifique o caminho do Cloud Storage para o diretório que contém os artefatos do modelo.

    Por exemplo, gs://BUCKET_NAME/models/

  4. Especifique valores para qualquer um dos outros campos.

    Saiba mais sobre esses campos opcionais.

  5. Para importar o modelo sem as configurações da Vertex Explainable AI, clique em Importar.

    Após a conclusão da importação, seu modelo aparece na página Modelos.

    Caso contrário, continue configurando o modelo inserindo as configurações de explicabilidade na guia Explicação. Saiba mais sobre as configurações de explicabilidade.

Contêiner tabular do AutoML

  1. Selecione Importar um contêiner personalizado existente.

  2. No campo Imagem do contêiner, insira MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

    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.

  3. No campo Local do pacote, especifique o caminho do Cloud Storage para o diretório que contém os artefatos do modelo.

    O caminho é semelhante ao seguinte exemplo:

    gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/

  4. Não preencha os outros campos.

  5. Clique em Importar.

    Após a conclusão da importação, seu modelo aparece na página Modelos. É possível usar esse modelo da mesma forma que outros modelos tabulares do AutoML, mas os modelos tabulares importados do AutoML não são compatíveis com a Vertex Explainable AI.

Importar um modelo de maneira programática

Os exemplos a seguir mostram como importar um modelo usando várias ferramentas:

gcloud

O exemplo a seguir usa o comando gcloud ai models upload:

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

Substitua:

  • LOCATION_ID: a região em que você está usando a Vertex AI.
  • MODEL_NAME: um nome de exibição para Model.
  • IMAGE_URI: o URI da imagem do contêiner a ser usado para exibir as previsões. Por exemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Use um contêiner pré-criado ou um contêiner personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: o URI do Cloud Storage (começando com gs://) de um diretório no Cloud Storage que contém seus artefatos do modelo.

No exemplo anterior, demonstramos todas as sinalizações necessárias para importar a maioria dos modelos. Se você não estiver usando um contêiner predefinido para predição, provavelmente será necessário especificar algumas sinalizações opcionais adicionais para que a Vertex AI possa usar sua imagem de contêiner. Essas sinalizações, que começam com --container-, correspondem aos campos do containerSpec do Model.

REST

Use o mesmo exemplo de código a seguir para fazer upload de um modelo usando o método upload do recurso model.

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.
  • MODEL_NAME: um nome de exibição para Model.
  • MODEL_DESCRIPTION: opcional. Uma descrição do modelo.
  • IMAGE_URI: o URI da imagem do contêiner a ser usado para exibir as previsões. Por exemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Use um contêiner pré-criado ou um contêiner personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: o URI do Cloud Storage (começando com gs://) de um diretório no Cloud Storage que contém seus artefatos do modelo. Essa variável e o campo artifactUri são opcionais se você estiver usando um contêiner personalizado.
  • labels: opcional. Qualquer conjunto de pares de chave-valor para organizar seus modelos. Por exemplo:
    • "env": "prod"
    • "tier": "backend"
  • Especifique LABEL_NAME e LABEL_VALUE para todos os rótulos que você quiser aplicar a esse pipeline de treinamento.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "model": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "labels": {
      "LABEL_NAME_1": "LABEL_VALUE_1",
      "LABEL_NAME_2": "LABEL_VALUE_2"
    }
  }
}

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

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

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.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import com.google.cloud.aiplatform.v1.UploadModelOperationMetadata;
import com.google.cloud.aiplatform.v1.UploadModelResponse;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UploadModelSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String modelDisplayName = "YOUR_MODEL_DISPLAY_NAME";
    String metadataSchemaUri =
        "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
    String imageUri = "YOUR_IMAGE_URI";
    String artifactUri = "gs://your-gcs-bucket/artifact_path";
    uploadModel(project, modelDisplayName, metadataSchemaUri, imageUri, artifactUri);
  }

  static void uploadModel(
      String project,
      String modelDisplayName,
      String metadataSchemaUri,
      String imageUri,
      String artifactUri)
      throws IOException, InterruptedException, ExecutionException, 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";
      LocationName locationName = LocationName.of(project, location);

      ModelContainerSpec modelContainerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();

      Model model =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setMetadataSchemaUri(metadataSchemaUri)
              .setArtifactUri(artifactUri)
              .setContainerSpec(modelContainerSpec)
              .build();

      OperationFuture<UploadModelResponse, UploadModelOperationMetadata> uploadModelResponseFuture =
          modelServiceClient.uploadModelAsync(locationName, model);
      System.out.format(
          "Operation name: %s\n", uploadModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      UploadModelResponse uploadModelResponse = uploadModelResponseFuture.get(5, TimeUnit.MINUTES);

      System.out.println("Upload Model Response");
      System.out.format("Model: %s\n", uploadModelResponse.getModel());
    }
  }
}

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.\
 */

// const modelDisplayName = 'YOUR_MODEL_DISPLAY_NAME';
// const metadataSchemaUri = 'YOUR_METADATA_SCHEMA_URI';
// const imageUri = 'YOUR_IMAGE_URI';
// const artifactUri = 'YOUR_ARTIFACT_URI';
// 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 uploadModel() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}`;
  // Configure the model resources
  const model = {
    displayName: modelDisplayName,
    metadataSchemaUri: '',
    artifactUri: artifactUri,
    containerSpec: {
      imageUri: imageUri,
      command: [],
      args: [],
      env: [],
      ports: [],
      predictRoute: '',
      healthRoute: '',
    },
  };
  const request = {
    parent,
    model,
  };

  console.log('PARENT AND MODEL');
  console.log(parent, model);
  // Upload Model request
  const [response] = await modelServiceClient.uploadModel(request);
  console.log(`Long running operation : ${response.name}`);

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

  console.log('Upload model response ');
  console.log(`\tModel : ${result.model}`);
}
uploadModel();

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 typing import Dict, Optional, Sequence

from google.cloud import aiplatform
from google.cloud.aiplatform import explain


def upload_model_sample(
    project: str,
    location: str,
    display_name: str,
    serving_container_image_uri: str,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    sync: bool = True,
):

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

    model = aiplatform.Model.upload(
        display_name=display_name,
        artifact_uri=artifact_uri,
        serving_container_image_uri=serving_container_image_uri,
        serving_container_predict_route=serving_container_predict_route,
        serving_container_health_route=serving_container_health_route,
        instance_schema_uri=instance_schema_uri,
        parameters_schema_uri=parameters_schema_uri,
        prediction_schema_uri=prediction_schema_uri,
        description=description,
        serving_container_command=serving_container_command,
        serving_container_args=serving_container_args,
        serving_container_environment_variables=serving_container_environment_variables,
        serving_container_ports=serving_container_ports,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        sync=sync,
    )

    model.wait()

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

Para importar um modelo com as configurações da Vertex Explainable AI ativadas, consulte os exemplos de importação do Vertex Explainable AI.

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.

Limitações

  • O tamanho máximo do modelo compatível é 10 GiB.

A seguir