Rutinas de predicción personalizadas

Las rutinas de predicción personalizadas te permiten determinar qué código se ejecuta cuando envías una solicitud de predicción en línea a AI Platform Prediction.

Cuando implementas un recurso de versión en AI Platform Prediction sin usar una rutina de predicción personalizada, ese recurso controla las solicitudes de predicción y, para ello, realiza la operación de predicción del framework de aprendizaje automático que usaste en el entrenamiento.

Pero cuando implementas una rutina de predicción personalizada como el recurso de versión, puedes indicar a AI Platform Prediction que ejecute un código de Python personalizado en respuesta a cada solicitud de predicción que reciba. Puedes procesar previamente la entrada de predicción antes de que el modelo entrenado realice la predicción, o puedes realizar un procesamiento posterior de la predicción del modelo antes de enviar el resultado de la predicción.

Para crear una rutina de predicción personalizada, debes proporcionar dos partes a AI Platform Prediction cuando creas la versión del modelo:

  • Un directorio del modelo en Cloud Storage, que contiene todos los artefactos que deben usarse para la predicción

  • Un paquete de distribución de origen de Python .tar.gz en Cloud Storage, que contenga la implementación de la interfaz de Predictor y cualquier otro código personalizado que deseas que AI Platform Prediction use en el momento de la predicción

Solo puedes implementar una rutina de predicción personalizada cuando usas un tipo de máquina heredada (MLS1) para la versión de tu modelo.

Sube los artefactos del modelo al directorio del modelo

Sigue la guía de implementación de modelos para subir el modelo entrenado a Cloud Storage, junto con los archivos que proporcionan datos o registros de estado a fin de que AI Platform Prediction los use durante la predicción.

El tamaño total del archivo de los artefactos de modelo que implementas en AI Platform Prediction debe ser de 500 MB o menos.

Puedes subir tu modelo de entrenamiento de aprendizaje automático a tu directorio del modelo como un SavedModel de TensorFlow, un archivo model.joblib, un archivo model.pkl o un archivo model.bst, pero también puedes proporcionar tu modelo como un archivo HDF5 que contiene un modelo tf.keras entrenado o en un formato serializado diferente.

Además, puedes incluir un archivo pickle con una instancia de una clase de procesador previo personalizado que conserva el estado serializado del entrenamiento.

Por ejemplo, considera el siguiente preprocesador, definido en el archivo llamado 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 el entrenamiento en un conjunto de datos numéricos, el preprocesador centra los datos alrededor de 0; para ello, resta la media de cada columna de cada valor en la columna. Luego, puedes exportar la instancia del preprocesador como un archivo pickle preprocessor.pkl, que conserva las medias de cada columna calculadas a partir de los datos de entrenamiento.

Durante la predicción, una rutina de predicción personalizada puede cargar el preprocesador desde este archivo para realizar una transformación idéntica en la entrada de predicción.

A fin de aprender cómo usar un procesador previo con estado similar a este en tu rutina de predicción personalizada, lee la siguiente sección, en la que se describe cómo implementar la interfaz de Predictor.

Para ver un ejemplo completo sobre el uso de un preprocesador con estado durante el entrenamiento y la predicción, lee Crea una rutina de predicción personalizada con Keras o Crea una rutina de predicción personalizada con scikit-learn.

Crea un Predictor

Para indicar a AI Platform Prediction cómo administrar las solicitudes de predicción, proporciónale una clase de Predictor. Esta es una clase que implementa la siguiente interfaz:

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

Los nodos de predicción de AI Platform Prediction usan el método de clase from_path para cargar una instancia del Predictor. Este método debe cargar los artefactos que guardaste en el directorio del modelo, cuyos contenidos se copian de Cloud Storage a una ubicación que indica el argumento model_dir.

Cada vez que la implementación recibe una solicitud de predicción en línea, la instancia de la clase de Predictor que muestra from_path usa su método predict para generar predicciones. AI Platform Prediction serializa el valor de resultado de este método a JSON y lo envía como respuesta a la solicitud de predicción.

Ten en cuenta que el método predict no necesita convertir la entrada de JSON a objetos de Python ni convertir la salida en JSON. AI Platform Prediction se encarga de esta tarea fuera del método predict.

AI Platform Prediction proporciona el argumento instances cuando analiza el campo instances del cuerpo de la solicitud predict a la API de entrenamiento y predicción de AI Platform. Analiza los demás campos del cuerpo de la solicitud y los proporciona al método predict como entradas en el diccionario **kwargs. Obtén información sobre cómo estructurar una solicitud predict a la API de entrenamiento y predicción de AI Platform.

