Importe modelos para o Vertex AI

Este guia descreve como importar modelos para o Registo de modelos da Vertex AI. Depois de importar o modelo, este fica visível no Model Registry. No Model Registry, pode implementar o modelo importado num ponto final e executar inferências.

Funções necessárias

Para receber as autorizações de que precisa para importar modelos, peça ao seu administrador para lhe conceder a função de IAM de utilizador da Vertex AI (roles/aiplatform.user) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Contentores pré-criados ou personalizados

Quando importa um modelo, associa-o a um contentor para que o Vertex AI execute pedidos de inferência. Pode usar contentores pré-criados fornecidos pelo Vertex AI ou usar os seus próprios contentores personalizados que cria e envia para o Artifact Registry.

Pode usar um contentor pré-criado se o seu modelo cumprir os seguintes requisitos:

Se estiver a importar um modelo AutoML tabular que tenha exportado anteriormente, tem de usar um contentor personalizado específico fornecido pelo Vertex AI.

Caso contrário, crie um novo contentor personalizado ou use um contentor personalizado existente que tenha no Artifact Registry.

Carregue artefactos do modelo para o Cloud Storage

Tem de armazenar os artefactos do modelo num contentor do Cloud Storage, onde a região do contentor corresponde ao ponto final de localização que está a usar.

Se o seu contentor do Cloud Storage estiver num Google Cloud projeto diferente, tem de conceder acesso ao Vertex AI para ler os artefactos do modelo.

Se estiver a usar um contentor pré-criado, certifique-se de que os nomes dos ficheiros dos artefactos do modelo correspondem exatamente aos seguintes exemplos:

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

Saiba mais sobre a exportação de artefactos de modelos para inferência.

Importe um modelo através da Google Cloud consola

Para importar um modelo através da Google Cloud consola:

  1. Na Google Cloud consola, aceda à página Modelos do Vertex AI.

    Aceda à página 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 existente. Para saber mais sobre o controlo de versões de modelos, consulte o artigo Controlo de versões de modelos.

  5. Nome e região: introduza um nome para o modelo. Selecione a região que corresponde à região do seu contentor e ao ponto final de localização do Vertex AI que está a usar. Clique em Continuar.

  6. Se expandir as Opções avançadas, pode optar por adicionar uma chave de encriptação gerida pelo cliente.

Consoante o tipo de contentor que estiver a usar, selecione o separador adequado abaixo.

Contentor pré-criado

  1. Selecione Importar artefactos do modelo para um novo contentor pré-criado.

  2. Selecione o Framework do modelo e a Versão do framework do modelo que usou para preparar o seu modelo.

  3. Se quiser usar GPUs para publicar inferências, defina o tipo de acelerador como GPUs.

    Seleciona o tipo de GPU mais tarde, quando implementar o modelo num ponto final.

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

    Por exemplo, gs://BUCKET_NAME/models/.

  5. Deixe o campo Predict schemata em branco.

  6. Para importar o seu modelo sem as definições do Vertex AI explicável, clique em Importar.

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

    Caso contrário, continue a configurar o modelo introduzindo as definições de explicabilidade no separador Explicabilidade. Saiba mais acerca das definições de explicabilidade.

Contentor personalizado

  1. Selecione Importar um contentor personalizado existente.

  2. Defina o URI da imagem de contentor.

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

    Por exemplo, gs://BUCKET_NAME/models/.

  4. Especifique valores para qualquer um dos outros campos.

    Saiba mais sobre estes campos opcionais.

  5. Para importar o seu modelo sem as definições do Vertex AI explicável, clique em Importar.

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

    Caso contrário, continue a configurar o modelo introduzindo as definições de explicabilidade no separador Explicabilidade. Saiba mais acerca das definições de explicabilidade.

Recipiente tabular do AutoML

  1. Selecione Importar um contentor personalizado existente.

  2. No campo Imagem do contentor, introduza MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

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

  3. No campo Localização do pacote, especifique o caminho do Cloud Storage para o diretório que contém os artefactos do modelo.

    O caminho é semelhante ao seguinte exemplo:

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

  4. Deixe todos os outros campos em branco.

  5. Clique em Importar.

    Após a conclusão da importação, o modelo é apresentado na página Modelos. Pode usar este modelo tal como outros modelos tabulares do AutoML, exceto que os modelos tabulares do AutoML importados não suportam a IA explicável do Vertex.

Importe um modelo através de programação

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

gcloud

O exemplo seguinte 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 o seguinte:

  • LOCATION_ID: a região onde está a usar o Vertex AI.
  • MODEL_NAME: um nome a apresentar para o Model.
  • IMAGE_URI: o URI da imagem do contentor a usar para publicar inferências. Por exemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Use um contentor pré-criado ou um contentor personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: o URI do Cloud Storage (a começar por gs://) de um diretório no Cloud Storage que contém os seus artefactos do modelo.

O exemplo anterior demonstra todas as flags necessárias para importar a maioria dos modelos. Se não estiver a usar um contentor pré-criado para a inferência, é provável que tenha de especificar algumas flags opcionais adicionais para que o Vertex AI possa usar a sua imagem de contentor. Estas flags, que começam com --container-, correspondem aos campos do ModelcontainerSpec.

REST

Use o seguinte exemplo de código para carregar um modelo através do método upload do recurso model.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION_ID: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu ID do projeto.
  • MODEL_NAME: um nome a apresentar para o Model.
  • MODEL_DESCRIPTION: opcional. Uma descrição do modelo.
  • IMAGE_URI: o URI da imagem do contentor a usar para publicar inferências. Por exemplo, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Use um contentor pré-criado ou um contentor personalizado.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: o URI do Cloud Storage (a começar por gs://) de um diretório no Cloud Storage que contém os seus artefactos do modelo. Esta variável e o campo artifactUri são opcionais se estiver a usar um contentor personalizado.
  • labels: opcional. Qualquer conjunto de pares de chave-valor para organizar os seus modelos. Por exemplo:
    • "env": "prod"
    • "tier": "backend"
  • Especifique o LABEL_NAME e o LABEL_VALUE para todas as etiquetas que quer aplicar a este pipeline de preparação.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "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 o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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 experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da API. 

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 definições do Vertex Explainable AI ativadas, consulte os exemplos de importação de modelos do Vertex Explainable AI.

Obtenha o estado da operação

Alguns pedidos iniciam operações de longa duração que requerem tempo para serem concluídas. Estes pedidos devolvem um nome da operação, que pode usar para ver o estado da operação ou cancelar a operação. A Vertex AI fornece métodos auxiliares para fazer chamadas contra operações de longa duração. Para mais informações, consulte o artigo Trabalhar com operações de longa duração.

Limitações

  • O tamanho máximo do modelo suportado pelo registo de modelos é de 1 TB.

O que se segue?