Como usar um contêiner personalizado

Para personalizar como o AI Platform Prediction exibe predições on-line com base no seu modelo treinado de machine learning (ML), é possível especificar um contêiner personalizado em vez de uma versão de ambiente de execução ao criar uma versão do modelo. Ao usar um contêiner personalizado, o AI Platform Prediction executa um contêiner do Docker de sua escolha em cada nó de previsão (em vez de executar o código da versão padrão do ambiente de execução) para exibir previsões de artefatos de modelo compatíveis.

Convém usar um contêiner personalizado por um dos seguintes motivos:

  • para exibir previsões de um modelo treinado de ML usando um framework diferente do TensorFlow, scikit-learn ou XGBoost;
  • para pré-processar solicitações de previsão ou pós-processar as previsões geradas pelo modelo;
  • para executar um servidor de previsão escrito em uma linguagem de programação de sua escolha;
  • para instalar as dependências que você quer usar para personalizar a previsão.

Neste guia, descrevemos como criar uma versão de modelo que usa um contêiner personalizado. Ele não apresenta instruções detalhadas sobre como projetar e criar uma imagem de contêiner do Docker. Para ver um exemplo de como criar uma imagem de contêiner e usá-la com o AI Platform Prediction, leia Primeiros passos: como exibir previsões do PyTorch com um contêiner personalizado.

Para usar um contêiner personalizado, utilize um endpoint regional e o tipo de máquina N1 do Compute Engine na versão do modelo.

Como preparar uma imagem de contêiner

Para criar uma versão de modelo que use um contêiner personalizado, forneça uma imagem de contêiner do Docker como base desse contêiner. Essa imagem de contêiner precisa atender aos requisitos descritos em Requisitos personalizados do contêiner.

Se você planeja usar uma imagem de contêiner atual criada por terceiros em quem confia, é possível pular uma ou as duas seções a seguir.

Crie uma imagem de contêiner

Projete e crie uma imagem de contêiner do Docker que atenda aos requisitos de imagem de contêiner.

Para aprender os princípios básicos de como projetar e criar uma imagem de contêiner do Docker, leia o guia de início rápido da documentação do Docker

Envie a imagem do contêiner para o Artifact Registry

Envie a imagem do contêiner para um repositório do Artifact Registry que atenda aos requisitos de publicação de imagem do contêiner.

Saiba como enviar uma imagem de contêiner para o Artifact Registry.

Como criar um modelo e uma versão de modelo

Especifique várias opções de configuração ao criar um modelo para garantir que qualquer versão que você criar posteriormente no modelo seja compatível com seu contêiner personalizado.

Em seguida, especifique a maior parte da configuração do contêiner ao criar uma versão do modelo.

Criar um modelo

Para criar um modelo, siga as instruções para criar um recurso de modelo. É preciso criar o modelo em um endpoint regional que corresponda à região do repositório do Artifact Registry em que a imagem do contêiner está armazenada. Para saber mais, leia os requisitos de publicação de imagens de contêiner.

Crie uma versão de modelo

