Deployment dei modelli

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

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

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

Prima di iniziare

Addestra il modello di machine learning e segui la guida all'esportazione dei modelli per la previsione per creare elementi del modello che possono essere di cui è stato eseguito il deployment in AI Platform Prediction.

Memorizza 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 il tuo account di servizio AI Platform Prediction possa accedere al tuo modello in Cloud Storage. Senza le autorizzazioni appropriate, la richiesta di creazione di una versione del modello di AI Platform Prediction non va a buon fine. Scopri di più sulla concessione delle autorizzazioni per lo spazio di archiviazione.

Configura il bucket Cloud Storage

Questa sezione spiega come creare un nuovo bucket. Puoi utilizzare un bucket esistente, ma deve trovarsi nella stessa regione in cui prevedi di eseguire i job di AI Platform. Inoltre, se non fa parte del progetto che utilizzi per eseguire AI Platform Prediction, devi esplicitamente concedere 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 di 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 i job di AI Platform Prediction. Consulta le regioni disponibili per i servizi AI Platform Prediction.

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

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

    gcloud storage buckets create gs://$BUCKET_NAME --location=$REGION

Carica il modello esportato in Cloud Storage

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

SavedModel di TensorFlow

SAVED_MODEL_DIR=$(ls ./YOUR_EXPORT_DIR_BASE | tail -1)
gcloud storage cp $SAVED_MODEL_DIR gs://YOUR_BUCKET --recursive

Quando esporti un modello SavedModel da tf.keras o da un estimatore di TensorFlow, viene salvato come sottodirectory con timestamp di una directory di esportazione di base che scegli, ad esempio YOUR_EXPORT_DIR_BASE/1487877383942. Questo esempio mostra come caricare la directory con il timestamp più recente. Se hai creato il tuo SavedModel in un altro modo, potrebbe trovarsi in una posizione diversa sul 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:

gcloud storage cp ./model.joblib gs://YOUR_BUCKET/model.joblib

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

gcloud storage cp ./model.pkl gs://YOUR_BUCKET/model.pkl

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

gcloud storage cp ./model.bst gs://YOUR_BUCKET/model.bst

Se stai implementando una routine di previsione personalizzata (beta), carica anche gli eventuali altri elementi del modello nella directory del modello.

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

Quando crei le versioni successive del modello, organizzale inserendo ciascuna in una directory separata all'interno del bucket Cloud Storage.

Carica codice personalizzato

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

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

Puoi caricare questo file tar nella stessa directory di Cloud Storage del file del modello, ma non è obbligatorio. In effetti, mantenerli separati può contribuire a un'organizzazione migliore, soprattutto se esegui il deployment di molte versioni del modello e del codice.

Testa il tuo modello con le previsioni locali

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

Per l'argomento --model-dir, specifica una directory contenente il tuo 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 model e version. Un modello di previsione di AI Platform è un contenitore per le versioni del tuo modello di machine learning.

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

Crea una risorsa modello

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

Devi decidere in questo momento se vuoi che le versioni del modello appartenenti a questo modello utilizzino un endpoint regionale o l'endpoint globale. Nella maggior parte dei casi, scegli un endpoint regionale. Se hai bisogno di funzionalità disponibili solo su tipi di macchine legacy (MLS1), utilizza l'endpoint globale.

In questo momento devi anche decidere se vuoi che le versioni del modello appartenenti a questo modello esportano eventuali log quando generano previsioni. Gli esempi riportati di seguito non attivano il logging. Scopri come attivare 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. Viene visualizzata la pagina Crea modello.

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

  4. Quando la casella di controllo Usa endpoint a livello di regione è selezionata, 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. Dall'elenco a discesa Regione, seleziona una posizione per i nodi di previsione. Le regioni disponibili variano a seconda che tu utilizzi un endpoint regionale o globale.

  6. Fai clic su Crea.

  7. Verifica di aver fatto ritorno alla pagina Modelli e che il nuovo modello sia presente nell'elenco.

gcloud

Endpoint regionale

Esegui questo comando:

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

Sostituisci quanto segue:

