Usar um contêiner personalizado para previsão

Para personalizar a maneira como a Vertex AI exibe previsões on-line do seu modelo treinado de forma personalizada, especifique um contêiner personalizado em vez de um contêiner pré-criado ao criar o atributo Model. Quando você usa um contêiner personalizado, a Vertex AI executa um contêiner do Docker de sua escolha em cada nó de previsão.

Convém usar um contêiner personalizado por um dos seguintes motivos:

• para exibir previsões de um modelo de ML treinado usando um framework que não está disponível como um contêiner pré-criado.
• para pré-processar solicitações de previsão ou pós-processar as previsões geradas pelo modelo;
• para executar um servidor de previsão escrito em uma linguagem de programação de sua escolha;
• para instalar as dependências que você quer usar para personalizar a previsão.

Neste guia, descrevemos como criar um Model que usa um contêiner personalizado. Ele não fornece instruções detalhadas sobre como projetar e criar uma imagem de contêiner do Docker.

Preparar uma imagem de contêiner

Para criar um Model que usa um contêiner personalizado, forneça uma imagem de contêiner do Docker para ser a base do contêiner. Essa imagem de contêiner precisa atender aos requisitos descritos em Requisitos personalizados do contêiner.

Se você planeja usar uma imagem de contêiner atual criada por terceiros em quem confia, é possível pular uma ou as duas seções a seguir.

Crie uma imagem de contêiner

Projete e crie uma imagem de contêiner do Docker que atenda aos requisitos de imagem de contêiner.

Para aprender os princípios básicos de como projetar e criar uma imagem de contêiner do Docker, leia o guia de início rápido da documentação do Docker

Envie a imagem do contêiner para o Artifact Registry

Envie a imagem do contêiner para um repositório do Artifact Registry.

Saiba como enviar uma imagem de contêiner para o Artifact Registry.

Criar um Model

Para criar um Model que usa um contêiner personalizado, siga um destes procedimentos:

• Importe um modelo treinado de forma personalizada.

• Crie um TrainingPipeline que executa um CustomJob e importe os artefatos resultantes como um Model.

Nas seções a seguir, mostramos como configurar os campos da API relacionados a contêineres personalizados durante a criação de um Model.

Campos da API relacionados ao contêiner

Ao criar o Model, configure o campo containerSpec com os detalhes do seu contêiner personalizado, em vez de usar um contêiner pré-criado.

Você precisa especificar uma mensagem ModelContainerSpec no campo Model.containerSpec. Nessa mensagem, é possível especificar os subcampos a seguir:

imageUri (obrigatório)

O URI do Artifact Registry da imagem do seu contêiner.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-image-uri para especificar o campo.

command (opcional)

Uma matriz de um executável e argumentos para substituir o ENTRYPOINT do contêiner. Para saber mais sobre como formatar este campo e como ele interage com o campo args, leia a referência da API sobre ModelContainerSpec.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-command para especificar o campo.

args (opcional)

Uma matriz de um executável e argumentos para modificar o CMD do contêiner. Para saber mais sobre como formatar este campo e como ele interage com o campo command, leia a referência da API para ModelContainerSpec.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-args para especificar o campo.

ports (opcional)

Uma matriz de portas: a Vertex AI envia verificações de atividade e de integridade e solicitações de previsão ao seu contêiner na primeira porta listada ou na porta 8080 por padrão. A especificação de portas extras não tem efeito.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-ports para especificar o campo.

env (opcional)

Uma matriz de variáveis de ambiente que o comando de entrypoint do contêiner e os campos command e args podem referenciar. Para saber mais sobre como outros campos podem referenciar essas variáveis de ambiente, leia a referência da API para ModelContainerSpec.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-env-vars para especificar o campo.

healthRoute (opcional)

O caminho no servidor HTTP do contêiner em que você quer que a Vertex AI envie verificações de integridade.

Se você não especificar esse campo, então quando implantar o Model como um DeployedModel para um atributo Endpoint, o padrão será definido como /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL, em que ENDPOINT é substituído pelo último segmento do campo name do Endpoint (após endpoints/), e DEPLOYED_MODEL é substituído pelo campo id do DeployedModel.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-health-route para especificar o campo.

predictRoute (opcional)

O caminho no servidor HTTP do contêiner em que você quer que a Vertex AI encaminhe solicitações de previsão.

Se você não especificar esse campo, então quando implantar o Model como um DeployedModel para um atributo Endpoint, o padrão será definido como /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict, em que ENDPOINT é substituído pelo último segmento do campo name do Endpoint (após endpoints/), e DEPLOYED_MODEL é substituído pelo campo id do DeployedModel.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-predict-route para especificar o campo.

sharedMemorySizeMb (opcional)

A quantidade de memória da VM a ser reservada em um volume de memória compartilhada para o modelo em megabytes.

A memória compartilhada é um mecanismo de comunicação entre processos (IPC) que permite que vários processos acessem e manipulem um bloco comum de memória. A quantidade de memória compartilhada necessária, se houver, é um detalhe de implementação do contêiner e do modelo. Consulte as diretrizes na documentação do servidor de modelo.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-shared-memory-size-mb para especificar o campo.

startupProbe (opcional)

Especificação da sondagem que verifica se o aplicativo do contêiner foi iniciado.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds para especificar o campo.

healthProbe (opcional)

Especificação da sondagem que verifica se um contêiner está pronto para aceitar o tráfego.

Se você estiver usando o comando gcloud ai models upload, então poderá usar a sinalização --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds para especificar o campo.

Além das variáveis definidas no campo Model.containerSpec.env, a a Vertex AI define várias outras variáveis com base na sua configuração. Saiba mais sobre como usar variáveis de ambiente nesses campos e no comando de entrypoint do contêiner.

Exemplos de importação de modelos

Nos exemplos a seguir, mostramos como especificar campos de API relacionados ao contêiner quando você importa um modelo.

Observação: se você usar um TrainingPipeline para criar um Model, deverá especificar esses campos em um contexto diferente. Não é possível usar a Google Cloud CLI para criar um TrainingPipeline. Leia mais sobre como criar atributos TrainingPipeline personalizados.

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 \
  --container-command=COMMAND \
  --container-args=ARGS \
  --container-ports=PORTS \
  --container-env-vars=ENV \
  --container-health-route=HEALTH_ROUTE \
  --container-predict-route=PREDICT_ROUTE \
  --container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
  --container-startup-probe-exec=STARTUP_PROBE_EXEC \
  --container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
  --container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
  --container-health-probe-exec=HEALTH_PROBE_EXEC \
  --container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
  --container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

A sinalização --container-image-uri é obrigatória, todas as outras sinalizações que começam com --container- são opcionais. Para saber mais sobre os valores desses campos, consulte a seção anterior deste guia.

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

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

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 mais contexto, leia o Guia de importação de modelos.

Enviar solicitações de previsão

Para enviar uma solicitação de previsão on-line ao Model, siga as instruções em Receber previsões de um modelo treinado personalizado: esse processo funciona, não importa se você usa um contêiner personalizado.

Leia sobre os requisitos de solicitação e resposta de previsão para contêineres personalizados.

A seguir

• Para saber mais sobre tudo que deve ser considerado ao projetar um contêiner personalizado para usar com a Vertex AI,, leia Requisitos de contêineres personalizados.