Requisitos de contentores personalizados para inferência

Para usar um contentor personalizado para apresentar inferências de um modelo preparado de forma personalizada, tem de fornecer ao Vertex AI uma imagem de contentor Docker que execute um servidor HTTP. Este documento descreve os requisitos que uma imagem de contentor tem de cumprir para ser compatível com o Vertex AI. O documento também descreve como o Vertex AI interage com o seu contentor personalizado assim que começa a ser executado. Por outras palavras, este documento descreve o que tem de considerar ao conceber uma imagem de contentor para usar com o Vertex AI.

Para ver um passo a passo da utilização de uma imagem de contentor personalizada para publicar inferências, leia o artigo Usar um contentor personalizado.

Requisitos de imagens de contentores

Quando a imagem do contentor do Docker é executada como um contentor, o contentor tem de executar um servidor HTTP. Especificamente, o contentor tem de ouvir e responder a verificações de vitalidade, verificações de estado e pedidos de inferência. As subsecções seguintes descrevem estes requisitos detalhadamente.

Pode implementar o servidor HTTP de qualquer forma, usando qualquer linguagem de programação, desde que cumpra os requisitos nesta secção. Por exemplo, pode escrever um servidor HTTP personalizado usando uma framework Web como o Flask ou usar software de publicação de aprendizagem automática (AA) que execute um servidor HTTP, como o TensorFlow Serving, o TorchServe ou o servidor Python KServe.

Execute o servidor HTTP

Pode executar um servidor HTTP usando uma ENTRYPOINTinstrução, uma CMDinstrução ou ambas no Dockerfile que usa para criar a imagem do contentor. Leia acerca da interação entre CMD e ENTRYPOINT.

Em alternativa, pode especificar os campos containerSpec.command e containerSpec.args quando cria o recurso Model para substituir os campos ENTRYPOINT e CMD da imagem do contentor, respetivamente. A especificação de um destes campos permite-lhe usar uma imagem de contentor que, de outra forma, não cumpriria os requisitos devido a um ENTRYPOINT ou CMD incompatível (ou inexistente).

No entanto, independentemente de determinar que comando o seu contentor executa quando é iniciado, certifique-se de que esta instrução ENTRYPOINT é executada indefinidamente. Por exemplo, não execute um comando que inicie um servidor HTTP em segundo plano e, em seguida, termine. Se o fizer, o contentor termina imediatamente após o início da execução.

O seu servidor HTTP tem de ouvir pedidos em 0.0.0.0, numa porta à sua escolha. Quando cria um Model, especifique esta porta no campo containerSpec.ports. Para saber como o contentor pode aceder a este valor, leia a secção deste documento sobre a variável de ambiente AIP_HTTP_PORT.

Verificações de atividade

O Vertex AI realiza uma verificação de atividade quando o contentor é iniciado para garantir que o servidor está em execução. Quando implementa um modelo preparado de forma personalizada num recurso Endpoint, o Vertex AI usa uma sondagem de atividade TCP para tentar estabelecer uma ligação TCP ao seu contentor na porta configurada. A sondagem faz até 4 tentativas para estabelecer uma ligação, aguardando 10 segundos após cada falha. Se a sonda ainda não tiver estabelecido uma ligação neste momento, o Vertex AI reinicia o contentor.

O seu servidor HTTP não precisa de ter um comportamento especial para processar estas verificações. Enquanto estiver a ouvir pedidos na porta configurada, a sondagem de atividade é capaz de estabelecer uma ligação.

Verificações de funcionamento

Opcionalmente, pode especificar startup_probe ou health_probe.

A sondagem de arranque verifica se a aplicação de contentor foi iniciada. Se não for fornecida uma sonda de arranque, não existe uma sonda de arranque e as verificações de estado de funcionamento começam imediatamente. Se for fornecida uma sondagem de arranque, as verificações de funcionamento não são realizadas até que a sondagem de arranque seja bem-sucedida.

