Deployment dei modelli

Questa pagina spiega come eseguire il deployment del modello in AI Platform Prediction per ottenere previsioni.

Per eseguire il deployment del modello addestrato su AI Platform Prediction, devi:

  • Carica il modello salvato in un bucket Cloud Storage.
  • Creare una risorsa del modello di previsione di AI Platform Prediction.
  • Creare una risorsa della versione di AI Platform Prediction, specificando il percorso Cloud Storage del modello salvato.

Prima di iniziare

Addestra il tuo modello di machine learning e segui la guida all'esportazione dei modelli per la previsione per creare artefatti del modello di cui eseguire il deployment in AI Platform Prediction.

Archivia il modello in Cloud Storage

In genere, è più semplice utilizzare un bucket Cloud Storage dedicato nello stesso progetto che utilizzi per AI Platform Prediction.

Se utilizzi un bucket in un altro progetto, devi assicurarti che l'account di servizio AI Platform Prediction possa accedere al modello in Cloud Storage. Senza le autorizzazioni appropriate, la richiesta di creazione di una versione del modelloAI Platform Predictionm non va a buon fine. Scopri di più su come concedere autorizzazioni per lo spazio di archiviazione.

Configura il bucket Cloud Storage

Questa sezione mostra come creare un nuovo bucket. Puoi utilizzare un bucket esistente, ma deve trovarsi nella stessa regione in cui prevedi di eseguire job AI Platform. Inoltre, se non fa parte del progetto che stai utilizzando per eseguire AI Platform Prediction, devi concedere esplicitamente l'accesso agli account di servizio AI Platform Prediction.

  1. Specifica un nome per il nuovo bucket. Il nome deve essere univoco in tutti i bucket in Cloud Storage.

    BUCKET_NAME="YOUR_BUCKET_NAME"

    Ad esempio, utilizza il nome del progetto con -aiplatform aggiunto:

    PROJECT_ID=$(gcloud config list project --format "value(core.project)")
    BUCKET_NAME=${PROJECT_ID}-aiplatform
  2. Controlla il nome del bucket che hai creato.

    echo $BUCKET_NAME
  3. Seleziona una regione per il bucket e imposta una variabile di ambiente REGION.

    Utilizza la stessa regione in cui prevedi di eseguire job di AI Platform Prediction. Consulta le regioni disponibili per i servizi di AI Platform Prediction.

    Ad esempio, il codice seguente crea REGION e lo imposta su us-central1:

    REGION=us-central1
  4. Crea il nuovo bucket:

    gsutil mb -l $REGION gs://$BUCKET_NAME

Carica il modello esportato in Cloud Storage

I seguenti esempi mostrano come caricare diversi tipi di artefatti del modello in una directory del modello in Cloud Storage:

SaveModel di TensorFlow

SAVED_MODEL_DIR=$(ls ./YOUR_EXPORT_DIR_BASE | tail -1)
gsutil cp -r $SAVED_MODEL_DIR gs://YOUR_BUCKET

Quando esporti un SaveModel da tf.keras o da uno strumento di stima di TensorFlow, viene salvato come sottodirectory con timestamp di una directory di esportazione di base di tua scelta, ad esempio YOUR_EXPORT_DIR_BASE/1487877383942. Questo esempio mostra come caricare la directory con il timestamp più recente. Se hai creato il SaveModel in un altro modo, potrebbe trovarsi in una posizione diversa nel tuo file system locale.

file del modello scikit-learn o XGBoost

A seconda di come hai esportato il modello addestrato, carica il file model.joblib, model.pkl o model.bst.

L'esempio seguente mostra come caricare un file esportato da sklearn.externals.joblib:

gsutil cp ./model.joblib gs://YOUR_BUCKET/model.joblib

L'esempio seguente mostra come caricare un file esportato dal modulo pickle di Python:

gsutil cp ./model.pkl gs://YOUR_BUCKET/model.pkl

L'esempio seguente mostra come caricare un file esportato con il metodo save_model di xgboost.Booster:

gsutil cp ./model.bst gs://YOUR_BUCKET/model.bst

