Requisitos para fazer previsões usando um contêiner personalizado

Observação: esta é a versão 1.0.0 deste documento. O documento é atualizado de acordo com o controle de versões semântico.

Para usar um contêiner personalizado para exibir previsões de um modelo treinado personalizado, forneça a Vertex AI com uma imagem de contêiner do Docker que execute um servidor HTTP. Neste documento, você verá os requisitos que uma imagem de contêiner precisa atender para ser compatível com a Vertex AI. No documento, também descrevemos como a Vertex AI interage com o contêiner personalizado quando ele é executado. Em outras palavras, este documento descreve o que você precisa considerar ao projetar uma imagem de contêiner a ser usada com a Vertex AI.

Se quiser saber como usar uma imagem de contêiner personalizado para exibir previsões, leia Como usar um contêiner personalizado.

Requisitos de imagem do contêiner

Digamos que a imagem do contêiner do Docker seja executada como um contêiner. Nesse caso, o contêiner precisa executar um servidor HTTP. Especificamente, o contêiner precisa detectar e responder a verificações de atividade, verificações de integridade e solicitações de previsão. As subseções a seguir descrevem esses requisitos em detalhes.

É possível implementar o servidor HTTP de várias formas, com qualquer linguagem de programação, desde que atenda aos requisitos desta seção. Por exemplo, é possível gravar um servidor HTTP personalizado com um framework da Web, como Flask, ou usar um software de veiculação de machine learning (ML) que executa um servidor HTTP, como TensorFlow Serving, TorchServe ou KServe Python Serve.

Executar o servidor HTTP

É possível executar um servidor HTTP com uma instrução ENTRYPOINT, uma instrução CMD ou ambas no Dockerfile que você usa para criar a imagem do contêiner. Leia sobre a interação entre CMD e ENTRYPOINT.

Como alternativa, você pode especificar os campos containerSpec.command e containerSpec.args ao criar seu recurso Model para modificar sua imagem de contêiner ENTRYPOINT e CMD, respectivamente. Especificar um desses campos permite usar uma imagem de contêiner que não atenderia aos requisitos devido a um ENTRYPOINT ou CMD incompatível (ou inexistente).

Determine o comando que será executado quando o contêiner for iniciado. Certifique-se de que esse comando de ponto de entrada seja executado indefinidamente, seja ele qual for. Por exemplo, não execute um comando que inicie um servidor HTTP em segundo plano e depois saia. Se você fizer isso, o contêiner será encerrado imediatamente depois que começar a ser executado.

O servidor HTTP precisa detectar solicitações no 0.0.0.0, em uma porta de sua escolha. Ao criar um Model, especifique essa porta no campo containerSpec.ports. Para saber como o contêiner pode acessar esse valor, leia a seção deste documento sobre a variável de ambiente AIP_HTTP_PORT.

Verificações de atividade

A Vertex AI executa uma verificação de atividade quando o contêiner começa a garantir que o servidor está em execução. Quando você implanta um modelo treinado personalizado em um recurso Endpoint, a Vertex AI usa uma sondagem de atividade de TCP para tentar estabelecer uma conexão TCP com o contêiner na porta configurada. A sondagem faz até 4 tentativas de estabelecer uma conexão, aguardando 10 segundos após cada falha. Se a sondagem ainda não tiver estabelecido uma conexão, a Vertex AI reiniciará o contêiner.

O servidor HTTP não precisa executar nenhum comportamento especial para processar essas verificações. Enquanto estiver detectando solicitações na porta configurada, a sondagem de atividade poderá fazer uma conexão.

Verificações de integridade

Também é possível especificar startup_probe ou health_probe.

A sondagem de inicialização verifica se o aplicativo do contêiner foi iniciado. Se a sondagem de inicialização não for fornecida, não haverá sondagem de inicialização e as verificações de integridade começarão imediatamente. Se a sondagem de inicialização for fornecida, as verificações de integridade não serão realizadas até que a sondagem de inicialização seja bem-sucedida.

Aplicativos legados que podem exigir mais tempo na primeira inicialização precisam configurar uma sondagem de inicialização. Por exemplo, se o aplicativo precisar copiar os artefatos do modelo de uma fonte externa, uma sondagem de inicialização precisará ser configurada para retornar sucesso quando essa inicialização for concluída.

