Se quiser usar um contêiner personalizado para exibir previsões, é necessário fornecer ao AI Platform Prediction 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 o AI Platform Prediction. Neste documento, também descrevemos como o AI Platform Prediction 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 para usar com o AI Platform Prediction.
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 KFServing Server.
Como 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, é possível especificar os campos containerSpec.command
e containerSpec.args
ao criar a versão do modelo para modificar, respectivamente,
os códigos ENTRYPOINT
e CMD
da imagem de contêiner. 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 uma versão de modelo, 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
O AI Platform Prediction realiza uma verificação de atividade quando o contêiner é iniciado para garantir que o servidor esteja em execução. Durante o processo de criação da versão, o AI Platform Prediction usa uma sondagem de atividade TCP para tentar estabelecer uma conexão TCP com seu 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, o AI Platform Prediction 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
O AI Platform Prediction executa de maneira intermitente as verificações de integridade no servidor HTTP
durante a execução a fim de 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 esse caminho no campo
routes.health
ao criar
uma versão de modelo. 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 com o código de status
200 OK
. O conteúdo do corpo da resposta não importa, porque ele será ignorado pelo AI Platform Prediction.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 nem com qualquer código de status, exceto
200 OK
. Por exemplo, responda com o código de status503 Service Unavailable
.Essa resposta significa que o servidor não está íntegro.
Se a sondagem de integridade receber uma resposta não íntegra do servidor, ela enviará até 3 verificações de integridade extras em intervalos de 10 segundos. Durante esse período, o AI Platform Prediction ainda considerará 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, o AI Platform Prediction interromperá o roteamento do tráfego de previsão para o contêiner. Se a versão do modelo for escalonada para usar vários nós de previsão, o AI Platform Prediction encaminhará as solicitações de previsão a outros contêineres íntegros.
O AI Platform Prediction 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
Digamos que um cliente envie uma solicitação projects.predict
ao AI Platform Training e à API Prediction. O AI Platform Prediction encaminhará essa solicitação como uma
solicitação HTTP POST
a uma previsão configurável no seu servidor. Especifique
esse caminho no campo
routes.predict
ao criar uma versão de modelo. 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
.
O AI Platform Prediction não valida solicitações e respostas de previsão, mas transmite cada solicitação de previsão inalterada para o servidor HTTP no contêiner, além de transmitir as respostas do servidor de volta para o cliente.
Cada solicitação e resposta de previsão precisa ter 1,5 MB ou menos. No entanto, você não precisa atender aos outros requisitos de corpos de solicitação e de corpos de resposta. Esses requisitos se aplicam somente a versões de modelo que não usam um contêiner personalizado. Quando você usa um contêiner personalizado, os corpos de solicitação e resposta podem assumir qualquer forma.
Porém, ainda recomendamos que você crie seu servidor HTTP de acordo com os requisitos de solicitação e resposta descritos nos links anteriores. Caso contrário, não há garantia de que outros recursos do AI Platform Prediction, como geração de registros, monitoramento e AI Explanations, funcionarão adequadamente.
Requisitos de publicação de imagens de contêiner
É preciso enviar a imagem do contêiner ao Artifact Registry para usá-la com o AI Platform Prediction. 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.
Location
O repositório precisa usar uma
região que corresponda ao
endpoint regional em que você planeja criar uma
versão de modelo. Por exemplo, se você planeja criar uma versão de modelo no
endpoint us-central1-ml.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 como imagem de contêiner.
Permissões
O AI Platform Prediction precisa ter permissão para receber a imagem do contêiner quando você
cria uma versão de modelo. Especificamente, o agente de serviço do AI Platform precisa ter as
permissões necessárias do papel de leitor do Artifact Registry
(roles/artifactregistry.reader
)
para o repositório da imagem do contêiner.
Se você tiver enviado a imagem do contêiner ao mesmo projeto do Google Cloud em que estiver usando o AI Platform Prediction, não será necessário configurar nenhuma permissão. As permissões padrão concedidas ao agente de serviço 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 o AI Platform Prediction, é necessário conceder o papel de leitor do Artifact Registry para o repositório do Artifact Registry ao Agente de serviço do AI Platform.
Como acessar artefatos de modelo
Ao criar uma versão de modelo sem um contêiner personalizado, especifique o URI de
um diretório do Cloud Storage com artefatos de
modelo como o campo
deploymentUri
. Ao criar
uma versão de modelo 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
deploymentUri
, o contêiner precisará carregar esses artefatos quando começar a ser executado.
Quando o AI Platform Prediction inicia o contêiner, ele 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.
O valor da variável de ambiente AIP_STORAGE_URI
não é idêntico
ao URI do Cloud Storage especificado no campo deploymentUri
quando você cria a versão de modelo. Em vez disso,
AIP_STORAGE_URI
aponta para uma cópia do diretório de artefatos de modelo em um
bucket diferente do Cloud Storage, gerenciado pelo AI Platform Prediction.
O AI Platform Prediction preenche esse diretório quando você cria uma versão de modelo.
Não é possível atualizar o conteúdo do diretório. Se você quiser usar novos artefatos de modelo,
crie uma nova versão de modelo.
A conta de serviço que seu contêiner usa por
padrão tem permissão
para ler esse URI. Por outro lado, imagine que você especifique uma conta de serviço
personalizada ao criar uma versão de modelo.
Nesse caso, o AI Platform Prediction automaticamente concederá à conta de serviço
especificada o papel de leitor de objetos do Storage
(roles/storage.objectViewer
) no 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.
Como o contêiner é compatível com o ADC para o agente de serviço do AI Platform ou uma conta de serviço personalizada, se você tiver especificado uma, ele também poderá acessar qualquer outro serviço do Google Cloud para o qual a conta de serviço tenha permissões.
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 pelo AI Platform Prediction. Nesta seção, descreveremos cada maneira de definir variáveis de ambiente e forneceremos detalhes sobre as variáveis definidas automaticamente pelo AI Platform Prediction.
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 entrypoint do contêiner pode usar essas variáveis de ambiente, mas não é possível referenciá-las em nenhum dos campos de API da versão de modelo.
Variáveis definidas pelo AI Platform Prediction
Quando o AI Platform Prediction começa a executar o contêiner, ele define as variáveis de ambiente
a seguir no ambiente de contêiner. Cada variável começa com
o prefixo AIP_
. Não faça a definição manual de nenhuma variável de ambiente que use
esse prefixo.
O comando de entrypoint do contêiner pode acessar essas variáveis. Para saber quais
campos do AI Platform Training e da API Prediction também podem referir-se a essas variáveis, leia a
referência da API de
ContainerSpec
.
Nome da variável | Valor padrão | Como configurar o valor | Detalhes |
---|---|---|---|
AIP_ACCELERATOR_TYPE | Cancelar configuração | Ao criar uma versão de modelo, defina o campo
acceleratorConfig.type . |
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_FRAMEWORK | CUSTOM_CONTAINER |
Não configurável | |
AIP_HEALTH_ROUTE | /v1/models/MODEL/versions/VERSION Nesta string, substitua MODEL pelo valor da variável AIP_MODEL_NAME e substitua VERSION pelo
valor da variável AIP_VERSION_NAME . |
Ao criar uma versão de modelo, defina o campo
routes.health . |
Essas variáveis especificam o caminho HTTP no contêiner que receberá verificações de integridade do AI Platform Prediction. |
AIP_HTTP_PORT | 8080 |
Ao criar uma versão de modelo, defina o campo
containerSpec.ports . A primeira entrada neste campo se torna o valor de
AIP_HTTP_PORT . |
O AI Platform Prediction envia verificações de atividade e 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 criar uma versão de modelo, defina o campo
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 no AI Platform Prediction para exibir previsões on-line. É possível usar essa variável de ambiente para adicionar uma lógica personalizada ao contêiner, de modo que ela possa ser executada em vários ambientes de computação, mas use somente caminhos de código específicos quando executada no AI Platform Prediction. |
AIP_MODE_VERSION | 1.0.0 |
Não configurável | Essa variável significa a versão dos requisitos do contêiner personalizado (este documento) que o AI Platform Prediction espera que sejam atendidos pelo contêiner. Este documento é atualizado de acordo com o controle de versões semântico. |
AIP_MODEL_NAME | Nenhum padrão. Precisa ser configurado. | Ao criar um modelo (o pai da versão de modelo que usa
o contêiner), especifique o campo
name . |
O valor não inclui o prefixo
projects/PROJECT_ID/models/ que o AI Platform Training
e a API Prediction produzem na saída. |
AIP_PREDICT_ROUTE | /v1/models/MODEL/versions/VERSION:predict Nesta string, substitua MODEL pelo valor da variável AIP_MODEL_NAME e substitua VERSION pelo
valor da variável AIP_VERSION_NAME . |
Ao criar uma versão de modelo, defina o campo
routes.predict . |
Essa variável especifica o caminho HTTP no contêiner que recebe solicitações de previsão do AI Platform Prediction. |
AIP_PROJECT_NUMBER | O número do projeto do Google Cloud em que você está usando o AI Platform Prediction. | Não configurável | |
AIP_STORAGE_URI |
|
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 | Nenhum padrão. Precisa ser configurado. | Ao criar uma versão de modelo, defina o campo
name . |
O valor não inclui o prefixo
projects/PROJECT_ID/models/MODEL/versions/
que o AI Platform Training e a API Prediction produzem na saída. |
Variáveis definidas no recurso "Version"
Ao criar uma versão de modelo, é possível definir mais variáveis de ambiente no
campo
container.env
.
O comando de entrypoint do contêiner pode acessar essas variáveis. Para saber quais
campos do AI Platform Training e da API Prediction também podem referir-se a essas variáveis, leia a
referência da API de
ContainerSpec
.
A seguir
- Saiba mais sobre a exibição de previsões com um contêiner personalizado.
- Para exibir previsões com um contêiner personalizado específico, leia o tutorial sobre como exibir previsões do PyTorch.