Use um contentor personalizado para a inferência

Para personalizar a forma como o Vertex AI apresenta inferências online a partir do seu modelo preparado de forma personalizada, pode especificar um contentor personalizado em vez de um contentor pré-criado quando cria um recurso Model. Quando usa um contentor personalizado, o Vertex AI executa um contentor Docker à sua escolha em cada nó de inferência.

Pode querer usar um contentor personalizado por qualquer um dos seguintes motivos:

  • Para publicar inferências a partir de um modelo de ML preparado com uma framework que não está disponível como um contentor pré-criado
  • Para pré-processar pedidos de inferência ou pós-processar as inferências geradas pelo seu modelo
  • para executar um servidor de inferência escrito numa linguagem de programação à sua escolha
  • Para instalar dependências que quer usar para personalizar inferências

Este guia descreve como criar um modelo que usa um contentor personalizado. Não fornece instruções detalhadas sobre a conceção e a criação de uma imagem de contentor do Docker.

Prepare uma imagem de contentor

Para criar um Model que use um contentor personalizado, tem de fornecer uma imagem de contentor Docker como base desse contentor. Esta imagem do contentor tem de cumprir os requisitos descritos nos requisitos do contentor personalizado.

Se planeia usar uma imagem de contentor existente criada por terceiros em quem confia, pode ignorar uma ou ambas as seguintes secções.

Crie uma imagem de contentor

Conceba e crie uma imagem de contentor do Docker que cumpra os requisitos da imagem de contentor.

Para aprender os princípios básicos da conceção e criação de uma imagem de contentor do Docker, leia o início rápido da documentação do Docker

Envie a imagem do contentor para o Artifact Registry

Envie a sua imagem de contentor para um repositório do Artifact Registry.

Saiba como enviar uma imagem de contentor para o Artifact Registry.

Crie um Model

Para criar um Model que use um contentor personalizado, faça uma das seguintes ações:

As secções seguintes mostram como configurar os campos da API relacionados com contentores personalizados quando cria um Model de uma destas formas.

Campos da API relacionados com o contentor

Quando criar o Model, certifique-se de que configura o campo containerSpec com os detalhes do seu contentor personalizado, em vez de com um contentor pré-criado.

Tem de especificar uma ModelContainerSpec mensagem no campo Model.containerSpec. Nesta mensagem, pode especificar os seguintes subcampos:

imageUri (obrigatório)

O URI do Artifact Registry da sua imagem de contentor.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-image-uri para especificar este campo.

command (opcional)

Uma matriz de um executável e argumentos para substituir a instrução ENTRYPOINT do contentor. Para saber como formatar este campo e como interage com o campo args, leia a referência da API para ModelContainerSpec.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-command para especificar este campo.

args (opcional)

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

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-args para especificar este campo.

ports (opcional)

Uma matriz de portas; o Vertex AI envia verificações de atividade, verificações de estado e pedidos de inferência para o seu contentor na primeira porta indicada ou 8080 por predefinição. A especificação de portas adicionais não tem efeito.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-ports para especificar este campo.

env (opcional)

Uma matriz de variáveis de ambiente que a instrução ENTRYPOINT do contentor, bem como os campos command e args, podem referenciar. Para saber mais sobre como outros campos podem fazer referência a estas variáveis de ambiente, leia a referência da API para ModelContainerSpec.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-env-vars para especificar este campo.

healthRoute (opcional)

O caminho no servidor HTTP do contentor para o qual quer que o Vertex AI envie verificações de estado.

Se não especificar este campo, quando implementar o Model como um DeployedModel num recurso Endpoint, o valor predefinido é /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL, em que ENDPOINT é substituído pelo último segmento do campo name do recurso Endpoint (após endpoints/) e DEPLOYED_MODEL é substituído pelo campo id do recurso DeployedModel.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-health-route para especificar este campo.

predictRoute (opcional)

O caminho no servidor HTTP do contentor para o qual quer que o Vertex AI encaminhe pedidos de inferência.

Se não especificar este campo, quando implementar o Model como um DeployedModel num recurso Endpoint, o valor predefinido é /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict, em que ENDPOINT é substituído pelo último segmento do campo name do recurso Endpoint (após endpoints/) e DEPLOYED_MODEL é substituído pelo campo id do recurso DeployedModel.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-predict-route para especificar este campo.

invokeRoutePrefix (opcional)

Invoque o prefixo do caminho para o contentor personalizado. Definir este campo como "/*" ativa o encaminhamento arbitrário para o modelo. Após a implementação, qualquer rota não raiz no servidor do modelo fica acessível com a chamada HTTP invoke. Por exemplo, "/invoke/foo/bar" seria encaminhado como "/foo/bar" para o servidor do modelo. Esta funcionalidade está na fase de pré-visualização pública. Para criar um modelo com invocação ativada, siga as instruções para usar rotas personalizadas arbitrárias.

sharedMemorySizeMb (opcional)

A quantidade de memória da VM a reservar num volume de memória partilhada para o modelo em megabytes.

A memória partilhada é um mecanismo de comunicação entre processos (IPC) que permite que vários processos acedam e manipulem um bloco de memória comum. A quantidade de memória partilhada necessária, se existir, é um detalhe de implementação do seu contentor e modelo. Consulte a documentação do servidor de modelos para ver diretrizes.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-shared-memory-size-mb para especificar este campo.

startupProbe (opcional)

Especificação da sonda que verifica se a aplicação do contentor foi iniciada.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds para especificar este campo.

healthProbe (opcional)

Especificação da sonda que verifica se um contentor está pronto para aceitar tráfego.

Se estiver a usar o comando gcloud ai models upload, pode usar a flag --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds para especificar este campo.

Além das variáveis que define no campo Model.containerSpec.env, o Vertex AI define várias outras variáveis com base na sua configuração. Saiba mais sobre a utilização destas variáveis de ambiente nestes campos e na instrução ENTRYPOINT do contentor.

Exemplos de importação de modelos

Os exemplos seguintes mostram como especificar campos da API relacionados com o contentor quando importa um modelo.

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 \
  --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 flag --container-image-uri é obrigatória. Todas as outras flags que começam com --container- são opcionais. Para saber mais sobre os valores destes campos, consulte a secção anterior deste guia.

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

Envie pedidos de inferência

Para enviar um pedido de inferência online para o seu Model, siga as instruções em Obtenha inferências a partir de um modelo preparado personalizado: este processo funciona da mesma forma, independentemente de usar um contentor personalizado.

Leia acerca dos requisitos de pedidos de previsão e respostas para contentores personalizados.

O que se segue?