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 ENTRYPOINT
instrução, uma CMD
instruçã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 exec
comando
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 estado503 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 Endpoint name (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?
- Saiba como publicar inferências através de um contentor personalizado, incluindo como especificar campos da API relacionados com o contentor quando importa um modelo.