Benutzerdefinierte Vorhersageroutinen

Mithilfe benutzerdefinierter Vorhersageroutinen können Sie ermitteln, welcher Code ausgeführt wird, wenn Sie eine Anfrage für eine Onlinevorhersage an AI Platform Prediction senden.

Wenn Sie eine Versionsressource ohne benutzerdefinierte Vorhersageroutine in AI Platform Prediction bereitstellen, werden Vorhersageanfragen analog zu dem Vorhersagevorgang des Frameworks für maschinelles Lernen ausgeführt, den Sie für das Training verwendet haben.

Wenn Sie jedoch eine benutzerdefinierte Vorhersageroutine als Versionsressource bereitstellen, können Sie AI Platform Prediction anweisen, als Antwort auf erhaltene Vorhersageanfragen jeweils benutzerdefinierten Python-Code auszuführen. Sie können die Vorhersageeingabe vorverarbeiten, bevor Sie mit dem trainierten Modell eine Vorhersage ausführen, oder Sie können die Vorhersage des Modells vor dem Senden der Vorhersageergebnisse nachbearbeiten.

Beim Erstellen Ihrer Modellversion müssen Sie AI Platform Prediction zwei Komponenten bereitstellen, um eine benutzerdefinierte Vorhersageroutine zu erstellen:

  • Ein Modellverzeichnis in Cloud Storage, das alle für die Vorhersage zu verwendenden Artefakte enthält

  • Ein .tar.gz-Quelldistributionspaket von Python in Cloud Storage, das Ihre Implementierung der Predictor-Schnittstelle und sonstigen benutzerdefinierten Code enthält, den AI Platform Prediction zur Vorhersagezeit verwenden soll

Sie können eine benutzerdefinierte Vorhersageroutine nur bereitstellen, wenn Sie für die Modellversion einen Legacy-Maschinentyp (MLS1) verwenden.

Modellartefakte in das Modellverzeichnis hochladen

In der Anleitung zum Bereitstellen von Modellen wird beschrieben, wie Sie in Cloud Storage ein trainiertes Modell zusammen mit anderen Dateien hochladen, die AI Platform Prediction mit Daten oder Zuständen versorgen, die während der Vorhersage zu verwenden sind.

Die Gesamtgröße der Modellartefakte, die Sie für AI Platform Prediction bereitstellen, darf maximal 500 MB betragen.

Sie können Ihr trainiertes ML-Modell als TensorFlow-SavedModel, model.joblib-Datei, model.pkl-Datei oder model.bst-Datei in das Modellverzeichnis hochladen. Ebenfalls können Sie das Modell als HDF5-Datei mit einem trainierten tf.keras-Modell oder in einem anderen serialisierten Format bereitstellen.

Zusätzlich können Sie eine Pickle-Datei mit der Instanz einer benutzerdefinierten Präprozessorklasse hinzufügen, die den serialisierten Zustand vom Training enthält.

Betrachten Sie beispielsweise den folgenden Präprozessor, der in der Datei preprocess.py definiert ist:

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

Während des Trainings mit einem numerischen Dataset zentriert der Präprozessor die Daten um 0. Dazu wird der Mittelwert jeder Spalte von jedem Wert in der Spalte subtrahiert. Anschließend können Sie die Präprozessorinstanz als Pickle-Datei (preprocessor.pkl) exportieren, um die Mittelwerte jeder Spalte, die aus den Trainingsdaten berechnet wurden, zu speichern.

Während der Vorhersage kann eine benutzerdefinierte Vorhersageroutine den Präprozessor aus dieser Datei laden, um eine identische Transformation für die Vorhersageeingabe durchzuführen.

Im nächsten Abschnitt wird die Implementierung der Predictor-Schnittstelle beschrieben. Dabei erfahren Sie, wie Sie einen zustandsorientierten Präprozessor wie diesen in einer benutzerdefinierten Vorhersageroutine verwenden können.

