Primeiros passos: como exibir previsões do PyTorch com um contêiner personalizado

Neste tutorial, mostraremos como usar um contêiner personalizado para implantar um modelo de machine learning (ML) do PyTorch que exibe previsões on-line.

Neste tutorial, você implantará um contêiner que executa a ferramenta TorchServe do PyTorch para exibir previsões de um modelo de reconhecimento de dígitos fornecido pela TorchServe (links em inglês) que tenha sido pré-treinado no conjunto de dados MNIST. É possível usar o AI Platform Prediction para classificar imagens de dígitos.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the AI Platform Training & Prediction and Artifact Registry API APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the AI Platform Training & Prediction and Artifact Registry API APIs.

    Enable the APIs

    8.

  8. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Neste tutorial, recomendamos que você use o Cloud Shell para interagir com o Google Cloud. Se você quiser usar um shell Bash diferente em vez do Cloud Shell, execute a seguinte configuração extra:

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init
  3. Siga a documentação do Artifact Registry para instalar o Docker.

Como criar e enviar a imagem do contêiner

Para usar um contêiner personalizado, especifique uma imagem de contêiner do Docker que atenda aos requisitos de contêiner personalizado. Nesta seção, descrevemos como criar a imagem do contêiner e enviá-la para o Artifact Registry.

Faça o download dos artefatos de modelo

Os artefatos de modelo são arquivos criados pelo treinamento de ML que podem ser usados para exibir previsões. Eles contêm, no mínimo, a estrutura e os pesos do seu modelo de ML treinado. O formato dos artefatos de modelo depende do framework de ML usado para treinamento.

Neste tutorial, em vez de treinar do zero, faça o download dos artefatos de modelo de exemplo fornecidos pelo TorchServe.

Para clonar o repositório do TorchServe e navegar para o diretório com os artefatos de modelo, execute os seguintes comandos no shell:

git clone https://github.com/pytorch/serve.git \
  --branch=v0.3.0 \
  --depth=1

cd serve/examples/image_classifier/mnist

Esse diretório contém três arquivos importantes a serem criados na imagem do contêiner:

Crie um repositório do Artifact Registry

Crie um repositório do Artifact Registry para armazenar a imagem do contêiner que você criará na próxima seção. Execute o seguinte comando no seu shell:

gcloud beta artifacts repositories create getting-started-pytorch \
 --repository-format=docker \
 --location=REGION

Substitua REGION pela região em que você quer que o Artifact Registry armazene a imagem do contêiner. Depois, crie um recurso de modelo do AI Platform Prediction em um endpoint regional que corresponda a essa região. Portanto, escolha uma região em que o AI Platform Prediction tenha um endpoint regional, por exemplo, us-central1.

Depois de concluir a operação, este comando imprime a seguinte entrada:

Created repository [getting-started-pytorch].

Crie a imagem do contêiner

O TorchServe fornece um Dockerfile para a criação de uma imagem de contêiner que executa o TorchServe. No entanto, em vez de usar esse Dockerfile para instalar todas as dependências do TorchServe, é possível acelerar o processo de criação, derivando a imagem do contêiner de uma das imagens do TorchServe que a equipe do TorchServe enviou ao Docker Hub.

  1. No diretório com os artefatos de modelo, crie um novo Dockerfile. Basta executar o seguinte comando no shell:

    cat > Dockerfile <<END
FROM pytorch/torchserve:0.3.0-cpu

COPY mnist.py mnist_cnn.pt mnist_handler.py /home/model-server/

USER root
RUN printf "\nservice_envelope=json" >> /home/model-server/config.properties
USER model-server

RUN torch-model-archiver \
  --model-name=mnist \
  --version=1.0 \
  --model-file=/home/model-server/mnist.py \
  --serialized-file=/home/model-server/mnist_cnn.pt \
  --handler=/home/model-server/mnist_handler.py \
  --export-path=/home/model-server/model-store

CMD ["torchserve", \
     "--start", \
     "--ts-config=/home/model-server/config.properties", \
     "--models", \
     "mnist=mnist.mar"]
