<br />

***A tutorial to train a TensorFlow Recommenders ranking model as a [TFX pipeline](https://www.tensorflow.org/tfx).***

|---|---|---|---|
| [![](https://www.tensorflow.org/images/tf_logo_32px.png)View on TensorFlow.org](https://www.tensorflow.org/recommenders/examples/ranking_tfx) | [![](https://www.tensorflow.org/images/colab_logo_32px.png)Run in Google Colab](https://colab.research.google.com/github/tensorflow/recommenders/blob/main/docs/examples/ranking_tfx.ipynb) | [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png)View source on GitHub](https://github.com/tensorflow/recommenders/blob/main/docs/examples/ranking_tfx.ipynb) | [![](https://www.tensorflow.org/images/download_logo_32px.png)Download notebook](https://storage.googleapis.com/tensorflow_docs/recommenders/docs/examples/ranking_tfx.ipynb) |

In this notebook-based tutorial, we will create and run a [TFX pipeline](https://www.tensorflow.org/tfx)
to train a ranking model to predict movie ratings using TensorFlow Recommenders (TFRS).
The pipeline will consist of three essential TFX components: ExampleGen,
Trainer and Pusher. The pipeline includes the most minimal ML workflow like
importing data, training a model and exporting the trained TFRS ranking model.

## Set Up

We first need to install the TFX Python package and download
the dataset which we will use for our model.

### Upgrade Pip

To avoid upgrading Pip in a system when running locally,
check to make sure that we are running in Colab.
Local systems can of course be upgraded separately.

    import sys
    if 'google.colab' in sys.modules:
      !pip install --upgrade pip

### Install TFX

    pip install -U tfx
    pip install -U tensorflow-recommenders

### Did you restart the runtime?

If you are using Google Colab, the first time that you run
the cell above, you must restart the runtime by clicking
above "RESTART RUNTIME" button or using "Runtime \> Restart
runtime ..." menu. This is because of the way that Colab
loads packages.

Before we define the pipeline, we need to write the model code for the
Trainer component and save it in a file.

Check the TensorFlow and TFX versions.

    import tensorflow as tf
    print('TensorFlow version: {}'.format(tf.__version__))
    from tfx import v1 as tfx
    print('TFX version: {}'.format(tfx.__version__))

### Set up variables

There are some variables used to define a pipeline. You can customize these
variables as you want. By default all output from the pipeline will be
generated under the current directory. Instead of using the SchemaGen component to generate a schema, for this
tutorial we will create a hardcoded schema.

    import os

    PIPELINE_NAME = 'TFRS-ranking'

    # Directory where MovieLens 100K rating data lives
    DATA_ROOT = os.path.join('data', PIPELINE_NAME)
    # Output directory to store artifacts generated from the pipeline.
    PIPELINE_ROOT = os.path.join('pipelines', PIPELINE_NAME)
    # Path to a SQLite DB file to use as an MLMD storage.
    METADATA_PATH = os.path.join('metadata', PIPELINE_NAME, 'metadata.db')
    # Output directory where created models from the pipeline will be exported.
    SERVING_MODEL_DIR = os.path.join('serving_model', PIPELINE_NAME)

    from absl import logging
    logging.set_verbosity(logging.INFO)  # Set default logging level.

### Prepare example data

Since TFX does not currently support TensorFlow Datasets API, we will download the MovieLens 100K dataset manually for use in our TFX pipeline. The dataset we
are using is
[MovieLens 100K Dataset](https://grouplens.org/datasets/movielens/100k/).

There are four numeric features in this dataset:

- userId
- movieId
- rating
- timestamp

We will build a ranking model which predicts the `rating` of the movies. We will not use the `timestamp` feature.

Because TFX ExampleGen reads inputs from a directory, we need to create a
directory and copy dataset to it.

    wget https://files.grouplens.org/datasets/movielens/ml-100k.zip
    mkdir -p {DATA_ROOT}
    unzip ml-100k.zip
    echo 'userId,movieId,rating,timestamp' > {DATA_ROOT}/ratings.csv
    sed 's/\t/,/g' ml-100k/u.data >> {DATA_ROOT}/ratings.csv

Take a quick look at the CSV file.

    head {DATA_ROOT}/ratings.csv

You should be able to see four values. For example, the first example means user '196' gives a rating of 3 to movie '242'.

## Create a pipeline

TFX pipelines are defined using Python APIs. We will define a pipeline which
consists of following three components.

- CsvExampleGen: Reads in data files and convert them to TFX internal format for further processing. There are multiple [ExampleGen](https://www.tensorflow.org/tfx/guide/examplegen)s for various formats. In this tutorial, we will use CsvExampleGen which takes CSV file input.
- Trainer: Trains an ML model. [Trainer component](https://www.tensorflow.org/tfx/guide/trainer) requires a model definition code from users. You can use TensorFlow APIs to specify how to train a model and save it in a _saved*model* format.
- Pusher: Copies the trained model outside of the TFX pipeline. [Pusher component](https://www.tensorflow.org/tfx/guide/pusher) can be thought of an deployment process of the trained ML model.

Before actually define the pipeline, we need to write a model code for the
Trainer component first.

### Write model training code

We will build a simple ranking model to predict movie ratings. This model training code will be saved to a separate file.

In this tutorial we will use
[Generic Trainer](https://www.tensorflow.org/tfx/guide/trainer#generic_trainer)
of TFX which support Keras-based models. You need to write a Python file
containing `run_fn` function, which is the entrypoint for the `Trainer`
component.

    _trainer_module_file = 'tfrs_ranking_trainer.py'

The ranking model we use is almost exactly the same as in the [Basic Ranking](https://www.tensorflow.org/recommenders/examples/basic_ranking) tutorial. The only difference is that we use movie IDs instead of movie titles in the candidate tower.

    %%writefile {_trainer_module_file}

    from typing import Dict, Text
    from typing import List

    import numpy as np
    import tensorflow as tf

    from tensorflow_metadata.proto.v0 import schema_pb2
    import tensorflow_recommenders as tfrs
    from tensorflow_transform.tf_metadata import schema_utils
    from tfx import v1 as tfx
    from tfx_bsl.public import tfxio

    _FEATURE_KEYS = ['userId', 'movieId']
    _LABEL_KEY = 'rating'

    _FEATURE_SPEC = {
        **{
            feature: tf.io.FixedLenFeature(shape=[1], dtype=tf.int64)
            for feature in _FEATURE_KEYS
        }, _LABEL_KEY: tf.io.FixedLenFeature(shape=[1], dtype=tf.int64)
    }


    class RankingModel(tf.keras.Model):

      def __init__(self):
        super().__init__()
        embedding_dimension = 32

        unique_user_ids = np.array(range(943)).astype(str)
        unique_movie_ids = np.array(range(1682)).astype(str)

        # Compute embeddings for users.
        self.user_embeddings = tf.keras.Sequential([
            tf.keras.layers.Input(shape=(1,), name='userId', dtype=tf.int64),
            tf.keras.layers.Lambda(lambda x: tf.as_string(x)),
            tf.keras.layers.StringLookup(
                vocabulary=unique_user_ids, mask_token=None),
            tf.keras.layers.Embedding(
                len(unique_user_ids) + 1, embedding_dimension)
        ])

        # Compute embeddings for movies.
        self.movie_embeddings = tf.keras.Sequential([
            tf.keras.layers.Input(shape=(1,), name='movieId', dtype=tf.int64),
            tf.keras.layers.Lambda(lambda x: tf.as_string(x)),
            tf.keras.layers.StringLookup(
                vocabulary=unique_movie_ids, mask_token=None),
            tf.keras.layers.Embedding(
                len(unique_movie_ids) + 1, embedding_dimension)
        ])

        # Compute predictions.
        self.ratings = tf.keras.Sequential([
            tf.keras.layers.Dense(256, activation='relu'),
            tf.keras.layers.Dense(64, activation='relu'),
            tf.keras.layers.Dense(1)
        ])

      def call(self, inputs):

        user_id, movie_id = inputs

        user_embedding = self.user_embeddings(user_id)
        movie_embedding = self.movie_embeddings(movie_id)

        return self.ratings(tf.concat([user_embedding, movie_embedding], axis=2))


    class MovielensModel(tfrs.models.Model):

      def __init__(self):
        super().__init__()
        self.ranking_model: tf.keras.Model = RankingModel()
        self.task: tf.keras.layers.Layer = tfrs.tasks.Ranking(
            loss=tf.keras.losses.MeanSquaredError(),
            metrics=[tf.keras.metrics.RootMeanSquaredError()])

      def call(self, features: Dict[str, tf.Tensor]) -> tf.Tensor:
        return self.ranking_model((features['userId'], features['movieId']))

      def compute_loss(self,
                       features: Dict[Text, tf.Tensor],
                       training=False) -> tf.Tensor:

        labels = features[1]
        rating_predictions = self(features[0])

        # The task computes the loss and the metrics.
        return self.task(labels=labels, predictions=rating_predictions)


    def _input_fn(file_pattern: List[str],
                  data_accessor: tfx.components.DataAccessor,
                  schema: schema_pb2.Schema,
                  batch_size: int = 256) -> tf.data.Dataset:
      return data_accessor.tf_dataset_factory(
          file_pattern,
          tfxio.TensorFlowDatasetOptions(
              batch_size=batch_size, label_key=_LABEL_KEY),
          schema=schema).repeat()


    def _build_keras_model() -> tf.keras.Model:
      return MovielensModel()


    # TFX Trainer will call this function.
    def run_fn(fn_args: tfx.components.FnArgs):
      """Train the model based on given args.

      Args:
        fn_args: Holds args used to train the model as name/value pairs.
      """
      schema = schema_utils.schema_from_feature_spec(_FEATURE_SPEC)

      train_dataset = _input_fn(
          fn_args.train_files, fn_args.data_accessor, schema, batch_size=8192)
      eval_dataset = _input_fn(
          fn_args.eval_files, fn_args.data_accessor, schema, batch_size=4096)

      model = _build_keras_model()

      model.compile(optimizer=tf.keras.optimizers.Adagrad(learning_rate=0.1))

      model.fit(
          train_dataset,
          steps_per_epoch=fn_args.train_steps,
          epochs = 3,
          validation_data=eval_dataset,
          validation_steps=fn_args.eval_steps)

      model.save(fn_args.serving_model_dir)

Now you have completed all preparation steps to build the TFX pipeline.

### Write a pipeline definition

We define a function to create a TFX pipeline. A `Pipeline` object
represents a TFX pipeline which can be run using one of pipeline
orchestration systems that TFX supports.

    def _create_pipeline(pipeline_name: str, pipeline_root: str, data_root: str,
                         module_file: str, serving_model_dir: str,
                         metadata_path: str) -> tfx.dsl.Pipeline:
      """Creates a three component pipeline with TFX."""
      # Brings data into the pipeline.
      example_gen = tfx.components.CsvExampleGen(input_base=data_root)

      # Uses user-provided Python function that trains a model.
      trainer = tfx.components.Trainer(
          module_file=module_file,
          examples=example_gen.outputs['examples'],
          train_args=tfx.proto.TrainArgs(num_steps=12),
          eval_args=tfx.proto.EvalArgs(num_steps=24))

      # Pushes the model to a filesystem destination.
      pusher = tfx.components.Pusher(
          model=trainer.outputs['model'],
          push_destination=tfx.proto.PushDestination(
              filesystem=tfx.proto.PushDestination.Filesystem(
                  base_directory=serving_model_dir)))

      # Following three components will be included in the pipeline.
      components = [
          example_gen,
          trainer,
          pusher,
      ]

      return tfx.dsl.Pipeline(
          pipeline_name=pipeline_name,
          pipeline_root=pipeline_root,
          metadata_connection_config=tfx.orchestration.metadata
          .sqlite_metadata_connection_config(metadata_path),
          components=components)

## Run the pipeline

TFX supports multiple orchestrators to run pipelines.
In this tutorial we will use `LocalDagRunner` which is included in the TFX
Python package and runs pipelines on local environment.

Now we create a `LocalDagRunner` and pass a `Pipeline` object created from the
function we already defined.

The pipeline runs directly and you can see logs for the progress of the pipeline including ML model training.

    tfx.orchestration.LocalDagRunner().run(
      _create_pipeline(
          pipeline_name=PIPELINE_NAME,
          pipeline_root=PIPELINE_ROOT,
          data_root=DATA_ROOT,
          module_file=_trainer_module_file,
          serving_model_dir=SERVING_MODEL_DIR,
          metadata_path=METADATA_PATH))

You should see "INFO:absl:Component Pusher is finished." at the end of the
logs if the pipeline finished successfully. Because `Pusher` component is the
last component of the pipeline.

The pusher component pushes the trained model to the `SERVING_MODEL_DIR` which
is the `serving_model/TFRS-ranking` directory if you did not change the
variables in the previous steps. You can see the result from the file browser
in the left-side panel in Colab, or using the following command:

    # List files in created model directory.
    ls -R {SERVING_MODEL_DIR}

Now we can test the ranking model by computing predictions for a user and a movie:

    import glob
    # Load the latest model for testing
    loaded = tf.saved_model.load(max(glob.glob(os.path.join(SERVING_MODEL_DIR, '*/')), key=os.path.getmtime))
    print(loaded({'userId': [[42]], 'movieId': [[15]]}).numpy())

This concludes the TensorFlow Recommenders + TFX tutorial.