A sondagem de integridade verifica se um contêiner está pronto para aceitar tráfego. Se a sondagem de integridade não for fornecida, a Vertex AI usará as verificações de integridade padrão, conforme descrito neste link.

Os aplicativos legados que não retornam 200 OK para indicar que o modelo está carregado e pronto para aceitar tráfego precisam configurar uma sondagem de integridade. Por exemplo, um aplicativo pode retornar 200 OK para indicar êxito mesmo que o status real de carregamento do modelo no corpo da resposta indique que o modelo pode não estar carregado e, assim, não estar pronto para aceitar tráfego. Nesse caso, uma sondagem de integridade precisa ser configurada para retornar êxito somente quando o modelo estiver carregado e pronto para disponibilizar tráfego.

Para executar uma sondagem, a Vertex AI executa o comando exec especificado no contêiner de destino. Se o comando for bem-sucedido, ele retornará 0 e o contêiner será considerado ativo e íntegro.

Verificações de integridade padrão

Por padrão, a Vertex AI executa de maneira intermitente verificações de integridade no servidor HTTP durante a execução para garantir que ele esteja pronto para processar as solicitações de previsão. O serviço usa uma sondagem de integridade para enviar solicitações HTTP GET a um caminho de verificação de integridade configurável no seu servidor. Especifique este caminho no campo containerSpec.healthRoute ao criar um Model. Para saber como o contêiner pode acessar esse valor, leia a seção deste documento sobre a variável de ambiente AIP_HEALTH_ROUTE.

Configure o servidor HTTP para responder a cada solicitação de verificação de integridade da seguinte maneira:

• Se o servidor estiver pronto para processar solicitações de previsão, responda à solicitação de verificação de integridade dentro de 10 segundos com o código de status 200 OK. O conteúdo do corpo da resposta não importa. Ele é ignorado pela Vertex AI.

  Essa resposta significa que o servidor está íntegro.

• Se o servidor não estiver pronto para processar solicitações de previsão, não responda à solicitação de verificação de integridade em até 10 segundos nem com qualquer código de status, exceto 200 OK. Por exemplo, responda com o código de status 503 Service Unavailable.

  Esta resposta (ou a falta de uma resposta) significa que o servidor não está íntegro.

Se a sondagem de integridade receber uma resposta não íntegra do servidor, incluindo a falta de resposta em 10 segundos, ela enviará até 3 verificações de integridade extras em intervalos de 10 segundos. Durante esse período, a Vertex AI ainda considera o servidor íntegro. Se a sondagem receber uma resposta íntegra para qualquer uma dessas verificações, a sondagem retornará imediatamente para a programação intermitente das verificações de integridade. No entanto, se a sondagem receber quatro respostas consecutivas não íntegras, a Vertex AI interromperá o roteamento do tráfego de previsão ao contêiner. Se o recurso DeployedModel for escalonado para usar vários nós de previsão, a Vertex AI encaminhará as solicitações de previsão a outros contêineres íntegros.

A Vertex AI não reinicia o contêiner. Em vez disso, a sondagem continuará enviando solicitações intermitentes de verificação de integridade ao servidor não íntegro. Se receber uma resposta íntegra, ele marcará esse contêiner como íntegro e começará a rotear o tráfego de previsão para ele novamente.

Orientação prática

Em alguns casos, é suficiente que o servidor HTTP no contêiner sempre responda com o código de status 200 OK às verificações de integridade. Se o contêiner carregar recursos antes de iniciar o servidor, ele não estará íntegro durante o período de inicialização e durante qualquer período em que o servidor HTTP falhar. Em todos os outros momentos, ele responderá como íntegro.

Para uma configuração mais sofisticada, convém projetar propositalmente o servidor HTTP para responder às verificações de integridade com um status não íntegro em determinados momentos. Por exemplo, convém bloquear o tráfego de previsão em um nó por um período para que o contêiner possa realizar a manutenção.

Solicitações de previsão

