Requisitos de contêiner personalizado

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 status 503 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
  • Se você não definir o campo deploymentUri ao criar uma versão de modelo: uma string vazia.
  • Se você definir o campo deploymentUri ao criar uma versão de modelo: um URI do Cloud Storage (começando com gs://) que especifica um diretório em um bucket gerenciado pelo AI Platform Prediction.
 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