Routine di previsione personalizzate

Le routine di previsione personalizzate ti consentono di determinare il codice da eseguire quando invii una richiesta di previsione online ad AI Platform Prediction.

Quando esegui il deployment di una risorsa di versione in AI Platform Prediction senza utilizzare una routine di previsione personalizzata, le richieste di previsione vengono gestite eseguendo l'operazione di previsione del framework di machine learning utilizzato per l'addestramento.

Tuttavia, quando esegui il deployment di una routine di previsione personalizzata come risorsa di versione, puoi chiedere ad AI Platform Prediction di eseguire codice Python personalizzato in risposta a ogni richiesta di previsione ricevuta. Puoi pre-elaborare l'input di previsione prima che il modello addestrato effettui la previsione oppure puoi post-elaborare la previsione del modello prima di inviare il risultato della previsione.

Per creare una routine di previsione personalizzata, devi fornire due parti a AI Platform Prediction quando crei la versione del modello:

  • Una directory del modello in Cloud Storage, che contiene tutti gli elementi da utilizzare per la previsione.

  • Un pacchetto di distribuzione di origine Python .tar.gz in Cloud Storage contenente l'implementazione dell'interfaccia Predictor e qualsiasi altro codice personalizzato che vuoi che AI Platform Prediction utilizzi al momento della previsione.

Puoi eseguire il deployment di una routine di previsione personalizzata solo se utilizzi un tipo di macchina legacy (MLS1) per la versione del modello.

Carica gli artefatti del modello nella directory del modello

Segui la guida all'implementazione dei modelli per caricare il modello addestrato su Cloud Storage, insieme a tutti gli altri file che forniscono dati o stato per l'utilizzo da parte di AI Platform Prediction durante la previsione.

Le dimensioni totali dei file degli elementi del modello di cui esegui il deployment in AI Platform Prediction devono essere pari o inferiori a 500 MB.

Puoi caricare il modello di machine learning addestrato nella directory dei modelli come TensorFlow SavedModel, file model.joblib, file model.pkl o model.bst, ma puoi anche fornire il modello come file HDF5 contenente un modello tf.keras addestrato o in un formato serializzato diverso.

Puoi anche includere un file pickle con un'istanza di una classe di preelaborazione personalizzata che contiene lo stato serializzato dell'addestramento.

Ad esempio, considera il seguente preprocessore, definito nel file chiamato preprocess.py:

import numpy as np


class ZeroCenterer(object):
    """Stores means of each column of a matrix and uses them for preprocessing."""

    def __init__(self):
        """On initialization, is not tied to any distribution."""
        self._means = None

    def preprocess(self, data):
        """Transforms a matrix.

        The first time this is called, it stores the means of each column of
        the input. Then it transforms the input so each column has mean 0. For
        subsequent calls, it subtracts the stored means from each column. This
        lets you 'center' data at prediction time based on the distribution of
        the original training data.

        Args:
            data: A NumPy matrix of numerical data.

        Returns:
            A transformed matrix with the same dimensions as the input.
        """
        if self._means is None:  # during training only
            self._means = np.mean(data, axis=0)
        return data - self._means

Durante l'addestramento su un set di dati numerico, il pre-processore centra i dati intorno a 0 sottraendo la media di ogni colonna da ogni valore della colonna. Quindi, puoi esportare l'istanza del pre-processore come file pickle, preprocessor.pkl, che conserva le medie di ogni colonna calcolate dai dati di addestramento.

Durante la previsione, una routine di previsione personalizzata può caricare il pre-processore da questo file per eseguire una trasformazione identica sull'input di previsione.

Per scoprire come utilizzare un pre-processore con stato come questo nella routine di previsione personalizzata, leggi la sezione successiva, che descrive come implementare l'interfaccia Predictor.

Per esaminare un esempio completo dell'utilizzo di un pre-processore con stato durante l'addestramento e la previsione, leggi Creare una routine di previsione personalizzata con Keras o Creare una routine di previsione personalizzata con scikit-learn.

Creare il predittore

Indica ad AI Platform Prediction come gestire le richieste di previsione fornendogli una classe Predictor. Questa è una classe che implementa la seguente interfaccia:

class Predictor(object):
    """Interface for constructing custom predictors."""

    def predict(self, instances, **kwargs):
        """Performs custom prediction.

        Instances are the decoded values from the request. They have already
        been deserialized from JSON.

        Args:
            instances: A list of prediction input instances.
            **kwargs: A dictionary of keyword args provided as additional
                fields on the predict request body.

        Returns:
            A list of outputs containing the prediction results. This list must
            be JSON serializable.
        """
        raise NotImplementedError()

    @classmethod
    def from_path(cls, model_dir):
        """Creates an instance of Predictor using the given path.

        Loading of the predictor should be done in this method.

        Args:
            model_dir: The local directory that contains the exported model
                file along with any additional files uploaded when creating the
                version resource.

        Returns:
            An instance implementing this Predictor class.
        """
        raise NotImplementedError()