Ein ausführliches Beispiel für die Verwendung eines zustandsorientierten Präprozessors während des Trainings und der Vorhersage finden Sie unter Benutzerdefinierte Vorhersageroutine mit Keras erstellen oder Benutzerdefinierte Vorhersageroutine mit scikit-learn erstellen.

Predictor erstellen

Stellen Sie in AI Platform Prediction eine Predictor-Klasse bereit, um vorzugeben, wie Vorhersageanfragen verarbeitet werden sollen. Diese Klasse implementiert die folgende Schnittstelle:

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()

Vorhersageknoten von AI Platform Prediction verwenden die Klassenmethode from_path, um eine Instanz Ihres Predictors zu laden. Bei dieser Methode sollten die im Modellverzeichnis gespeicherten Artefakte geladen werden. Deren Inhalte werden aus Cloud Storage an einen Speicherort kopiert, der durch das Argument model_dir angezeigt wird.

Immer wenn Ihre Bereitstellung eine Anfrage für eine Onlinevorhersage erhält, verwendet die von from_path zurückgegebene Instanz der Predictor-Klasse die zugehörige predict-Methode, um Vorhersagen zu generieren. AI Platform Prediction serialisiert den Rückgabewert dieser Methode in JSON und sendet ihn als Antwort auf die Vorhersageanfrage.

Die Methode predict muss keine Eingabe von JSON in Python-Objekte und keine Ausgabe in JSON konvertieren. Dies findet außerhalb der Methode predict in AI Platform Prediction statt.

AI Platform Prediction parst das Feld instances aus dem Text der predict-Anfrage, um der AI Platform Training and Prediction API das Argument instances bereitzustellen. Alle anderen Felder des Anfragetexts werden geparst und der Methode predict als Einträge im Wörterbuch **kwargs bereitgestellt. Weitere Informationen finden Sie unter predict-Anfrage für die AI Platform Training and Prediction API strukturieren.

Wir ziehen noch einmal das Beispiel aus dem vorherigen Abschnitt heran und gehen davon aus, dass Ihr Modellverzeichnis preprocessor.pkl (die Pickle-Instanz der Klasse ZeroCenterer) und entweder ein als model.h5 exportiertes trainiertes tf.keras-Modell oder ein trainiertes scikit-learn-Modell enthält, das als model.joblib exportiert wurde.

Abhängig davon, welches ML-Framework Sie verwenden, implementieren Sie eine der folgenden Predictor-Klassen in einer Datei namens 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)

Die Methode predict konvertiert die Vorhersageergebnisse mit der Methode tolist in eine Liste, bevor sie sie zurückgibt. NumPy-Arrays können nicht in JSON serialisiert werden. Daher müssen Sie sie in Listen mit Nummern konvertieren (die in JSON serialisiert werden können). Andernfalls sendet AI Platform Prediction keine Antwort auf die Vorhersageanfrage.

Paket mit dem Predictor und den zugehörigen Abhängigkeiten erstellen

Sie müssen den Predictor als .tar.gz-Distributionspaket mit Quellen verpacken. Da NumPy, TensorFlow und scikit-learn im Laufzeit-Image von AI Platform Prediction enthalten sind, müssen diese Abhängigkeiten nicht in das Tarball-Paket eingefügt werden. Achten Sie jedoch darauf, alle Abhängigkeiten des Predictors hinzuzufügen, die nicht in AI Platform Prediction vorinstalliert sind.

Für das obige Beispiel müssen Sie preprocess.py in das Distributionspaket aufnehmen, auch wenn der Predictor die Datei nicht explizit importiert. Andernfalls schlägt preprocessor = pickle.load(f) fehl, weil Python die Klasse der ZeroCenterer-Instanz in der Pickle-Datei nicht erkennt.

Die folgende setup.py-Datei zeigt eine Möglichkeit, wie diese Skripte verpackt werden können:

from setuptools import setup

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

