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. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  4. Ative as APIs AI Platform Training & Prediction and Artifact Registry API.

    Ative as APIs

  5. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  7. Ative as APIs AI Platform Training & Prediction and Artifact Registry API.

    Ative as APIs

  8. No Console do Google Cloud, ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

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. Instale a CLI do Google Cloud.
  2. Para inicializar a CLI gcloud, execute o seguinte comando:

    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 pai 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]}

Limpar

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