Se esegui il deployment di una routine di previsione personalizzata (beta), carica anche eventuali altri artefatti del modello.

Le dimensioni totali del file della directory del modello devono essere pari o inferiori a 500 MB se utilizzi un tipo di macchina legacy (MLS1) o a 10 GB o meno se utilizzi un tipo di macchina di Compute Engine (N1). Scopri di più sui tipi di macchine per la previsione online.

Quando crei versioni successive del modello, organizzale posizionandole nella propria directory separata all'interno del bucket Cloud Storage.

Carica codice personalizzato

Se esegui il deployment di una pipeline scikit-learn con codice personalizzato o di una routine di previsione personalizzata, devi anche caricare il pacchetto di distribuzione di origine contenente il tuo codice personalizzato. Ad esempio:

gsutil cp dist/my_custom_code-0.1.tar.gz gs://YOUR_BUCKET/my_custom_code-0.1.tar.gz

Puoi caricare questo tarball nella stessa directory in Cloud Storage del file del modello, ma non è necessario. Infatti, tenerli separati può fornire una migliore organizzazione, soprattutto se esegui il deployment di molte versioni del tuo modello e del tuo codice.

Testa il modello con previsioni locali

Puoi utilizzare il comando gcloud ai-platform local predict per verificare in che modo il modello gestisce le previsioni prima di eseguirne il deployment su AI Platform Prediction. Il comando utilizza le dipendenze del tuo ambiente locale per eseguire previsioni e restituisce i risultati nello stesso formato utilizzato da gcloud ai-platform predict per eseguire previsioni online. Testare le previsioni in locale può aiutarti a individuare gli errori prima di incorrere in costi per le richieste di previsione online.

Per l'argomento --model-dir, specifica una directory contenente il modello di machine learning esportato sulla tua macchina locale o in Cloud Storage. Per l'argomento --framework, specifica tensorflow, scikit-learn o xgboost. Non puoi utilizzare il comando gcloud ai-platform local predict con una routine di previsione personalizzata.

L'esempio seguente mostra come eseguire una previsione locale:

gcloud ai-platform local predict --model-dir LOCAL_OR_CLOUD_STORAGE_PATH_TO_MODEL_DIRECTORY/ \
  --json-instances LOCAL_PATH_TO_PREDICTION_INPUT.JSON \
  --framework NAME_OF_FRAMEWORK

Esegui il deployment di modelli e versioni

AI Platform Prediction organizza i modelli addestrati utilizzando le risorse di model e model. Un modello di previsione di AI Platform è un container per le versioni del modello di machine learning.

Per eseguire il deployment di un modello, crea una risorsa del modello in AI Platform Prediction, crea una versione del modello e collega la versione del modello al file del modello archiviato in Cloud Storage.

Crea una risorsa del modello

AI Platform Prediction utilizza le risorse del modello per organizzare le diverse versioni del modello.

A questo punto, devi decidere se le versioni dei modelli appartenenti a questo modello devono utilizzare un endpoint a livello di regione o l'endpoint globale. Nella maggior parte dei casi, scegli un endpoint a livello di regione. Se hai bisogno di funzionalità disponibili solo nei tipi di macchine legacy (MLS1), utilizza l'endpoint globale.

A questo punto, devi anche decidere se le versioni del modello appartenenti a questo modello devono esportare i log quando forniscono previsioni. I seguenti esempi non abilitano il logging. Scopri come abilitare il logging.

console

  1. Apri la pagina Modelli di AI Platform Prediction nella console Google Cloud:

    Vai alla pagina Modelli

  2. Fai clic sul pulsante Nuovo modello nella parte superiore della pagina Modelli. Accederai alla pagina Crea modello.

  3. Inserisci un nome univoco per il modello nel campo Nome modello.

  4. Quando è selezionata la casella di controllo Utilizza endpoint a livello di regione, AI Platform Prediction utilizza un endpoint a livello di regione. Per utilizzare invece l'endpoint globale, deseleziona la casella di controllo Utilizza endpoint a livello di regione.

  5. Nell'elenco a discesa Regione, seleziona una località per i nodi di previsione. Le regioni disponibili variano a seconda che utilizzi un endpoint a livello di regione o un endpoint globale.

  6. Fai clic su Crea.

  7. Verifica di essere tornato alla pagina Modelli e che il nuovo modello venga visualizzato nell'elenco.