Para seguir con el ejemplo de la sección anterior, supongamos que el directorio de modelos contiene preprocessor.pkl (la instancia serializada de la clase ZeroCenterer) y un modelo entrenado tf.keras exportado como model.h5 o un modelo de scikit-learn entrenado y exportado como model.joblib.

Según el framework de aprendizaje automático que uses, implementa una de las siguientes clases de Predictor en un archivo llamado 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)

Ten en cuenta que el método predict convierte los resultados de la predicción en una lista con el tolist método antes de devolverlas. Los arreglos NumPy no pueden serializarse con JSON, por lo que debes convertirlos en listas de números (que sí pueden serializarse con JSON). De lo contrario, AI Platform Prediction no podrá enviar la respuesta de la predicción.

Empaqueta el Predictor y sus dependencias

Debes empaquetar el Predictor como un paquete de distribución de origen .tar.gz. Debido a que NumPy, TensorFlow y scikit-learn se incluyen en la imagen del entorno de ejecución de AI Platform Prediction, no es necesario que incluyas estas dependencias en el archivo comprimido. Sin embargo, asegúrate de incluir todas las dependencias de Predictor que no estén preinstaladas en AI Platform Prediction.

Para el ejemplo anterior, debes incluir preprocess.py en el paquete de distribución de origen, aunque el Predictor no lo importe de forma explícita. De lo contrario, preprocessor = pickle.load(f) fallará porque Python no reconocerá la clase de la instancia de ZeroCenterer en el archivo pickle.

En setup.py a continuación, se muestra una forma de empaquetar estas secuencias de comandos:

from setuptools import setup

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

Para empaquetar y subir el ejemplo de código personalizado descrito en esta página, haz lo siguiente:

  1. Crea los archivos preprocess.py, predictor.py y setup.py que se describen en las secciones anteriores, todos en el mismo directorio. Navega hasta ese directorio en tu Shell.

  2. Ejecuta python setup.py sdist --formats=gztar para crear dist/my_custom_code-0.1.tar.gz.

  3. Sube este archivo comprimido a una ubicación de etapa de pruebas en Cloud Storage.

    No es necesario que sea la misma que la del directorio de modelos. Si planeas iterar y, también, implementar varias versiones de la rutina de predicción personalizada, puede que desees subir los paquetes de código personalizado en un directorio de etapa de pruebas designado. Puedes incrementar el argumento version en setup.py cuando actualices el código para realizar un seguimiento de las diferentes versiones.

    El siguiente comando muestra una forma de subir el paquete de distribución de origen a Cloud Storage:

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

Puedes proporcionar el código para la rutina de predicción personalizada en uno o más paquetes.

Implementa tu rutina de predicción personalizada

Primero, selecciona una región en la que la predicción en línea esté disponible y usa gcloud para crear un recurso del modelo:

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

Asegúrate de que tu componente gcloud beta esté actualizado, luego, crea un recurso de versión con especial atención en las siguientes marcas gcloud:

  • --origin: es la ruta de acceso a tu directorio de modelos en Cloud Storage.
  • --package-uris: Es una lista separada por comas de los archivos comprimidos de código de usuario en Cloud Storage, incluido el que contiene tu clase de Predictor.
  • --prediction-class: Es el nombre completamente calificado de la clase de Predictor (MODULE_NAME.CLASS_NAME).
  • --framework: No especifiques un framework cuando implementes una rutina de predicción personalizada.
  • --runtime-version: Las rutinas de predicción personalizadas están disponibles en las versiones 1.4 a 2.11 del entorno de ejecución.

En el siguiente comando, se muestra cómo crear un recurso de versión según los archivos de ejemplo descritos en las secciones anteriores:

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

Si deseas obtener más información sobre la creación de modelos y versiones en detalle, o aprender a crearlos mediante la consola de Google Cloud en lugar de la CLI de gcloud, consulta la guía de implementación de modelos.

Especifica una cuenta de servicio

Cuando se crea un recurso de versión, puedes especificar una cuenta de servicio para que la rutina de predicción personalizada la use durante la predicción. Esto te permite personalizar los permisos para acceder a otros recursos de Google Cloud. Obtén más información sobre cómo especificar una cuenta de servicio para la rutina de predicción personalizada.

Pasos siguientes

  • Revisa un instructivo sobre cómo usar rutinas de predicción personalizadas con Keras o con scikit-learn para ver un ejemplo más completo de cómo entrenar y luego implementar un modelo mediante una rutina de predicción personalizada.
  • Lee la guía para exportar modelos si deseas obtener información sobre cómo exportar artefactos para la predicción sin usar una rutina de predicción personalizada.
  • Consulta la guía de implementación de modelos para obtener más detalles sobre cómo implementar los recursos de model y version en AI Platform Prediction a fin de entregar predicciones.