Ao criar uma versão de modelo que usa um contêiner personalizado, configure os seguintes campos de API específicos de contêiner, além dos [outros campos especificados de uma versão de modelo]((/ai-platform/prediction/docs/deploying-models#create_a_model_version):

As seções a seguir descrevem como configurar esses campos.

Além disso, observe as seguintes diferenças específicas de contêiner em como você configura outros campos de API:

Configurar o Version.container

Você precisa especificar uma mensagem ContainerSpec no campo Version.container. Nessa mensagem, é possível especificar os subcampos a seguir. Se você usar o comando gcloud beta ai-platform versions create para criar a versão de modelo, será possível usar uma sinalização de linha de comando para especificar cada subcampo.

image (obrigatório)

O URI do Artifact Registry da imagem do seu contêiner.

Sinalização da ferramenta gcloud: --image

command (opcional)

Uma matriz de um executável e argumentos para substituir o ENTRYPOINT do contêiner. Para saber mais sobre como formatar este campo e como ele interage com o campo args, leia a referência da API sobre ContainerSpec.

Sinalização da ferramenta gcloud: --command

args (opcional)

Uma matriz de um executável e argumentos para modificar o CMD do contêiner. Para saber mais sobre como formatar este campo e como ele interage com o campo command, leia a referência da API para ContainerSpec.

Sinalização da ferramenta gcloud: --args

ports (opcional)

Uma matriz de portas: o AI Platform Prediction envia verificações de atividade e de integridade e solicitações de previsão ao seu contêiner na primeira porta listada ou 8080 por padrão. A especificação de portas extras não tem efeito.

Sinalização da ferramenta gcloud: --ports

env (opcional)

Uma matriz de variáveis de ambiente que o comando de entrypoint do contêiner e os campos command e args podem referenciar. Para saber mais sobre como outros campos podem referenciar essas variáveis de ambiente, leia a referência da API para ContainerSpec.

Sinalização da ferramenta gcloud: --env-vars

Além das variáveis definidas no campo Version.container.env, o AI Platform Prediction define várias outras variáveis com base na sua configuração. Saiba mais sobre como usar essas variáveis de ambiente nesses campos e no comando de entrypoint do contêiner.

O exemplo a seguir mostra como especificar esses campos ao criar uma versão de modelo usando a ferramenta de linha de comando gcloud:

gcloud beta ai-platform versions create VERSION \
  --region=REGION \
  --model=MODEL \
  --machine-type=n1-standard-4 \
  --image=IMAGE_URI \
  --command=executable,param1,param2 \
  --args=param3,param4 \
  --ports=8081 \
  --env-vars \
    VAR1='value 1' \
    VAR2='value 2'

Substitua:

Configurar o Version.routes

É possível especificar uma mensagem RouteMap no campo Version.routes. Nessa mensagem, é possível especificar os subcampos a seguir. Se você usar o comando gcloud beta ai-platform versions create para criar a versão de modelo, será possível usar uma sinalização de linha de comando para especificar cada subcampo.

health (opcional)

O caminho no servidor HTTP do contêiner em que o AI Platform Prediction enviará verificações de integridade.

Se você não especificar esse campo, o padrão será /v1/models/MODEL/versions/VERSION, em que MODEL e VERSION são substituídos pelos nomes do modelo e da versão do modelo, respectivamente.

Sinalização da ferramenta gcloud: --health-route

predict (opcional)

O caminho no servidor HTTP do contêiner em que você quer que o AI Platform Prediction encaminhe solicitações de previsão.

Se você não especificar esse campo, o padrão será /v1/models/MODEL/versions/VERSION:predict, em que MODEL e VERSION são substituídos pelos nomes do modelo e da versão do modelo, respectivamente.

Sinalização da ferramenta gcloud: --predict-route

O exemplo a seguir mostra como especificar esses campos ao criar uma versão de modelo com a ferramenta gcloud:

gcloud beta ai-platform versions create VERSION \
  --region=REGION \
  --model=MODEL \
  --machine-type=n1-standard-4 \
  --image=IMAGE_URI \
  --command=executable,param1,param2 \
  --args=param3,param4 \
  --ports=8081 \
  --env-vars \
    VAR1='value 1' \
    VAR2='value 2' \
  --health-route=/health \
  --predict-route=/predict

Substitua:

Como enviar solicitações de previsão

Para enviar uma solicitação de previsão on-line à versão do modelo, siga o guia da previsão on-line: esse processo funciona da mesma maneira, independentemente de você usar um contêiner personalizado.

No entanto, quando você usa um contêiner personalizado, o corpo de cada solicitação de previsão não precisa atender aos requisitos do corpo da solicitação das versões de modelo que usam uma versão de ambiente de execução. Por isso, recomendamos que você projete o contêiner para esperar corpos de solicitação com o formato padrão, se possível. Saiba mais sobre requisitos de solicitação e de resposta para contêineres personalizados.

A seguir