END

    Estas instruções do Docker realizam as seguintes ações:

    • A instrução FROM deriva a imagem do contêiner atual de uma imagem existente do TorchServe.

    • A instrução COPY copia os artefatos de modelo e o gerenciador de previsão do seu diretório local para o diretório /home/model-server/ da imagem do contêiner.

    • A primeira instrução RUN edita o arquivo de configuração da imagem mãe para aceitar o formato de entrada preferencial do AI Platform Prediction para previsões.

      Especificamente, esta instrução configura o TorchServe para esperar um ambiente de serviço JSON para solicitações de previsão.

      A edição deste arquivo de configuração requer a permissão que o usuário model-server (que foi criado na imagem pai) não tem. As instruções orientam o Docker a executar como usuário root para editar o arquivo de configuração e, em seguida, continuar usando o usuário model-server para as instruções a seguir.

    • A segunda instrução RUN usa o arquivo de modelos do Edge, que já está instalado na imagem do contêiner, para criar um arquivo de modelo com base nos arquivos copiados para a imagem. Esse arquivo de modelo é salvo no diretório /home/model-server/model-store/ com o nome de arquivo mnist.mar.

      Se você quiser alterar a imagem do contêiner (por exemplo, para executar um pré-processamento personalizado ou pós-processamento no gerenciador de solicitação), será possível usar outras instruções RUN para instalar dependências.

    • A instrução CMD inicia o servidor HTTP TorchServe. Ele faz referência ao arquivo de configuração da imagem pai e permite a exibição de um modelo chamado mnist. Esse modelo carrega o arquivo mnist.mar criado pela instrução RUN.

      Essa instrução modifica a instrução CMD da imagem pai. É importante modificar a instrução CMD e não a instrução ENTRYPOINT, porque o script ENTRYPOINT da imagem pai executa o comando transmitido em CMD, além de adicionar lógica extra para impedir a saída do Docker.

  2. Para criar a imagem do contêiner com base no seu novo Dockerfile e marcá-lo com um nome compatível com seu repositório do Artifact Registry, execute o seguinte comando no shell:

    docker build \
  --tag=REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist \
  .

    Substitua:

    • REGION: a região do repositório do Artifact Registry, conforme especificado em uma seção anterior.
    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    O comando pode ser executado por vários minutos.

Execute o contêiner localmente (opcional)

Antes de enviar a imagem do contêiner ao Artifact Registry para usá-la com o AI Platform Prediction, execute-a como um contêiner no ambiente local para verificar se o servidor funciona conforme o esperado:

  1. Para executar a imagem do contêiner como um contêiner localmente, execute o seguinte comando no shell:

    docker run -d -p 8080:8080 --name=local_mnist \
  REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist

    Faça o seguinte, como na seção anterior:

    • REGION: a região do repositório do Artifact Registry, conforme especificado em uma seção anterior.
    • PROJECT_ID: o ID do seu projeto do Google Cloud.

    Esse comando executa um contêiner no modo separado, mapeando a porta 8080 do contêiner para a porta 8080 do ambiente local. A imagem de base que originou a imagem do contêiner e configura o TorchServe para usar a porta 8080 (em inglês).

  2. Para enviar uma verificação de integridade ao servidor do contêiner, execute o seguinte comando no shell:

    curl localhost:8080/ping

    Se for bem-sucedido, o servidor retornará a seguinte resposta:

    {
  "status": "Healthy"
}

  3. Para enviar uma solicitação de predição ao servidor do contêiner, execute os seguintes comandos no shell:

    cat > instances.json <<END
{
  "instances": [
    {
      "data": {
        "b64": "$(base64 --wrap=0 test_data/3.png)"
      }
    }
  ]
}
END

curl -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @instances.json \
  localhost:8080/predictions/mnist

    Essa solicitação usa uma das imagens de teste incluídas no exemplo de TorchServe.

    Se for bem-sucedido, o servidor retornará a seguinte previsão:

    {"predictions": [3]}

  4. Para interromper o contêiner, execute o seguinte comando no shell:

    docker stop local_mnist

Envie a imagem do contêiner para o Artifact Registry