As aplicações antigas que possam exigir um tempo de arranque adicional na respetiva inicialização devem configurar uma sondagem de arranque. Por exemplo, se a aplicação precisar de copiar os artefactos do modelo de uma origem externa, deve configurar uma sondagem de arranque para devolver o sucesso quando essa inicialização estiver concluída.

A sondagem de estado verifica se um contentor está pronto para aceitar tráfego. Se não for fornecida uma sondagem de funcionamento, a Vertex AI usa as verificações de funcionamento predefinidas, conforme descrito em Verificações de funcionamento predefinidas.

As aplicações antigas que não devolvem 200 OK para indicar que o modelo está carregado e pronto para aceitar tráfego devem configurar uma análise de integridade. Por exemplo, uma aplicação pode devolver 200 OK para indicar êxito, embora o estado de carregamento do modelo real que se encontra no corpo da resposta indique que o modelo pode não estar carregado e, por conseguinte, pode não estar pronto para aceitar tráfego. Neste caso, deve configurar uma sondagem de integridade para devolver êxito apenas quando o modelo estiver carregado e pronto para publicar tráfego.

Para realizar uma sondagem, o Vertex AI executa o execcomando especificado no contentor de destino. Se o comando for bem-sucedido, devolve 0 e o contentor é considerado ativo e em bom estado.

Verificações de funcionamento predefinidas

Por predefinição, o Vertex AI realiza verificações de estado intermitentemente no seu servidor HTTP enquanto está em execução para garantir que está pronto para processar pedidos de inferência. O serviço usa uma sonda de funcionamento para enviar pedidos HTTP GET para um caminho de verificação de funcionamento configurável no seu servidor. Especifique este caminho no campo containerSpec.healthRoute quando criar um Model. Para saber como o contentor pode aceder a este valor, leia a secção deste documento sobre a variável de ambiente AIP_HEALTH_ROUTE.

Configure o servidor HTTP para responder a cada pedido de verificação de funcionamento da seguinte forma:

  • Se o servidor estiver pronto para processar pedidos de inferência, responda ao pedido de verificação do estado no prazo de 10 segundos com o código de estado 200 OK. O conteúdo do corpo da resposta não é importante. O Vertex AI ignora-o.

    Esta resposta significa que o servidor está em bom estado.

  • Se o servidor não estiver pronto para processar pedidos de inferência, não responda ao pedido de verificação do estado no prazo de 10 segundos ou responda com qualquer código de estado, exceto 200 OK. Por exemplo, responda com o código de estado 503 Service Unavailable.

    Esta resposta (ou a ausência de uma resposta) significa que o servidor não está em bom estado.

Se a análise de integridade receber uma resposta não saudável do seu servidor (incluindo nenhuma resposta no prazo de 10 segundos), envia até 3 verificações de integridade adicionais a intervalos de 10 segundos. Durante este período, o Vertex AI continua a considerar o seu servidor como estando em bom estado. Se a sonda receber uma resposta válida a qualquer uma destas verificações, a sonda regressa imediatamente à sua programação intermitente de verificações de funcionamento. No entanto, se a sondagem receber 4 respostas não íntegras consecutivas, o Vertex AI deixa de encaminhar o tráfego de inferência para o contentor. (Se o recurso DeployedModel for dimensionado para usar vários nós de inferência, o Vertex AI encaminha os pedidos de inferência para outros contentores em bom estado.)

O Vertex AI não reinicia o contentor. Em vez disso, a sonda de verificação do estado de funcionamento continua a enviar pedidos de verificação do estado de funcionamento intermitentes para o servidor em mau estado. Se receber uma resposta saudável, marca esse contentor como saudável e começa novamente a encaminhar o tráfego de inferência para o mesmo.

Orientações práticas