Quando um cliente envia uma solicitação projects.locations.endpoints.predict para a API Vertex AI, a Vertex AI encaminha essa solicitação como uma solicitação HTTP POST a um caminho de previsão configurável no servidor. Especifique este caminho no campo containerSpec.predictRoute ao criar um Model. Para saber como o contêiner pode acessar esse valor, leia a seção deste documento sobre a variável de ambiente AIP_PREDICT_ROUTE.

Requisitos de solicitação

Se o modelo for implantado em um endpoint público, cada solicitação de previsão precisará ter 1,5 MB ou menos. O servidor HTTP precisa aceitar solicitações de previsão que tenham o cabeçalho HTTP Content-Type: application/json e os corpos JSON com o seguinte formato:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

Nessas solicitações:

• INSTANCES é uma matriz de um ou mais valores JSON de qualquer tipo. Cada valor representa uma instância em que você está fornecendo uma previsão.

• PARAMETERS é um objeto JSON que contém qualquer parâmetro que seu contêiner exige para ajudar a disponibilizar previsões nas instâncias. A Vertex AI considera o campo parameters opcional, portanto, é possível projetar o contêiner para exigi-lo, usá-lo apenas quando fornecido ou ignorá-lo.

Saiba mais sobre os requisitos do corpo da solicitação.

Requisitos de resposta

Se o modelo for implantado em um endpoint público, cada resposta de previsão precisará ter 1,5 MB ou menos. O servidor HTTP precisa enviar respostas com corpos JSON que atendam ao seguinte formato:

{
  "predictions": PREDICTIONS
}

Nessas respostas, substitua PREDICTIONS por uma matriz de valores JSON que representam as previsões geradas pelo contêiner para cada INSTANCES na solicitação correspondente.

Depois que o servidor HTTP enviar essa resposta, a Vertex AI adiciona um campo deployedModelId à resposta antes de retorná-la ao cliente. Esse campo especifica qual DeployedModel em um Endpoint está enviando a resposta. Saiba mais sobre o formato do corpo da resposta.

Observação: se seu contêiner não atender a esses requisitos para receber solicitações e enviar respostas, ainda será possível usar o contêiner para previsões brutas.

Requisitos de publicação de imagens de contêiner

É preciso enviar a imagem do contêiner ao Artifact Registry para usá-lo com a Vertex AI. Saiba como enviar uma imagem de contêiner ao Artifact Registry.

Especificamente, é necessário enviar a imagem do contêiner a um repositório que atenda aos seguintes requisitos de local e permissões.

Local

Quando você usa o Artifact Registry, o repositório precisa usar uma região que corresponda ao endpoint regional em que você planeja criar um Model. Por exemplo, se você planeja criar um Model no endpoint us-central1-aiplatform.googleapis.com, o nome completo da imagem do contêiner precisa começar com us-central1-docker.pkg.dev/. Não use um repositório multirregional para sua imagem de contêiner.

Permissões

A Vertex AI precisa ter permissão para enviar a imagem do contêiner quando você cria um Model. Especificamente, o Agente de serviço da Vertex AI do seu projeto precisa ter as permissões do papel de leitor do Artifact Registry (roles/artifactregistry.reader) para o repositório da imagem do contêiner.

O Agente de serviço da Vertex AI do projeto é a conta de serviço gerenciada pelo Google que a Vertex AI usa para interagir com outros serviços do Google Cloud. Essa conta de serviço tem o endereço de e-mail [e-mail], em que PROJECT_NUMBER é substituído pelo número do projeto da Vertex AI.

Se você enviou a imagem do contêiner para o mesmo projeto do Google Cloud em que está usando a Vertex AI, não é necessário configurar permissões. As permissões padrão concedidas ao Agente de serviço da Vertex AI são suficientes.

Por outro lado, se você enviou a imagem do contêiner para um projeto do Google Cloud diferente daquele em que está usando a Vertex AI, é necessário conceder o papel de leitor do Artifact Registry para o repositório do Artifact Registry ao Agente de serviço da Vertex AI.

Observação: mesmo que você pretenda usar uma conta de serviço personalizada no seu contêiner personalizado, não será necessário conceder permissões à conta de serviço do Artifact Registry. Somente a conta de serviço gerenciada pelo Google precisa delas. A Vertex AI não usa sua conta de serviço personalizada para extrair imagens de contêiner. Ele só usa a conta de serviço personalizada para executar o código de exibição do modelo.