Se non specifichi il flag --region, l'interfaccia alla gcloud CLI ti chiede di selezionare un endpoint regionale (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 regionale corrispondente per AI Platform Prediction, anche se 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, l'interfaccia alla gcloud CLI ti chiede di selezionare un endpoint regionale (o di utilizzare us-central1 per l'endpoint globale).

API REST

Endpoint regionale

  1. Formatta la richiesta inserendo l'oggetto modello nel corpo della richiesta. Come minimo, specifica un nome per il modello sostituendoMODEL_NAME nel seguente esempio:

    {
      "name": "MODEL_NAME"
    }
    
  2. Esegui una chiamata all'API REST al seguente URL, 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 seguente richiesta 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 sostituendoMODEL_NAME nel seguente esempio e specifica una regione sostituendoMODEL_NAME con una regione che supporta i tipi di macchina legacy (MLS1):REGION

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

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

    Ad esempio, puoi effettuare la seguente richiesta 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.

Creare una versione del modello

Ora puoi creare una versione del modello con il modello addestrato caricato in precedenza su Cloud Storage. Quando crei una versione, puoi specificare una serie di parametri. L'elenco seguente descrive i parametri comuni, alcuni dei quali sono obbligatori:

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

    • Se stai eseguendo il deployment di un modello TensorFlow, si tratta di una directory SavedModel.
    • Se stai eseguendo il deployment di un modello scikit-learn o XGBoost, si tratta della directory contenente il file model.joblib, model.pkl o model.bst.
    • Se stai implementando una routine di previsione personalizzata, questa è la directory contenente tutti gli elementi del modello. La dimensione totale di questa directory deve essere inferiore o pari a 500 MB.
  • framework: TENSORFLOW, SCIKIT_LEARN o XGBOOST. Ometti questo parametro se stai implementando una routine di previsione personalizzata.

  • runtimeVersion: una versione di runtime in base alle dipendenze di cui ha bisogno il modello. Se stai eseguendo il deployment di un modello scikit-learn, di un modello XGBoost o di una routine di previsione personalizzata, deve essere almeno 1.4. Se prevedi di utilizzare la versione del modello per le previsioni in batch, devi utilizzare la versione di runtime 2.1 o precedente.

  • packageUris (facoltativo): un elenco di percorsi ai pacchetti di distribuzione del codice personalizzato (file .tar.gz) in Cloud Storage. Fornisci questo parametro solo se stai eseguendo 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 Predictor in formato module_name.class_name. Fornisci questo parametro solo se stai implementando una routine di previsione personalizzata (beta).

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

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

  • 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 macchina. Se non viene impostato, il valore predefinito è n1-standard-2 per gli endpoint regionali e mls1-c1-m2 per l'endpoint globale.

Per ulteriori informazioni su ciascuno di questi parametri, nonché su altri parametri meno comuni, consulta la documentazione di riferimento dell'API per la risorsa versione.

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

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 modello che vuoi utilizzare per creare la versione. Viene visualizzata la pagina Dettagli modello.

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

  4. Inserisci il nome della versione nel campo Nome. Se vuoi, inserisci una descrizione della 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 modello, inserisci la posizione 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 stai eseguendo il deployment di una pipeline scikit-learn con codice personalizzato (beta) o di una routine di previsione personalizzata (beta), fornisci il percorso di Cloud Storage per eventuali pacchetti di codice personalizzato (.tar.gz) in Codice personalizzato e dipendenze. Se esegui il deployment di una routine di previsione personalizzata, inserisci il nome della tua classe predittore nel campo Classe di previsione.

  9. Seleziona un'opzione di scalabilità per il deployment della previsione online:

    • Se selezioni "Scalabilità automatica", viene visualizzato il campo facoltativo Numero minimo di nodi. Quando il servizio è stato ridotto, puoi inserire il numero minimo di nodi da mantenere in esecuzione in qualsiasi momento.

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

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

    Scopri di più sulla determinazione del prezzo per i costi di previsione.

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

gcloud

  1. Imposta le variabili di ambiente per memorizzare il percorso della directory Cloud Storage in cui si trova il file 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 es.SCIKIT_LEARN) o in lettere minuscole con trattini (ad es.scikit-learn). Entrambe le opzioni hanno lo stesso comportamento.

    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 file tarball del 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 del codice personalizzato e il nome della classe di previsione:

    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:

    • REGION: la regione dell'endpoint regionale su cui hai creato il modello. Se hai creato il modello sull'endpoint globale, ometti il flag --region.

    • MACHINE_TYPE: un tipo di macchina che determina le risorse di calcolo disponibili per i nodi di previsione.

    Per una pipeline di 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 tuo 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 \
      --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 è tutto pronto, dovresti vedere il seguente output:

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

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

    Dovresti visualizzare 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 version. 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. Esegui la chiamata all'API REST al seguente percorso, 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 regionale in cui hai creato il tuo modello. Se hai creato il modello sull'endpoint globale, utilizzaml.googleapis.com.

    Ad esempio, puoi effettuare la seguente richiesta 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. Al termine, dovresti vedere un output simile al seguente:

    {
      "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"
        }
      }
    }