Implementation:Recommenders team Recommenders DeepRec Base Model
| Knowledge Sources | |
|---|---|
| Domains | Recommender Systems, Deep Learning, TensorFlow |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Abstract base class for all TensorFlow-based deep recommendation models in the DeepRec framework, providing shared training, evaluation, inference, and neural network building logic.
Description
The BaseModel class is the foundational component that all deeprec TensorFlow models (DKN, xDeepFM, and all sequential models via SequentialBaseModel) inherit from. It centralizes common deep learning infrastructure into a single reusable class.
During initialization, the model creates a TensorFlow computation graph by calling the abstract _build_graph method (which subclasses must implement), then constructs predictions via _get_pred, computes the loss via _get_loss, and builds the optimizer via _build_train_opt. A TensorFlow session is created with GPU memory growth enabled.
The class provides multiple loss functions including cross-entropy, square loss (RMSE), log loss, and softmax with negative sampling. Regularization is handled through L1 and L2 norms on embedding parameters, layer parameters, and cross-network parameters. Weight initialization supports truncated normal, uniform, xavier (normal and uniform), and He (normal and uniform) strategies. Optimizer selection includes Adam, SGD, Adadelta, Adagrad, FTRL, RMSProp, and proximal variants.
The fit method implements the epoch-based training loop with periodic evaluation on a validation set and optional evaluation on a test set, along with model checkpointing and TensorBoard summary writing. The run_eval method computes metrics using cal_metric with support for grouped pairwise metrics.
Utility methods include _fcn_net for building multi-layer perceptrons with batch normalization and dropout, _attention for soft alignment attention, _active_layer for activation with optional dropout, and predict for writing prediction scores to a file.
Usage
BaseModel is never instantiated directly. Subclasses (such as DKN, xDeepFM, ASVD, Caser, GRU4Rec, SLi_Rec, SUM, NextItNet) implement the abstract _build_graph method to define their specific model architecture. The base class handles all training infrastructure automatically.
Code Reference
Source Location
- Repository: Recommenders
- File: recommenders/models/deeprec/models/base_model.py
- Lines: 1-735
Signature
class BaseModel:
"""Base class for models"""
def __init__(self, hparams, iterator_creator, graph=None, seed=None):
@abc.abstractmethod
def _build_graph(self):
def _get_loss(self):
def _get_pred(self, logit, task):
def _compute_data_loss(self):
def _compute_regular_loss(self):
def _l2_loss(self):
def _l1_loss(self):
def _cross_l_loss(self):
def _get_initializer(self):
def _train_opt(self):
def _build_train_opt(self):
def _active_layer(self, logit, activation, layer_idx=-1):
def _activate(self, logit, activation):
def _dropout(self, logit, keep_prob):
def train(self, sess, feed_dict):
def eval(self, sess, feed_dict):
def infer(self, sess, feed_dict):
def load_model(self, model_path=None):
def fit(self, train_file, valid_file, test_file=None):
def run_eval(self, filename):
def predict(self, infile_name, outfile_name):
def group_labels(self, labels, preds, group_keys):
def _attention(self, inputs, attention_size):
def _fcn_net(self, model_output, layer_sizes, scope):
Import
from recommenders.models.deeprec.models.base_model import BaseModel
I/O Contract
Inputs (__init__)
| Name | Type | Required | Description |
|---|---|---|---|
| hparams | HParams | Yes | An HParams object holding the entire set of hyperparameters including loss type, optimizer, learning rate, layer sizes, activation functions, regularization coefficients, initialization method, and more
|
| iterator_creator | callable | Yes | A data iterator class/factory that is called with (hparams, graph) to create the data loading pipeline
|
| graph | tf.Graph | No | An optional TensorFlow graph. If None, a new graph is created
|
| seed | int | No | Random seed for TensorFlow and NumPy reproducibility |
Inputs (fit)
| Name | Type | Required | Description |
|---|---|---|---|
| train_file | str | Yes | Path to the training data file |
| valid_file | str | Yes | Path to the validation data file for per-epoch evaluation |
| test_file | str | No | Optional path to a test data file for additional per-epoch evaluation |
Outputs
| Name | Type | Description |
|---|---|---|
| self | BaseModel | The model instance itself (returned by fit and predict)
|
| self.pred | tf.Tensor | Prediction scores tensor, accessible via eval and infer methods
|
| run_eval return | dict | A dictionary of evaluation metric names to values computed by cal_metric
|
Key Hyperparameters
| Name | Type | Description |
|---|---|---|
| loss | str | Loss function: "cross_entropy_loss", "square_loss", "log_loss", or "softmax"
|
| optimizer | str | Optimizer type: "adam", "sgd", "adadelta", "adagrad", "ftrl", "rmsprop", etc.
|
| learning_rate | float | Learning rate for the optimizer |
| init_method | str | Weight initialization: "tnormal", "uniform", "normal", "xavier_normal", "xavier_uniform", "he_normal", "he_uniform"
|
| epochs | int | Number of training epochs |
| method | str | Task type: "regression" or "classification"
|
| embed_l1 / embed_l2 | float | L1/L2 regularization coefficients for embedding parameters |
| layer_l1 / layer_l2 | float | L1/L2 regularization coefficients for layer parameters |
| is_clip_norm | bool | Whether to apply gradient clipping |
| max_grad_norm | float | Maximum gradient norm for clipping |
| enable_BN | bool | Whether to enable batch normalization in MLP layers |
Usage Examples
Subclassing BaseModel
from recommenders.models.deeprec.models.base_model import BaseModel
class MyModel(BaseModel):
def _build_graph(self):
"""Define model-specific architecture."""
hparams = self.hparams
self.keep_prob_train = 1 - np.array(hparams.dropout)
self.keep_prob_test = np.ones_like(hparams.dropout)
# Build custom layers here
logit = self._fcn_net(self.iterator.input, hparams.layer_sizes, "dnn")
return logit
Training a Subclass Model
from recommenders.models.deeprec.deeprec_utils import prepare_hparams
# Prepare hyperparameters from a YAML config
hparams = prepare_hparams("config.yaml", learning_rate=0.001, epochs=10)
# Instantiate model (MyModel extends BaseModel)
model = MyModel(hparams, iterator_creator)
# Train the model
model.fit(train_file="train.txt", valid_file="valid.txt")
# Evaluate
eval_res = model.run_eval("test.txt")
print(eval_res) # e.g. {"auc": 0.85, "logloss": 0.42}
Related Pages
Requires Environment
- Environment:Recommenders_team_Recommenders_Python_Core_Dependencies
- Environment:Recommenders_team_Recommenders_GPU_CUDA_Environment