Em alguns casos, é suficiente que o servidor HTTP no seu contentor responda sempre com o código de estado 200 OK às verificações de estado. Se o contentor carregar recursos antes de iniciar o servidor, o contentor não está em bom estado durante o período de arranque e durante os períodos em que o servidor HTTP falha. Em todos os outros momentos, responde como saudável.

Para uma configuração mais sofisticada, pode querer conceber intencionalmente o servidor HTTP para responder às verificações de estado com um estado não saudável em determinados momentos. Por exemplo, pode querer bloquear o tráfego de inferência para um nó durante um período para que o contentor possa realizar a manutenção.

Pedidos de inferência

Existem dois padrões para configurar rotas para o servidor de modelos. Um definido pela Vertex AI (/predict) e outro que permite a personalização total para que possa simplesmente adicionar o servidor de modelos da sua escolha (/invoke).

Rota /predict definida pelo Vertex

Quando um cliente envia um pedido projects.locations.endpoints.predict para a API Vertex AI, o Vertex AI encaminha este pedido como um pedido HTTP POST para um caminho de inferência configurável no seu servidor. Especifique este caminho no campo containerSpec.predictRoute quando criar um Model. Para saber como o contentor pode aceder a este valor, leia a secção deste documento sobre a variável de ambiente AIP_PREDICT_ROUTE.

Requisitos de solicitação

Se o modelo for implementado num ponto final público partilhado, cada pedido de inferência tem de ter um tamanho igual ou inferior a 1,5 MB. O servidor HTTP tem de aceitar pedidos de inferência que tenham o cabeçalho HTTP Content-Type: application/json e corpos JSON com o seguinte formato:

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

Nestas solicitações:

  • INSTANCES é uma matriz de um ou mais valores JSON de qualquer tipo. Cada valor representa uma instância para a qual está a fornecer uma inferência.

  • PARAMETERS é um objeto JSON que contém todos os parâmetros que o seu contentor requer para ajudar a publicar inferências nas instâncias. O Vertex AI considera o campo parameters opcional, pelo que pode conceber o seu contentor para o exigir, usá-lo apenas quando fornecido ou ignorá-lo.

Saiba mais acerca dos requisitos do corpo do pedido.

Requisitos de resposta

Se o modelo for implementado num ponto final público partilhado, cada resposta de inferência tem de ter 1,5 MB ou menos. O servidor HTTP tem de enviar respostas com corpos JSON que cumpram o seguinte formato:

{
  "predictions": INFERENCES
}

Nestas respostas, substitua INFERENCES por uma matriz de valores JSON que representam as inferências que o seu contentor gerou para cada um dos INSTANCES no pedido correspondente.

Depois de o servidor HTTP enviar esta resposta, o Vertex AI adiciona um campo deployedModelId à resposta antes de a devolver ao cliente. Este campo especifica que DeployedModel num Endpoint está a enviar a resposta. Saiba mais sobre o formato do corpo da resposta.

Rotas de inferência personalizadas

Se o servidor do modelo implementar várias rotas de inferência, é recomendável usar a API invoke para aceder a várias rotas de inferência. A API Invoke pode ser ativada durante o carregamento do modelo definindo o campo Model.containerSpec.invokeRoutePrefix como "/*". Após a implementação, um pedido HTTP para a rota /invoke/foo/bar é encaminhado como /foo/bar para o caminho do servidor do modelo. Para saber os detalhes, leia o artigo Usar rotas personalizadas arbitrárias.

Requisitos de publicação de imagens de contentores

Tem de enviar a imagem do contentor para o Artifact Registry para a usar com o Vertex AI. Saiba como enviar uma imagem de contentor para o Artifact Registry.

Em particular, tem de enviar a imagem do contentor para um repositório que cumpra os seguintes requisitos de localização e autorizações.

Localização

Quando usa o Artifact Registry, o repositório tem de usar uma região que corresponda ao ponto final de localização onde planeia criar um Model. Por exemplo, se planear criar um Model no ponto final us-central1-aiplatform.googleapis.com, o nome completo da imagem do contentor tem de começar por us-central1-docker.pkg.dev/. Não use um repositório multirregional para a sua imagem de contentor.

