Per iniziare: pubblicazione di previsioni PyTorch con un container personalizzato

Questo tutorial mostra come utilizzare un contenuto personalizzato contenuto personalizzato per eseguire il deployment di un modello di machine learning (ML) PyTorch che genera previsioni online.

In questo tutorial esegui il deployment di un contenitore che esegue lo strumento TorchServe di PyTorch per fornire le previsioni di un modello di riconoscimento di cifre fornito da TorchServe che è stato preaddestrato sul set di dati MNIST. Puoi quindi utilizzare AI Platform Prediction per classificare le immagini di cifre.

Prima di iniziare

  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.

Per tutto il tutorial, ti consigliamo di utilizzare Cloud Shell per interagire con Google Cloud. Se vuoi utilizzare una shell Bash diversa anziché Cloud Shell, esegui la seguente configurazione aggiuntiva:

  1. Install the Google Cloud CLI.

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

    gcloud init
  3. Segui la documentazione di Artifact Registry per installare Docker.

Creazione ed esecuzione del push dell'immagine container

Per utilizzare un container personalizzato, devi specificare un'immagine container Docker che soddisfi i requisiti dei container personalizzati. Questa sezione descrive come creare l'immagine del contenitore ed eseguirne il push su Artifact Registry.

Scaricare gli artefatti del modello

Gli elementi del modello sono file creati dall'addestramento ML che puoi utilizzare per fornire le previsioni. Contengono, come minimo, la struttura e i pesi del tuo modello di ML addestrato. Il formato degli elementi del modello dipende dal framework ML utilizzato per l'addestramento .

Per questo tutorial, anziché eseguire l'addestramento da zero, scarica gli elementi del modello di esempio forniti da TorchServe.

Per clonare il repository TorchServe e passare alla directory con gli elementi del modello, esegui i seguenti comandi nella shell:

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

cd serve/examples/image_classifier/mnist

Questa directory contiene tre file importanti da incorporare nell'immagine del contenitore:

  • mnist.py: definisce la struttura della rete neurale addestrata
  • mnist_cnn.pt: contiene un state_dict con i pesi delle funzionalità e altri output dell'addestramento
  • mnist_handler.py: espande il modo in cui TorchServe gestisce le richieste di previsione

Crea un repository Artifact Registry

Crea un repository Artifact Registry per archiviare l'immagine del contenitore che creerai nella sezione successiva. Esegui questo comando nella shell:

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

Sostituisci REGION con la regione in cui vuoi che Artifact Registry immagazzina l'immagine del contenitore. In un secondo momento, dovrai creare una risorsa modello di AI Platform Prediction su un endpoint regionale corrispondente a questa regione, quindi scegli una regione in cui AI Platform Prediction ha un endpoint regionale, ad esempio us-central1.

Al termine dell'operazione, questo comando stampa il seguente input:

Created repository [getting-started-pytorch].

Crea l'immagine container