Acessar artefatos de modelos

Quando você cria um modelo personalizado Model sem um contêiner personalizado, você precisa especificar o URI de um diretório do Cloud Storage com artefatos de modelo como o campoartifactUri. Ao criar um Model com um contêiner personalizado, o fornecimento de artefatos de modelo no Cloud Storage é opcional.

Se a imagem do contêiner incluir os artefatos de modelo que você precisa para exibir previsões, não será necessário carregar arquivos do Cloud Storage. No entanto, se você fornecer artefatos de modelo especificando o campo artifactUri, o contêiner precisará carregar esses artefatos quando começar a ser executado. Quando a Vertex AI inicia o contêiner, ela define a variável de ambiente AIP_STORAGE_URI como um URI do Cloud Storage que começa com gs://. O comando de entrypoint do contêiner pode fazer o download do diretório especificado por esse URI a fim de acessar os artefatos de modelo.

Lembre-se que o valor da variável de ambiente AIP_STORAGE_URI não é idêntico ao URI do Cloud Storage especificado no campo artifactUri ao criar o Model. Em vez disso, AIP_STORAGE_URI aponta para uma cópia do diretório de artefato de modelo em um bucket diferente do Cloud Storage, que a Vertex AI gerencia. A Vertex AI preenche esse diretório quando você cria um Model. Não é possível atualizar o conteúdo do diretório. Se você quiser usar novos artefatos de modelo, crie um novo Model.

A conta de serviço que seu contêiner usa por padrão tem permissão para ler esse URI.

Por outro lado, se você especificar uma conta de serviço personalizada ao implantar o Model em um Endpoint, a Vertex AI concederá automaticamente à conta de serviço especificada o papel "Leitor de objetos do Storage" (roles/storage.objectViewer) para o bucket do Cloud Storage do URI.

Use qualquer biblioteca compatível com o Application Default Credentials (ADC) para carregar os artefatos de modelo. Não será necessário configurar explicitamente a autenticação.

Variáveis de ambiente disponíveis no contêiner

Durante a execução, o comando de entrypoint do contêiner pode referir-se a variáveis de ambiente que você configurou manualmente, bem como às definidas automaticamente pela Vertex AI. Nesta seção, descrevemos as maneira de definir variáveis de ambiente e fornecemos detalhes sobre as variáveis definidas automaticamente pela Vertex AI.

Variáveis definidas na imagem do contêiner

Para definir variáveis de ambiente ao criar a imagem do contêiner, use a instrução ENV do Docker. Não defina variáveis de ambiente que comecem com o prefixo AIP_.

O comando de ponto de entrada do contêiner pode usar essas variáveis de ambiente, mas não é possível se referir a elas em nenhum dos campos de API do Model.

Variáveis definidas pela Vertex AI

Quando a Vertex AI começa a executar o contêiner, ela define as seguintes variáveis no ambiente do contêiner. Cada variável começa com o prefixo AIP_. Não defina manualmente variáveis de ambiente que usem esse prefixo.

O comando de entrypoint do contêiner pode acessar essas variáveis. Para saber quais campos da API Vertex AI também podem referenciar essas variáveis, leia a referência da API para ModelContainerSpec.

Observação: as instruções do Docker usadas para criar a imagem do contêiner, como RUN, não podem acessar essas variáveis porque você precisa criar a imagem do contêiner antes de fornecê-la à Vertex AI.

Observação: a Vertex AI define os valores de algumas das seguintes variáveis ao implantar Model como um DeployedModel em um Endpoint. É possível fazer referência a outros campos da API ao criar o Model. Os valores são expandidos sempre que você implanta o Model.