Configure o Docker para acessar o Artifact Registry. Em seguida, envie a imagem do contêiner para o repositório do Artifact Registry.

  1. Para conceder à instalação local do Docker permissão para transmitir ao Artifact Registry na região escolhida, execute o seguinte comando no shell:

    gcloud auth configure-docker REGION-docker.pkg.dev

    Substitua REGION pela região em que você criou o repositório em uma seção anterior.

  2. Para enviar a imagem de contêiner recém-criada ao Artifact Registry, execute o seguinte comando no shell:

    docker push REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist

    Faça o seguinte, como na seção anterior:

    • REGION: a região do repositório do Artifact Registry, conforme especificado em uma seção anterior.
    • PROJECT_ID: o ID do seu projeto do Google Cloud.

Como implantar o contêiner

Nesta seção, mostramos como criar um modelo e uma versão de modelo no AI Platform Prediction para exibir a previsão. A versão do modelo executa a imagem do contêiner como um contêiner para exibir previsões.

Neste tutorial, fornecemos opções de configuração específicas para usar na criação do modelo e da versão do modelo. Se você quiser saber mais sobre diferentes opções de configuração, leia Como implantar modelos.

Criar um modelo

Para criar um recurso de modelo, execute o seguinte comando no shell:

gcloud beta ai-platform models create getting_started_pytorch \
  --region=REGION \
  --enable-logging \
  --enable-console-logging

Substitua REGION pela mesma região em que você criou o repositório do Artifact Registry em uma seção anterior.

Crie uma versão de modelo

Para criar um recurso de versão de modelo, execute o seguinte comando no shell:

gcloud beta ai-platform versions create v1 \
  --region=REGION \
  --model=getting_started_pytorch \
  --machine-type=n1-standard-4 \
  --image=REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist \
  --ports=8080 \
  --health-route=/ping \
  --predict-route=/predictions/mnist

Substitua:

  • REGION: a região em que você criou o repositório do Artifact Registry e o modelo do AI Platform Prediction nas seções anteriores.
  • PROJECT_ID: o ID do seu projeto do Google Cloud.

As sinalizações relacionadas ao contêiner nesse comando fazem o seguinte:

Como receber uma previsão

Os arquivos de exemplo do TorchServe que você baixou em uma seção anterior incluem imagens de teste. A configuração do TorchServe do contêiner espera receber solicitações de previsão no formato JSON, com a imagem como uma string codificada em base64 no campo data.b64 de cada instância.

Por exemplo, para classificar test_data/3.png, execute os seguintes comandos no shell:

cat > instances.json <<END
{
 "instances": [
   {
     "data": {
       "b64": "$(base64 --wrap=0 test_data/3.png)"
     }
   }
 ]
}
END

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @instances.json \
  https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models/getting_started_pytorch/versions/v1:predict

Substitua:

  • REGION: a região em que você criou seu modelo do AI Platform Prediction como uma seção anterior.
  • PROJECT_ID: o ID do seu projeto do Google Cloud.

Se for bem-sucedida, a versão do modelo retornará a seguinte previsão:

{"predictions": [3]}

Limpeza

Para evitar mais cobranças do AI Platform Prediction e cobranças do Artifact Registry, exclua os recursos do Google Cloud criados durante este tutorial:

  1. Para excluir a versão do modelo, execute o seguinte comando no shell:

    gcloud ai-platform versions delete v1 \
  --region=REGION \
  --model=getting_started_pytorch \
  --quiet

    Substitua REGION pela região em que você criou o modelo em uma seção anterior.

  2. Para excluir o modelo, execute o seguinte comando no shell:

    gcloud ai-platform models delete getting_started_pytorch \
  --region=REGION \
  --quiet

    Substitua REGION pela região em que você criou o modelo em uma seção anterior.

  3. Para excluir o repositório do Artifact Registry e a imagem do contêiner nele, execute o seguinte comando no shell:

    gcloud beta artifacts repositories delete getting-started-pytorch \
  --location=REGION \
  --quiet

    Substitua REGION pela região em que você criou o repositório do Artifact Registry em uma seção anterior.

A seguir