Implementation:Recommenders team Recommenders TF Utils

Knowledge Sources	Recommenders
Domains	TensorFlow, Data Pipelines, Model Training, Recommendation Systems
Last Updated	2026-02-10 00:00 GMT

Overview

The tf_utils module provides TensorFlow utility functions for data input pipelines, optimizer construction, model export, and training-time evaluation logging for the TensorFlow Estimator API.

Description

This module serves as the core infrastructure layer for all TensorFlow Estimator-based recommendation models in the library. It contains the following key components:

• pandas_input_fn -- Converts a pandas DataFrame into a tf.data.Dataset pipeline with configurable batching, shuffling, epoch control, and proper handling of array/list columns that the standard TF input function cannot handle. Returns a callable that produces the dataset.

• pandas_input_fn_for_saved_model -- Serializes DataFrame rows as TF Example protobufs for SavedModel serving. Supports int, float, and list feature types.

• build_optimizer -- Maps optimizer name strings to TensorFlow v1 optimizer classes. Supported optimizers: adadelta, adagrad, adam, ftrl, momentum, rmsprop, sgd. Configures learning rate and optimizer-specific parameters (L1/L2 regularization for Ftrl, momentum for Momentum/RMSProp).

• export_model -- Exports a TensorFlow Estimator to SavedModel format with separate input receivers for train, eval, and predict modes using build_supervised_input_receiver_fn_from_input_fn.

• evaluation_log_hook -- Returns a _TrainLogHook (SessionRunHook) that periodically evaluates the model during training at configurable intervals. Supports both loss-based evaluation and custom evaluation functions. Logs results via a MetricsLogger and optionally writes TF summaries for TensorBoard.

• MetricsLogger -- A simple metrics storage class that accumulates metric values in lists, keyed by metric name.

The module also defines MODEL_DIR ("model_checkpoints") and an OPTIMIZERS dictionary as module-level constants.

Usage

Use these utilities when working with TensorFlow Estimator-based models such as Wide & Deep. The pandas_input_fn bridges pandas DataFrames to TensorFlow's data pipeline, build_optimizer provides named optimizer construction, and evaluation_log_hook enables real-time evaluation during training. These utilities are designed to work together as a consistent infrastructure layer.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/utils/tf_utils.py
• Lines: 1-359

Signature

MODEL_DIR = "model_checkpoints"
OPTIMIZERS = dict(...)

def pandas_input_fn_for_saved_model(df, feat_name_type)
def pandas_input_fn(df, y_col=None, batch_size=128, num_epochs=1, shuffle=False, seed=None)
def build_optimizer(name, lr=0.001, **kwargs)
def export_model(model, train_input_fn, eval_input_fn, tf_feat_cols, base_dir)
def evaluation_log_hook(estimator, logger, true_df, y_col, eval_df,
                        every_n_iter=10000, model_dir=None, batch_size=256,
                        eval_fns=None, **eval_kwargs)

class MetricsLogger:
    def __init__(self)
    def log(self, metric, value)
    def get_log(self)

Import

from recommenders.utils.tf_utils import (
    pandas_input_fn,
    pandas_input_fn_for_saved_model,
    build_optimizer,
    export_model,
    evaluation_log_hook,
    MetricsLogger,
    MODEL_DIR,
)

I/O Contract

Inputs

Name	Type	Required	Description
df	pandas.DataFrame	Yes	Data containing features (for pandas_input_fn and pandas_input_fn_for_saved_model)
y_col	str	No	Label column name; if None, no labels are produced (for pandas_input_fn)
batch_size	int	No	Batch size for the input function (default: 128)
num_epochs	int	No	Number of epochs; None for infinite (default: 1)
shuffle	bool	No	Whether to shuffle the data (default: False)
seed	int	No	Random seed for shuffling
feat_name_type	dict	Yes	Feature name to type mapping, e.g. {"userID": int, "itemID": int} (for saved model input fn)
name	str	Yes	Optimizer name: adadelta, adagrad, adam, ftrl, momentum, rmsprop, or sgd (for build_optimizer)
lr	float	No	Learning rate (default: 0.001)
model	tf.estimator.Estimator	Yes	Model to export or evaluate
train_input_fn	function	Yes	Training input function (for export_model)
eval_input_fn	function	Yes	Evaluation input function (for export_model)
tf_feat_cols	list	Yes	Feature columns for serving input spec (for export_model)
base_dir	str	Yes	Base directory for model export (for export_model)
estimator	tf.estimator.Estimator	Yes	Model to evaluate during training (for evaluation_log_hook)
logger	MetricsLogger	Yes	Logger to record evaluation metrics (for evaluation_log_hook)
true_df	pandas.DataFrame	Yes	Ground-truth data for evaluation (for evaluation_log_hook)
eval_df	pandas.DataFrame	Yes	Evaluation data without labels (for evaluation_log_hook)
every_n_iter	int	No	Evaluation frequency in training steps (default: 10000)
eval_fns	iterable of functions	No	Custom evaluation functions with signature (true_df, prediction_df) -> float

Outputs

Name	Type	Description
pandas_input_fn return	callable	A function that returns a tf.data.Dataset
pandas_input_fn_for_saved_model return	callable	A function that returns a dict with serialized TF Examples
build_optimizer return	tf.train.Optimizer	Configured TensorFlow optimizer
export_model return	str	Exported model path as string
evaluation_log_hook return	tf.train.SessionRunHook	Hook for evaluating the model during training
MetricsLogger.get_log return	dict	Dictionary of metric names to lists of values

Usage Examples

Basic Usage

from recommenders.utils.tf_utils import (
    pandas_input_fn, build_optimizer, evaluation_log_hook, MetricsLogger
)

# Create input function from DataFrame
train_fn = pandas_input_fn(
    df=train_df,
    y_col="rating",
    batch_size=256,
    num_epochs=10,
    shuffle=True,
    seed=42
)

# Build an optimizer
optimizer = build_optimizer("adam", lr=0.001)

# Set up evaluation logging during training
logger = MetricsLogger()
hook = evaluation_log_hook(
    estimator=model,
    logger=logger,
    true_df=test_df,
    y_col="rating",
    eval_df=eval_df,
    every_n_iter=5000,
    eval_fns=[rmse, mae]
)

# Train with the hook
model.train(input_fn=train_fn, hooks=[hook])

# Retrieve logged metrics
metrics = logger.get_log()