I nodi di previsione di AI Platform Prediction utilizzano il metodo di classe from_path per caricare un'istanza del tuo predittore. Questo metodo dovrebbe caricare gli elementi salvati nella directory del modello, i cui contenuti vengono copiati da Cloud Storage in una posizione indicata dall'argomento model_dir.

Ogni volta che il deployment riceve una richiesta di previsione online, l'istanza della classe Predictor restituita da from_path utilizza il metodo predict per generare le previsioni. AI Platform Prediction esegue la serializzazione del valore restituito di questo metodo in JSON e lo invia come risposta alla richiesta di previsione.

Tieni presente che il metodo predict non deve convertire l'input da JSON in oggetti Python o l'output in JSON. AI Platform Prediction gestisce questa operazione al di fuori del metodo predict.

AI Platform Prediction fornisce l'argomento instances analizzando il campo instances dal corpo della richiesta predict all'API AI Platform Training and Prediction. Analizza tutti gli altri campi del corpo della richiesta e li fornisce al metodo predict come voci nel dizionario **kwargs. Per saperne di più, leggi l'articolo su come strutturare una richiestapredict all'API AI Platform Training and Prediction.

Continuando con l'esempio della sezione precedente, supponiamo che la tua directory del modello contenga preprocessor.pkl (l'istanza sottoposta a pickling della classe ZeroCenterer) e un modello tf.keras addestrato esportato come model.h5 o un modello scikit-learn addestrato esportato come model.joblib.

A seconda del framework di machine learning utilizzato, implementa una delle seguenti classi di Predictor in un file denominato predictor.py:

TensorFlow

import os
import pickle

import numpy as np
from tensorflow import keras


class MyPredictor(object):
    """An example Predictor for an AI Platform custom prediction routine."""

    def __init__(self, model, preprocessor):
        """Stores artifacts for prediction. Only initialized via `from_path`."""
        self._model = model
        self._preprocessor = preprocessor

    def predict(self, instances, **kwargs):
        """Performs custom prediction.

        Preprocesses inputs, then performs prediction using the trained Keras
        model.

        Args:
            instances: A list of prediction input instances.
            **kwargs: A dictionary of keyword args provided as additional
                fields on the predict request body.

        Returns:
            A list of outputs containing the prediction results.
        """
        inputs = np.asarray(instances)
        preprocessed_inputs = self._preprocessor.preprocess(inputs)
        outputs = self._model.predict(preprocessed_inputs)
        return outputs.tolist()

    @classmethod
    def from_path(cls, model_dir):
        """Creates an instance of MyPredictor using the given path.

        This loads artifacts that have been copied from your model directory in
        Cloud Storage. MyPredictor uses them during prediction.

        Args:
            model_dir: The local directory that contains the trained Keras
                model and the pickled preprocessor instance. These are copied
                from the Cloud Storage model directory you provide when you
                deploy a version resource.

        Returns:
            An instance of `MyPredictor`.
        """
        model_path = os.path.join(model_dir, "model.h5")
        model = keras.models.load_model(model_path)

        preprocessor_path = os.path.join(model_dir, "preprocessor.pkl")
        with open(preprocessor_path, "rb") as f:
            preprocessor = pickle.load(f)

        return cls(model, preprocessor)

scikit-learn

import os
import pickle

import numpy as np
from sklearn.externals import joblib


class MyPredictor(object):
    """An example Predictor for an AI Platform custom prediction routine."""

    def __init__(self, model, preprocessor):
        """Stores artifacts for prediction. Only initialized via `from_path`."""
        self._model = model
        self._preprocessor = preprocessor

    def predict(self, instances, **kwargs):
        """Performs custom prediction.

        Preprocesses inputs, then performs prediction using the trained
        scikit-learn model.

        Args:
            instances: A list of prediction input instances.
            **kwargs: A dictionary of keyword args provided as additional
                fields on the predict request body.

        Returns:
            A list of outputs containing the prediction results.
        """
        inputs = np.asarray(instances)
        preprocessed_inputs = self._preprocessor.preprocess(inputs)
        outputs = self._model.predict(preprocessed_inputs)
        return outputs.tolist()

    @classmethod
    def from_path(cls, model_dir):
        """Creates an instance of MyPredictor using the given path.

        This loads artifacts that have been copied from your model directory in
        Cloud Storage. MyPredictor uses them during prediction.

        Args:
            model_dir: The local directory that contains the trained
                scikit-learn model and the pickled preprocessor instance. These
                are copied from the Cloud Storage model directory you provide
                when you deploy a version resource.

        Returns:
            An instance of `MyPredictor`.
        """
        model_path = os.path.join(model_dir, "model.joblib")
        model = joblib.load(model_path)

        preprocessor_path = os.path.join(model_dir, "preprocessor.pkl")
        with open(preprocessor_path, "rb") as f:
            preprocessor = pickle.load(f)

        return cls(model, preprocessor)

