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.

Cuando implementas un recurso de versión en AI Platform 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 marco de trabajo de aprendizaje automático que utilizaste para el entrenamiento.

Pero cuando implementas una rutina de predicción personalizada como tu recurso de versión, puedes indicarle a AI Platform 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 tu modelo entrenado realice la predicción, o puedes procesar posteriormente 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 cuando creas tu 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 fuente de Python .tar.gz en Cloud Storage que contiene tu implementación de la interfaz de Predictor y cualquier otro código personalizado que deseas que AI Platform use en el momento de la predicción.

Sube los artefactos del modelo a tu directorio del modelo

Sigue la guía de implementación de modelos para subir tu modelo entrenado en Cloud Storage, junto con los archivos que proporcionan datos o registros de estado para que AI Platform 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 solicitar una cuota más alta para implementar modelos más grandes.

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 preprocesador 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 procesador previo 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 tu Predictor

Indícale a AI Platform cómo manejar las solicitudes de predicción; para ello, se le debe proporcionar 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 usan el método de clase from_path para cargar una instancia de tu Predictor. Este método debe cargar los artefactos que guardaste en tu directorio del modelo, cuyos contenidos se copian desde Cloud Storage a una ubicación que surge del 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 serializa el valor de retorno 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 en objetos de Python ni convertir la salida a JSON; AI Platform se encarga de esta tarea fuera del método .

AI Platform proporciona el argumento instances cuando analiza el campo del cuerpo de la solicitud predict a la API de entrenamiento y predicción de AI Platform. Analiza cualquier otro campo del cuerpo de la solicitud y los proporciona al método predict como entradas en el diccionario **kwargs. Si deseas obtener más información, lee acerca de cómo estructurar una solicitud predict para la API de entrenamiento y predicción de AI Platform .

Para seguir con el ejemplo de la sección anterior, supongamos que tu directorio de modelos contiene preprocessor.pkl (la instancia serializada de la claseZeroCenterer) 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 marco de trabajo de aprendizaje automático que uses, implementa una de las clases de Predictor siguientes 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 método tolist antes de mostrarlos. 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 no podrá enviar la respuesta de predicción.

Empaqueta tu Predictor y sus dependencias

Debes empaquetar tu Predictor como un paquete de distribución de fuente .tar.gz. Debido a que NumPy, TensorFlow y scikit-learn se incluyen en la imagen del entorno de ejecución de AI Platform, no es necesario incluir estas dependencias en el tarball. Sin embargo, asegúrate de incluir todas las dependencias de Predictor que no se hayan instalado previamente en AI Platform.

Para el ejemplo anterior, debes incluir preprocess.py en tu paquete de distribución de fuente, aunque tu Predictor no lo importe explícitamente. 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 descritos 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 igual que el modelo del directorio. Si tienes planes de iterar y de implementar varias versiones de tu rutina de predicción personalizada, es posible que desees subir tus paquetes de código personalizado a 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 tu paquete de distribución de fuente a Cloud Storage:

    gsutil cp dist/my_custom_code-0.1.tar.gz gs://your-bucket/path-to-staging-dir/
    

Puedes proporcionar el código para tu 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 de la siguiente manera:

gcloud ai-platform models create model-name \
  --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: una lista separada por comas de los archivos comprimidos de código de usuario en Cloud Storage, incluida la que contiene tu clase de Predictor.
  • --prediction-class: es el nombre completo de tu clase de Predictor ( module_name . class_name ).
  • --framework: no especifiques un marco de trabajo cuando implementes una rutina de predicción personalizada.
  • --runtime-version: las rutinas de predicción personalizadas están disponibles en las versiones del entorno de ejecución 1.4 y superiores.

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 \
  --runtime-version 1.14 \
  --python-version 3.5 \
  --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 Google Cloud Platform Console en lugar de la herramienta de gcloud, consulta la guía para implementar modelos.

Especifica una cuenta de servicio

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

Próximos pasos

  • 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 destinados a predicción sin usar una rutina de predicción personalizada.
  • Lee la guía para implementar modelos a fin de obtener más detalles sobre cómo implementar los recursos model y version destinados a la entrega de predicciones en AI Platform.