Autorizações

O Vertex AI tem de ter autorização para extrair a imagem do contentor quando cria um Model. Especificamente, o agente do serviço do Vertex AI para o seu projeto tem de ter as autorizações da função de leitor do Artifact Registry (roles/artifactregistry.reader) para o repositório da imagem do contentor.

O Vertex AI usa o agente de serviço do Vertex AI para o seu projeto interagir com outros Google Cloud serviços. Esta conta de serviço tem o endereço de email service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, em que PROJECT_NUMBER é substituído pelo número do projeto do Vertex AI.

Se tiver enviado a imagem do contentor para o mesmo Google Cloud projeto onde está a usar o Vertex AI, não tem de configurar nenhuma autorização. As autorizações predefinidas concedidas ao agente de serviço da Vertex AI são suficientes.

Por outro lado, se tiver enviado a imagem do contentor para umGoogle Cloud projeto diferente daquele em que está a usar o Vertex AI, tem de conceder a função de leitor do Artifact Registry para o repositório do Artifact Registry ao agente de serviço do Vertex AI.

Aceda a artefactos de modelos

Quando cria um Model com preparação personalizada sem um contentor personalizado, tem de especificar o URI de um diretório do Cloud Storage com artefactos do modelo como o campo artifactUri. Quando cria um Model com um contentor personalizado, o fornecimento de artefactos do modelo no Cloud Storage é opcional.

Se a imagem do contentor incluir os artefactos do modelo de que precisa para publicar inferências, não tem de carregar ficheiros do Cloud Storage. No entanto, se fornecer artefactos do modelo especificando o campo artifactUri, o contentor tem de carregar estes artefactos quando começar a ser executado. Quando o Vertex AI inicia o contentor, define a variável de ambiente AIP_STORAGE_URI para um URI do Cloud Storage que começa por gs://. A instrução ENTRYPOINT do seu contentor pode transferir o diretório especificado por este URI para aceder aos artefactos do modelo.

Tenha em atenção que o valor da variável de ambiente AIP_STORAGE_URI não é idêntico ao URI do Google Cloud Storage que especifica no campo artifactUri quando cria o Model. Em vez disso, o elemento AIP_STORAGE_URI aponta para uma cópia do diretório de artefactos do modelo num contentor do Cloud Storage diferente, que o Vertex AI gere. O Vertex AI preenche este diretório quando cria um Model. Não pode atualizar o conteúdo do diretório. Se quiser usar novos artefactos do modelo, tem de criar um novo Model.

A conta de serviço que o seu contentor usa por predefinição tem autorização para ler a partir deste URI.

Por outro lado, se especificar uma conta de serviço personalizada quando implementar o Model num Endpoint, o Vertex AI concede automaticamente à conta de serviço especificada a função Leitor de objetos de armazenamento (roles/storage.objectViewer) para o contentor do Cloud Storage dos URI.

Use qualquer biblioteca que suporte credenciais predefinidas da aplicação (ADC) para carregar os artefactos do modelo. Não precisa de configurar explicitamente a autenticação.

Variáveis de ambiente disponíveis no contentor

Quando executada, a instrução ENTRYPOINT do contentor pode referenciar variáveis de ambiente que configurou manualmente, bem como variáveis de ambiente definidas automaticamente pelo Vertex AI. Esta secção descreve cada forma de definir variáveis de ambiente e fornece detalhes sobre as variáveis definidas automaticamente pelo Vertex AI.

Variáveis definidas na imagem do contentor

Para definir variáveis de ambiente na imagem do contentor quando a cria, use a instrução ENV do Docker. Não defina variáveis de ambiente que comecem com o prefixo AIP_.

A instrução ENTRYPOINT do contentor pode usar estas variáveis de ambiente, mas não pode fazer referência a elas em nenhum dos campos da API Model.