So verpacken Sie den auf dieser Seite beschriebenen benutzerdefinierten Beispielcode und laden ihn anschließend hoch:

  1. Erstellen Sie die in den vorherigen Abschnitten beschriebenen Dateien preprocess.py, predictor.py und setup.py im selben Verzeichnis. Rufen Sie dieses Verzeichnis in Ihrer Shell auf.

  2. Führen Sie python setup.py sdist --formats=gztar aus, um dist/my_custom_code-0.1.tar.gz zu erstellen.

  3. Laden Sie dieses Tarball-Paket an einen Staging-Speicherort in Cloud Storage hoch.

    Dieser muss nicht mit Ihrem Modellverzeichnis identisch sein. Wenn Sie beabsichtigen, mehrere Versionen der benutzerdefinierten Vorhersageroutine zu iterieren und bereitzustellen, sollten Sie Ihre benutzerdefinierten Codepakete in ein festgelegtes Staging-Verzeichnis hochladen. Zur Unterscheidung verschiedener Versionen können Sie das Argument version in setup.py erhöhen, wenn Sie den Code aktualisieren.

    Der folgende Befehl ist eine Möglichkeit, um das Distributionspaket in Cloud Storage hochzuladen:

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

Sie können Code für Ihre benutzerdefinierte Vorhersageroutine in einem oder mehreren Paketen bereitstellen.

Benutzerdefinierte Vorhersageroutine bereitstellen

Wählen Sie zuerst eine Region aus, in der Onlinevorhersagen verfügbar sind, und erstellen Sie dann mit gcloud eine Modellressource:

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

Die gcloud beta-Komponente sollte aktualisiert sein. Erstellen Sie eine Versionsressource und beachten Sie dabei die folgenden gcloud-Flags:

  • --origin: Der Pfad zu Ihrem Modellverzeichnis in Cloud Storage.
  • --package-uris: Eine durch Kommas getrennte Liste von Nutzercode-Tarballs in Cloud Storage, einschließlich des Pakets, das Ihre Predictor-Klasse enthält.
  • --prediction-class: Der vollständig qualifizierte Name Ihrer Prediction-Klasse (MODULE_NAME.CLASS_NAME).
  • --framework: Geben Sie bei der Bereitstellung einer benutzerdefinierten Vorhersageroutine kein Framework an.
  • --runtime-version: Benutzerdefinierte Vorhersageroutinen sind in den Laufzeitversionen 1.4 bis 2.11 verfügbar.

Im folgenden Befehl wird gezeigt, wie Sie auf Basis der in den vorherigen Abschnitten beschriebenen Beispieldateien eine Versionsressource erstellen:

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

Weitere ausführliche Informationen zum Erstellen von Modellen und Versionen oder zum Erstellen von Modellen und Versionen mit der Google Cloud Platform Console anstelle der gcloud CLI finden Sie im Leitfaden zum Bereitstellen von Modellen.

Dienstkonto angeben

Beim Erstellen einer Versionsressource können Sie optional ein Dienstkonto angeben, das Ihre benutzerdefinierte Vorhersageroutine während der Vorhersage verwenden soll. Auf diese Weise können Sie die Berechtigungen für den Zugriff auf andere Google Cloud-Ressourcen anpassen. Weitere Informationen finden Sie unter Ein Dienstkonto für Ihre benutzerdefinierte Vorhersageroutine angeben.

Weitere Informationen

  • Eine Anleitung zu benutzerdefinierten Vorhersageroutinen mit Keras oder mit scikit-learn durcharbeiten, um ein umfangreicheres Beispiel für das Trainieren und Bereitstellen eines Modells mit einer benutzerdefinierten Vorhersageroutine zu sehen
  • Leitfaden zum Exportieren von Modellen lesen, um Informationen zum Exportieren von Artefakten für die Vorhersage ohne eine benutzerdefinierte Vorhersageroutine zu erhalten
  • Leitfaden zum Bereitstellen von Modellen lesen, um mehr über das Bereitstellen von model- und version-Ressourcen für Vorhersagen in AI Platform Prediction zu erfahren