Nome da variável	Valor padrão	Como configurar o valor	Detalhes
AIP_ACCELERATOR_TYPE	Não definido	Ao implantar um Model como um DeployedModel em um recurso Endpoint, defina o campo dedicatedResources.machineSpec.acceleratorType.	Se for aplicável, essa variável especificará o tipo de acelerador usado pela instância da máquina virtual (VM) em que o contêiner está sendo executado.
AIP_DEPLOYED_MODEL_ID	Uma string de dígitos identificando o DeployedModel em que o Model deste contêiner foi implantado.	Não configurável	Esse valor é o campo id do DeployedModel.
AIP_ENDPOINT_ID	Uma string de dígitos identificando o Endpoint em que o Model do contêiner foi implantado.	Não configurável	Esse valor é o último segmento do campo name da Endpoint (depois de endpoints/).
AIP_FRAMEWORK	CUSTOM_CONTAINER	Não configurável
AIP_HEALTH_ROUTE	/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL Nesta string, substitua ENDPOINT pelo valor da variável AIP_ENDPOINT_ID e substitua DEPLOYED_MODEL pelo valor da variável AIP_DEPLOYED_MODEL_ID.	Ao criar um Model, defina o campo containerSpec.healthRoute.	Essa variável especifica o caminho HTTP no contêiner em que a Vertex AI envia verificações de integridade.
AIP_HTTP_PORT	8080	Ao criar um Model, defina o campo containerSpec.ports. A primeira entrada neste campo se torna o valor de AIP_HTTP_PORT.	A Vertex AI envia verificações de atividade, verificações de integridade e solicitações de previsão a essa porta no contêiner. O servidor HTTP do seu contêiner precisa detectar solicitações nessa porta.
AIP_MACHINE_TYPE	Nenhum padrão. Precisa ser configurado.	Ao implantar um Model como um DeployedModel em um recurso Endpoint, defina o campo dedicatedResources.machineSpec.machineType.	Essa variável especifica o tipo de VM em que o contêiner está sendo executado.
AIP_MODE	PREDICTION	Não configurável	Essa variável significa que o contêiner está em execução na Vertex AI para exibir previsões on-line. É possível usar essa variável de ambiente para adicionar lógica personalizada ao contêiner, para que ele possa ser executado em vários ambientes de computação e use apenas caminhos de código específicos quando executado na Vertex AI.
AIP_MODE_VERSION	1.0.0	Não configurável	Essa variável especifica a versão dos requisitos do contêiner personalizado (este documento) que a Vertex AI espera que sejam atendidos pelo contêiner. Este documento é atualizado de acordo com o controle de versões semântico.
AIP_MODEL_NAME	Valor da variável AIP_ENDPOINT_ID.	Não configurável	Consulte a linha AIP_ENDPOINT_ID. Essa variável existe por motivos de compatibilidade.
AIP_PREDICT_ROUTE	/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict Nesta string, substitua ENDPOINT pelo valor da variável AIP_ENDPOINT_ID e substitua DEPLOYED_MODEL pelo valor da variável AIP_DEPLOYED_MODEL_ID.	Ao criar um Model, defina o campo containerSpec.predictRoute.	Essa variável especifica o caminho HTTP no contêiner para o qual a Vertex AI encaminha as solicitações de previsão.
AIP_PROJECT_NUMBER	O número do projeto do Google Cloud em que você está usando a Vertex AI	Não configurável
AIP_STORAGE_URI	Se você não definir o campo artifactUri ao criar um Model: uma string vazia Se você definir o campo artifactUri ao criar um Model: um URI do Cloud Storage (começando com gs://) que especifica um diretório em um bucket gerenciado pela Vertex AI	Não configurável	Essa variável especifica o diretório que contém uma cópia dos artefatos de modelo, se aplicável.
AIP_VERSION_NAME	Valor da variável AIP_DEPLOYED_MODEL_ID.	Não configurável	Consulte a linha AIP_DEPLOYED_MODEL_ID. Essa variável existe por motivos de compatibilidade.

Variáveis definidas no recurso Model

Ao criar um Model, é possível definir mais variáveis de ambiente no campo containerSpec.env.

O comando de entrypoint do contêiner pode acessar essas variáveis. Para saber quais campos da API Vertex AI também podem referenciar essas variáveis, leia a referência da API para ModelContainerSpec.

Observação: as instruções do Docker usadas para criar a imagem do contêiner, como RUN, não podem acessar essas variáveis porque você precisa criar a imagem do contêiner antes de fornecê-la à Vertex AI.

A seguir

• Saiba mais sobre como exibir predições usando um contêiner personalizado, incluindo como especificar campos de API relacionados ao contêiner ao importar um modelo.