Tieni presente che il metodo predict converte i risultati della previsione in un elenco con il metodo tolist prima di restituirli. Gli array NumPy non sono serializzabili in JSON, quindi devi convertirli in elenchi di numeri (che sono serializzabili in JSON). In caso contrario, AI Platform Prediction non riuscirà a inviare la risposta alla previsione.

Esegui il packaging del predittore e delle sue dipendenze

Devi pacchettizzare il predittore come pacchetto di distribuzione di origine .tar.gz. Poiché NumPy, TensorFlow e scikit-learn sono inclusi nell'immagine del runtime di AI Platform Prediction, non è necessario includere queste dipendenze nel file tarball. Tuttavia, assicurati di includere tutte le dipendenze di Predictor che non sono preinstallate su AI Platform Prediction.

Per l'esempio riportato sopra, devi includere preprocess.py nel pacchetto di distribuzione di origine, anche se il predittore non lo importa esplicitamente. In caso contrario, preprocessor = pickle.load(f) non andrà a buon fine perché Python non riconoscerà la classe dell'istanza ZeroCenterer nel file pickle.

Il seguente setup.py mostra un modo per pacchettizzare questi script:

from setuptools import setup

setup(name="my_custom_code", version="0.1", scripts=["predictor.py", "preprocess.py"])

Per pacchettizzare e caricare l'esempio di codice personalizzato descritto in questa pagina, procedi nel seguente modo:

  1. Crea i file preprocess.py, predictor.py e setup.py descritti nelle sezioni precedenti, tutti nella stessa directory. Vai a quella directory nella shell.

  2. Esegui python setup.py sdist --formats=gztar per creare dist/my_custom_code-0.1.tar.gz.

  3. Carica questo file tarball in una posizione di staging in Cloud Storage.

    Non deve necessariamente corrispondere alla directory del modello. Se prevedi di eseguire l'iterazione e il deployment di più versioni della routine di previsione personalizzata, ti consigliamo di caricare i pacchetti di codice personalizzato in una directory di staging apposita. Puoi incrementare l'argomento version in setup.py quando aggiorni il codice per tenere traccia delle diverse versioni.

    Il seguente comando mostra un modo per caricare il pacchetto della distribuzione di origine su Cloud Storage:

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

Puoi fornire il codice della routine di previsione personalizzata in uno o più pacchetti.

Esegui il deployment della routine di previsione personalizzata

Innanzitutto, seleziona una regione in cui è disponibile la previsione online e utilizza gcloud per creare una risorsa modello:

gcloud ai-platform models create MODEL_NAME{"</var>"}} \
  --regions CHOSEN_REGION

Assicurati che il componente gcloud beta sia aggiornato, quindi crea una risorsa di versione prestando particolare attenzione ai seguenti flag gcloud beta:gcloud

  • --origin: il percorso della directory del modello in Cloud Storage.
  • --package-uris: un elenco separato da virgole di pacchetti tar del codice utente in Cloud Storage, incluso quello contenente la classe Predictor.
  • --prediction-class: il nome completo della classe Predictor (MODULE_NAME.CLASS_NAME).
  • --framework: non specificare un framework quando esegui il deployment di una routine di previsione personalizzata.
  • --runtime-version: le routine di previsione personalizzate sono disponibili nelle versioni di runtime da 1.4 a 2.11.

Il comando seguente mostra come creare una risorsa versione in base ai file di esempio descritti nelle sezioni precedenti:

gcloud components install beta

gcloud beta ai-platform versions create VERSION_NAME \
  --model MODEL_NAME{"</var>"}} \
  --runtime-version 2.11 \
  --python-version 3.7 \
  --origin gs://YOUR_BUCKET/PATH_TO_MODEL_DIR \
  --package-uris gs://YOUR_BUCKET/PATH_TO_STAGING_DIR/my_custom_code-0.1.tar.gz \
  --prediction-class predictor.MyPredictor

Per scoprire di più sulla creazione di modelli e versioni in dettaglio o per scoprire come crearli utilizzando la console Google Cloud anziché l'interfaccia alla gcloud CLI, consulta la guida al deployment dei modelli.

Specifica un account di servizio personalizzato

Quando crei una risorsa di versione, puoi specificare facoltativamente un account di servizio da utilizzare per la routine di previsione personalizzata durante la previsione. In questo modo puoi personalizzare le autorizzazioni per accedere ad altre risorse Google Cloud. Scopri di più su come specificare un account di servizio per la routine di previsione personalizzata.

Passaggi successivi

  • Consulta un tutorial sull'utilizzo delle routine di previsione personalizzate con Keras o con scikit-learn per vedere un esempio più completo di come addestrare e implementare un modello utilizzando una routine di previsione personalizzata.
  • Leggi la guida all'esportazione dei modelli per scoprire di più sull'esportazione degli artefatti per la previsione senza utilizzare una routine di previsione personalizzata.
  • Leggi la guida al deployment dei modelli per scoprire di più sul deployment delle risorse model e version in AI Platform Prediction per generare le previsioni.