TorchServe fornisce un Dockerfile per creare un'immagine container che esegue TorchServe. Tuttavia, invece di utilizzare questo Dockerfile per installare tutte le dipendenze di TorchServe, puoi velocizzare il processo di compilazione ricavando l'immagine container da una delle immagini TorchServe che il team di TorchServe ha caricato su Docker Hub.

  1. Nella directory con gli elementi del modello, crea un nuovo Dockerfile eseguendo il seguente comando nella 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

    Queste istruzioni Docker eseguono le seguenti azioni:

    • L'istruzione FROM ricava l'immagine container corrente da un'immagine TorchServe esistente.

    • L'istruzione COPY copia gli artefatti del modello e l'handler di previsione dalla tua directory locale nella directory /home/model-server/ dell'immagine container.

    • La prima istruzione RUN modifica il file di configurazione dell'immagine principale per supportare il formato di input preferito di AI Platform Prediction per le previsioni.

      Nello specifico, questa istruzione configura TorchServe in modo che aspetti un envelope service JSON per le richieste di previsione.

      La modifica di questo file di configurazione richiede l'autorizzazione che l'utentemodel-server (creato nell'immagine principale) non ha. Le istruzioni indicano a Docker di eseguire l'utente root per modificare il file di configurazione e poi continuare a utilizzare l'utente root per le istruzioni seguenti.model-server

    • La seconda istruzione RUN utilizza l'archiviatore di modelli Torch, già installato nell'immagine del contenitore, per creare un'archivio dei modelli dai file che hai copiato nell'immagine. Salva questo archiviazione del modello nella directory /home/model-server/model-store/ con il nome file mnist.mar.

      Se vuoi modificare l'immagine del contenitore, ad esempio per eseguire la preelaborazione o la post-elaborazione personalizzata nel gestore delle richieste, puoi utilizzare istruzioni RUN aggiuntive per installare le dipendenze.

    • L'istruzione CMD avvia il server HTTP TorchServe. Fa riferimento al file di configurazione dell'immagine principale e attiva la pubblicazione per un modello denominato mnist. Questo modello carica il file mnist.mar creato dall'istruzione RUN.

      Questa istruzione sostituisce l'istruzione CMD dell'immagine principale. È importante eseguire l'override dell'istruzione CMD e non dell'istruzione ENTRYPOINT, perché lo script ENTRYPOINT dell'immagine principale esegue il comando passato in CMD e aggiunge anche una logica aggiuntiva per impedire l'uscita di Docker.

  2. Per creare l'immagine container in base al nuovo Dockerfile e taggarla con un nome compatibile con il repository Artifact Registry, esegui il seguente comando nella shell:

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

    Sostituisci quanto segue:

    • REGION: la regione del repository Artifact Registry, come specificato in una sezione precedente
    • PROJECT_ID: l'ID del tuo progetto Google Cloud

    L'esecuzione del comando potrebbe richiedere diversi minuti.

(Facoltativo) Esegui il contenitore localmente

Prima di eseguire il push dell'immagine del contenitore in Artifact Registry per utilizzarla con AI Platform Prediction, puoi eseguirla come contenitore nel tuo ambiente locale per verificare che il server funzioni come previsto:

  1. Per eseguire l'immagine container come container in locale, esegui il seguente comando nella shell:

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

    Sostituisci quanto segue, come hai fatto nella sezione precedente:

    • REGION: la regione del repository Artifact Registry, come specificato in una sezione precedente
    • PROJECT_ID: l'ID del tuo progetto Google Cloud

    Questo comando esegue un container in modalità distinta, mappando la porta 8080 del container alla porta 8080 dell'ambiente locale. L'immagine principale, da cui hai dedotto l'immagine container, configura TorchServe per utilizzare la porta8080.

  2. Per inviare al server del contenitore un controllo di stato, esegui il seguente comando nella shell:

    curl localhost:8080/ping

    In caso di esito positivo, il server restituisce la seguente risposta:

    {
  "status": "Healthy"
}

  3. Per inviare al server del contenitore una richiesta di previsione, esegui i seguenti comandi nella 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

    Questa richiesta utilizza una delle immagini di test incluse nell'esempio TorchServe.

    In caso di esito positivo, il server restituisce la seguente previsione:

    {"predictions": [3]}

  4. Per interrompere il contenitore, esegui il seguente comando nella shell:

    docker stop local_mnist

Esegui il push dell'immagine del contenitore in Artifact Registry

Configura Docker per accedere ad Artifact Registry. Poi esegui il push dell'immagine container nel repository Artifact Registry.

  1. Per concedere all'installazione Docker locale l'autorizzazione per eseguire il push in Artifact Registry nella regione scelta, esegui il seguente comando nella shell:

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

    Sostituisci REGION con la regione in cui hai creato il repository in una sezione precedente.

  2. Per eseguire il push dell'immagine container appena creata in Artifact Registry, esegui il seguente comando nella shell:

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

    Sostituisci quanto segue, come hai fatto nella sezione precedente:

    • REGION: la regione del repository Artifact Registry, come specificato in una sezione precedente
    • PROJECT_ID: l'ID del tuo progetto Google Cloud

Deployment del container

Questa sezione illustra la creazione di un modello e di una versione del modello su AI Platform Prediction per eseguire la previsione. La versione del modello esegue l'immagine container come contenitore per fornire le previsioni.

Questo tutorial fornisce opzioni di configurazione specifiche da utilizzare quando crei il modello e la relativa versione. Per scoprire di più sulle diverse opzioni di configurazione, consulta Eseguire il deployment dei modelli.

crea un modello

Per creare una risorsa modello, esegui il seguente comando nella shell:

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

Sostituisci REGION con la stessa regione in cui hai creato il repository Artifact Registry in una sezione precedente.

Creare una versione del modello

Per creare una risorsa di versione del modello, esegui il seguente comando nella 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

Sostituisci quanto segue:

  • REGION: la regione in cui hai creato il repository Artifact Registry e il modello di AI Platform Prediction nelle sezioni precedenti
  • PROJECT_ID: l'ID del tuo progetto Google Cloud

I flag relativi ai container in questo comando eseguono le seguenti operazioni:

Ottenere una previsione

I file di esempio di TorchServe che hai scaricato in una sezione precedente includono immagini di test. La configurazione di TorchServe del contenitore si aspetta di ricevere richieste di previsione in formato JSON, con l'immagine come stringa codificata Base64 nel campo data.b64 di ogni istanza.

Ad esempio, per classificare test_data/3.png, esegui i seguenti comandi nella 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

Sostituisci quanto segue:

  • REGION: la regione in cui hai creato il modello di AI Platform Prediction in una sezione precedente
  • PROJECT_ID: l'ID del tuo progetto Google Cloud

In caso di esito positivo, la versione del modello restituisce la seguente previsione:

{"predictions": [3]}

Pulizia

Per evitare ulteriori addebiti di AI Platform Prediction e Artifact Registry, elimina le risorse Google Cloud che hai creato durante questo tutorial:

  1. Per eliminare la versione del modello, esegui il seguente comando nella shell:

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

    Sostituisci REGION con la regione in cui hai creato il modello in una sezione precedente.

  2. Per eliminare il modello, esegui il seguente comando nella shell:

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

    Sostituisci REGION con la regione in cui hai creato il modello in una sezione precedente.

  3. Per eliminare il repository Artifact Registry e l'immagine del contenitore al suo interno, esegui il seguente comando nella shell:

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

    Sostituisci REGION con la regione in cui hai creato il repository Artifact Registry in una sezione precedente.

Passaggi successivi