Variáveis definidas pelo Vertex AI

Quando a Vertex AI começa a executar o contentor, define as seguintes variáveis de ambiente no ambiente do contentor. Cada variável começa com o prefixo AIP_. Não defina manualmente nenhuma variável de ambiente que use este prefixo.

A instrução ENTRYPOINT do contentor pode aceder a estas variáveis. Para saber que campos da API Vertex AI também podem fazer referência a estas variáveis, leia a referência da API para ModelContainerSpec.

Nome da variável Valor predefinido Como configurar o valor Detalhes
AIP_ACCELERATOR_TYPE Não definido Quando implementa um Model como um DeployedModel num recurso Endpoint, defina o campo dedicatedResources.machineSpec.acceleratorType. Se aplicável, esta variável especifica o tipo de acelerador usado pela instância de máquina virtual (VM) em que o contentor está a ser executado.
AIP_DEPLOYED_MODEL_ID Uma string de dígitos que identifica o DeployedModel para o qual o Model deste contentor foi implementado. Não configurável Este valor é o campo id de DeployedModel.
AIP_ENDPOINT_ID Uma string de dígitos que identifica o Endpoint no qual o Model do contentor foi implementado. Não configurável Este valor é o último segmento do campo Endpointname (após 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.		 Quando cria um Model, defina o campo containerSpec.healthRoute. Esta variável especifica o caminho HTTP no contentor para o qual a Vertex AI envia verificações de estado.
AIP_HTTP_PORT 8080 Quando cria um Model, defina o campo containerSpec.ports. A primeira entrada neste campo torna-se o valor de AIP_HTTP_PORT. O Vertex AI envia verificações de atividade, verificações de estado e pedidos de inferência para esta porta no contentor. O servidor HTTP do seu contentor tem de escutar pedidos nesta porta.
AIP_MACHINE_TYPE Nenhuma predefinição, tem de ser configurado Quando implementa um Model como um DeployedModel num recurso Endpoint, defina o campo dedicatedResources.machineSpec.machineType. Esta variável especifica o tipo de VM em que o contentor está a ser executado.
AIP_MODE PREDICTION Não configurável Esta variável significa que o contentor está a ser executado no Vertex AI para publicar inferências online. Pode usar esta variável de ambiente para adicionar lógica personalizada ao seu contentor, para que possa ser executada em vários ambientes de computação, mas apenas usar determinados caminhos de código quando executada no Vertex AI.
AIP_MODE_VERSION 1.0.0 Não configurável Esta variável indica a versão dos requisitos do contentor personalizado (este documento) que o Vertex AI espera que o contentor cumpra. Este documento é atualizado de acordo com a versão semântica.
AIP_MODEL_NAME O valor da variável AIP_ENDPOINT_ID Não configurável Consulte a linha AIP_ENDPOINT_ID. Esta 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.		 Quando cria um Model, defina o campo containerSpec.predictRoute. Esta variável especifica o caminho HTTP no contentor para o qual o Vertex AI encaminha os pedidos de inferência.
AIP_PROJECT_NUMBER O número do projeto do Google Cloud projeto onde está a usar o Vertex AI Não configurável
AIP_STORAGE_URI Não configurável Esta variável especifica o diretório que contém uma cópia dos artefactos do modelo, se aplicável.
AIP_VERSION_NAME O valor da variável AIP_DEPLOYED_MODEL_ID Não configurável Consulte a linha AIP_DEPLOYED_MODEL_ID. Esta variável existe por motivos de compatibilidade.

Variáveis definidas no recurso Model

Quando cria um Model, pode definir variáveis de ambiente adicionais no campo containerSpec.env.

A instrução ENTRYPOINT do contentor pode aceder a estas variáveis. Para saber que campos da API Vertex AI também podem fazer referência a estas variáveis, leia a referência da API para ModelContainerSpec.

O que se segue?