gcloud

Endpoint a livello di regione

Esegui questo comando:

gcloud ai-platform models create MODEL_NAME \
  --region=REGION

Sostituisci quanto segue:

Se non specifichi il flag --region, gcloud CLI ti chiede di selezionare un endpoint a livello di regione (o di utilizzare us-central sull'endpoint globale).

In alternativa, puoi impostare la proprietà ai_platform/region su una regione specifica per assicurarti che gcloud CLI utilizzi sempre l'endpoint a livello di regione corrispondente per AI Platform Prediction, anche quando non specifichi il flag --region. (Questa configurazione non si applica ai comandi nel gruppo di comandi gcloud ai-platform operations.)

Endpoint globale

Esegui questo comando:

gcloud ai-platform models create MODEL_NAME \
  --regions=REGION

Sostituisci quanto segue:

Se non specifichi il flag --regions, gcloud CLI ti chiede di selezionare un endpoint a livello di regione (o di utilizzare us-central1 sull'endpoint globale).

API REST

Endpoint a livello di regione

  1. Formatta la richiesta inserendo l'oggetto modello nel corpo della richiesta. Specifica almeno un nome per il modello sostituendo MODEL_NAME nell'esempio seguente:

    {
      "name": "MODEL_NAME"
    }
    
  2. Effettua una chiamata API REST all'URL seguente, sostituendo PROJECT_ID con l'ID progetto Google Cloud:

    POST https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models/
    

    Sostituisci quanto segue:

    Ad esempio, puoi effettuare la richiesta seguente utilizzando il comando curl. Questo comando autorizza la richiesta utilizzando le credenziali associate all'installazione di Google Cloud CLI.

    curl -X POST -H "Content-Type: application/json" \
      -d '{"name": "MODEL_NAME"}' \
      -H "Authorization: Bearer `gcloud auth print-access-token`" \
      "https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models"
    

    L'API restituisce una risposta simile alla seguente:

    {
      "name": "projects/PROJECT_ID/models/MODEL_NAME",
      "regions": [
        "REGION"
      ]
    }
    

Endpoint globale

  1. Formatta la richiesta inserendo l'oggetto modello nel corpo della richiesta. Come minimo, specifica un nome per il modello sostituendo MODEL_NAME nell'esempio seguente e specifica una regione sostituendo REGION con una regione che supporta i tipi di macchina legacy (MLS1):

    {
      "name": "MODEL_NAME",
      "regions": ["REGION"]
    }
    
  2. Effettua una chiamata API REST all'URL seguente, sostituendo PROJECT_ID con l'ID progetto Google Cloud:

    POST https://ml.googleapis.com/v1/projects/PROJECT_ID/models/
    

    Ad esempio, puoi effettuare la richiesta seguente utilizzando il comando curl. Questo comando autorizza la richiesta utilizzando le credenziali associate all'installazione di Google Cloud CLI.

    curl -X POST -H "Content-Type: application/json" \
      -d '{"name": "MODEL_NAME", "regions": ["REGION"]}' \
      -H "Authorization: Bearer `gcloud auth print-access-token`" \
      "https://ml.googleapis.com/v1/projects/PROJECT_ID/models"
    

    L'API restituisce una risposta simile alla seguente:

    {
      "name": "projects/PROJECT_ID/models/MODEL_NAME",
      "regions": [
        "REGION"
      ]
    }
    

Per ulteriori dettagli, consulta l'API del modello AI Platform Prediction.

Crea una versione del modello

Ora è tutto pronto per creare una versione del modello con il modello addestrato che hai caricato in precedenza su Cloud Storage. Quando crei una versione, puoi specificare un numero di parametri. Il seguente elenco descrive i parametri comuni, alcuni dei quali sono obbligatori:

  • name: deve essere univoco all'interno del modello di AI Platform Prediction.
  • deploymentUri: il percorso della directory del modello in Cloud Storage.

    • Se esegui il deployment di un modello TensorFlow, si tratta di una directory salvataModel.
    • Se esegui il deployment di un modello scikit-learn o XGBoost, questa è la directory contenente il file model.joblib, model.pkl o model.bst.
    • Se esegui il deployment di una routine di previsione personalizzata, questa è la directory che contiene tutti gli artefatti del modello. La dimensione totale di questa directory deve essere di 500 MB o inferiore.
  • framework: TENSORFLOW, SCIKIT_LEARN o XGBOOST. Ometti questo parametro se esegui il deployment di una routine di previsione personalizzata.

  • runtimeVersion: una versione di runtime basata sulle dipendenze necessarie al modello. Se esegui il deployment di un modello scikit-learn, un modello XGBoost o una routine di previsione personalizzata, il valore deve essere almeno 1, 4. Se prevedi di utilizzare la versione del modello per la previsione batch, devi utilizzare la versione 2.1 o precedente del runtime.

  • packageUris (facoltativo): un elenco di percorsi ai pacchetti di distribuzione del codice personalizzati (.tar.gz file) in Cloud Storage. Fornisci questo parametro solo se esegui il deployment di una pipeline scikit-learn con codice personalizzato (beta) o di una routine di previsione personalizzata (beta).

  • predictionClass (facoltativo): il nome della classe Predittore in formato module_name.class_name. Fornisci questo parametro solo se stai eseguendo il deployment di una routine di previsione personalizzata (beta).

  • serviceAccount (Facoltativo) Puoi specificare un account di servizio per la versione del modello da utilizzare se accede alle risorse Google Cloud durante l'elaborazione delle previsioni. Scopri di più su come specificare un account di servizio. Specifica questo parametro solo se utilizzi un container personalizzato o una routine di previsione personalizzata.

  • pythonVersion: deve essere impostato su "3.5" (per le versioni di runtime dalla 1.4 alla 1.14) o "3.7" (per le versioni del runtime 1.15 e successive) per essere compatibile con i file del modello esportati utilizzando Python 3. Può anche essere impostato su "2.7" se utilizzato con la versione 1.15 o precedente del runtime.

  • machineType (facoltativo): il tipo di macchina virtuale utilizzata da AI Platform Prediction per i nodi che forniscono le previsioni. Scopri di più sui tipi di macchine. Se non viene configurato, il valore predefinito è n1-standard-2 sugli endpoint a livello di regione e mls1-c1-m2 sull'endpoint globale.

Leggi ulteriori informazioni su ciascuno di questi parametri, nonché su altri parametri meno comuni, nella documentazione di riferimento API per la risorsa della versione.

Inoltre, se hai creato il modello su un endpoint a livello di regione, assicurati di creare anche la versione sullo stesso endpoint a livello di regione.

console

  1. Apri la pagina Modelli di AI Platform Prediction nella console Google Cloud:

    Vai alla pagina Modelli

  2. Nella pagina Modelli, seleziona il nome della risorsa del modello che vuoi utilizzare per creare la tua versione. Viene visualizzata la pagina Dettagli modello.

  3. Fai clic sul pulsante Nuova versione nella parte superiore della pagina Dettagli modello. Viene visualizzata la pagina Crea versione.

  4. Inserisci il nome della versione nel campo Nome. Se vuoi, inserisci una descrizione per la versione nel campo Descrizione.

  5. Inserisci le seguenti informazioni su come hai addestrato il modello nelle caselle a discesa corrispondenti:

  6. Seleziona un tipo di macchina per eseguire la previsione online.

  7. Nel campo URI del modello, inserisci la località del bucket Cloud Storage in cui hai caricato il file del modello. Puoi utilizzare il pulsante Sfoglia per trovare il percorso corretto.

    Assicurati di specificare il percorso della directory contenente il file, non il percorso del file del modello stesso. Ad esempio, utilizza gs://your_bucket_name/model-dir/ anziché gs://your_bucket_name/model-dir/saved_model.pb o gs://your_bucket_name/model-dir/model.pkl.

  8. Se esegui il deployment di una pipeline scikit-learn con codice personalizzato (beta) o di una routine di previsione personalizzata (beta), fornisci il percorso Cloud Storage a qualsiasi pacchetto di codice personalizzato (.tar.gz) in Codice personalizzato e dipendenze. Se esegui il deployment di una routine di previsione personalizzata, inserisci il nome della classe Predictor nel campo Classe di previsione.

  9. Seleziona un'opzione di Scalabilità per l'implementazione della previsione online:

    • Se selezioni "Scalabilità automatica", viene visualizzato il campo facoltativo Numero minimo di nodi. Puoi inserire il numero minimo di nodi da mantenere in esecuzione sempre dopo lo scale down del servizio.

    • Se selezioni "Scalabilità manuale", devi inserire il numero di nodi che vuoi mantenere sempre in esecuzione.

    Scopri come le opzioni di scalabilità variano in base al tipo di macchina.

    Scopri di più sui prezzi dei costi di previsione.

  10. Per completare la creazione della versione del modello, fai clic su Salva.

gcloud

  1. Imposta le variabili di ambiente per archiviare il percorso della directory Cloud Storage in cui si trova il programma binario del modello, il nome del modello, il nome della versione e il framework scelto.

    Quando crei una versione con gcloud CLI, puoi fornire il nome del framework in lettere maiuscole con trattini bassi (ad esempio SCIKIT_LEARN) o in lettere minuscole con trattini (ad esempio scikit-learn). Entrambe le opzioni portano a un comportamento identico.

    Sostituisci [VALUES_IN_BRACKETS] con i valori appropriati:

    MODEL_DIR="gs://your_bucket_name/"
    VERSION_NAME="[YOUR-VERSION-NAME]"
    MODEL_NAME="[YOUR-MODEL-NAME]"
    FRAMEWORK="[YOUR-FRAMEWORK_NAME]"
    

    Per una pipeline scikit-learn con codice personalizzato (beta), imposta una variabile aggiuntiva con il percorso del tarball di codice personalizzato:

    MODEL_DIR="gs://your_bucket_name/"
    VERSION_NAME="[YOUR-VERSION-NAME]"
    MODEL_NAME="[YOUR-MODEL-NAME]"
    FRAMEWORK="scikit-learn"
    CUSTOM_CODE_PATH="gs://your_bucket_name/my_custom_code-0.1.tar.gz"
    

    Per una routine di previsione personalizzata (beta), ometti la variabile FRAMEWORK e imposta variabili aggiuntive con il percorso del tarball di codice personalizzato e il nome della classe del predittore:

    MODEL_DIR="gs://your_bucket_name/"
    VERSION_NAME="[YOUR-VERSION-NAME]"
    MODEL_NAME="[YOUR-MODEL-NAME]"
    CUSTOM_CODE_PATH="gs://your_bucket_name/my_custom_code-0.1.tar.gz"
    PREDICTOR_CLASS="[MODULE_NAME].[CLASS_NAME]"
    
  2. Crea la versione:

    gcloud ai-platform versions create $VERSION_NAME \
      --model=$MODEL_NAME \
      --origin=$MODEL_DIR \
      --runtime-version=2.11 \
      --framework=$FRAMEWORK \
      --python-version=3.7 \
      --region=REGION \
      --machine-type=MACHINE_TYPE
    

    Sostituisci quanto segue:

    Per una pipeline scikit-learn con codice personalizzato (beta), utilizza il componente gcloud beta e assicurati di impostare il flag --package-uris. Per eseguire il deployment di codice personalizzato, il modello deve utilizzare l'endpoint globale.

    gcloud components install beta
    
    gcloud beta ai-platform versions create $VERSION_NAME \
      --model=$MODEL_NAME \
      --origin=$MODEL_DIR \
      --runtime-version=2.11 \
      --framework=$FRAMEWORK \
      --python-version=3.7 \
      --machine-type=mls1-c1-m2 \
      --package-uris=$CUSTOM_CODE_PATH
    

    Per una routine di previsione personalizzata (beta), utilizza il componente gcloud beta, ometti il flag --framework e imposta i flag --package-uris e --prediction-class. Per eseguire il deployment di codice personalizzato, il modello deve usare l'endpoint globale.

    gcloud components install beta
    
    gcloud beta ai-platform versions create $VERSION_NAME \
      --model=$MODEL_NAME \
      --origin=$MODEL_DIR \
      --runtime-version=2.11 \
      --python-version=3.7 \
      --machine-type=mls1-c1-m2 \
      --package-uris=$CUSTOM_CODE_PATH \
      --prediction-class=$PREDICTOR_CLASS
    

    La creazione della versione richiede alcuni minuti. Quando è pronto, dovresti vedere il seguente output:

    Creating version (this might take a few minutes)......done.
  3. Ottieni informazioni sulla tua nuova versione:

    gcloud ai-platform versions describe $VERSION_NAME \
      --model=$MODEL_NAME
    

    Dovresti vedere un output simile al seguente:

    createTime: '2018-02-28T16:30:45Z'
    deploymentUri: gs://your_bucket_name
    framework: [YOUR-FRAMEWORK-NAME]
    machineType: mls1-c1-m2
    name: projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions/[YOUR-VERSION-NAME]
    pythonVersion: '3.7'
    runtimeVersion: '2.11'
    state: READY

API REST

  1. Formatta il corpo della richiesta in modo che contenga l'oggetto versione. Questo esempio specifica le versioni name, deploymentUri, runtimeVersion, framework e machineType. Sostituisci [VALUES_IN_BRACKETS] con i valori appropriati:

    {
      "name": "[YOUR-VERSION-NAME]",
      "deploymentUri": "gs://your_bucket_name/",
      "runtimeVersion": "2.11",
      "framework": "[YOUR_FRAMEWORK_NAME]",
      "pythonVersion": "3.7",
      "machineType": "[YOUR_MACHINE_TYPE]"
    }
    
  2. Effettua la chiamata API REST al percorso seguente, sostituendo [VALUES_IN_BRACKETS] con i valori appropriati:

    POST https://REGION-ml.googleapis.com/v1/projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions
    

    Sostituisci REGION con la regione dell'endpoint a livello di regione in cui hai creato il modello. Se hai creato il modello sull'endpoint globale, utilizza ml.googleapis.com.

    Ad esempio, puoi effettuare la richiesta seguente utilizzando il comando curl:

    curl -X POST -H "Content-Type: application/json" \
      -d '{"name": "[YOUR-VERSION-NAME]", "deploymentUri": "gs://your_bucket_name/", "runtimeVersion": "2.11", "framework": "[YOUR_FRAMEWORK_NAME]", "pythonVersion": "3.7", "machineType": "[YOUR_MACHINE_TYPE]"}' \
      -H "Authorization: Bearer `gcloud auth print-access-token`" \
      "https://REGION-ml.googleapis.com/v1/projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions"
    

    La creazione della versione richiede alcuni minuti. Quando è pronto, dovresti vedere un output simile a questo:

    {
      "name": "projects/[YOUR-PROJECT-ID]/operations/create_[YOUR-MODEL-NAME]_[YOUR-VERSION-NAME]-[TIMESTAMP]",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.ml.v1.OperationMetadata",
        "createTime": "2018-07-07T02:51:50Z",
        "operationType": "CREATE_VERSION",
        "modelName": "projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]",
        "version": {
          "name": "projects/[YOUR-PROJECT-ID]/models/[YOUR-MODEL-NAME]/versions/[YOUR-VERSION-NAME]",
          "deploymentUri": "gs://your_bucket_name",
          "createTime": "2018-07-07T02:51:49Z",
          "runtimeVersion": "2.11",
          "framework": "[YOUR_FRAMEWORK_NAME]",
          "machineType": "[YOUR_MACHINE_TYPE]",
          "pythonVersion": "3.7"
        }
      }
    }