Implementation:Recommenders team Recommenders XDeepFM

Knowledge Sources	Recommenders xDeepFM: Combining Explicit and Implicit Feature Interactions for Recommender Systems
Domains	Recommender Systems, Deep Learning, Feature Interaction, Click-Through Rate Prediction
Last Updated	2026-02-10 00:00 GMT

Overview

Implements the xDeepFM model, which combines explicit higher-order feature interactions via a Compressed Interaction Network (CIN) with implicit feature interactions via a deep neural network for recommendation and CTR prediction.

Description

The XDeepFMModel class extends BaseModel and implements the xDeepFM architecture from Lian et al. (KDD 2018). The model constructs a modular architecture with four optional components that are independently controlled by hyperparameters and whose logits are summed for the final prediction.

The _build_embedding method creates the field embedding layer. It performs sum pooling of feature embeddings for each field from sparse FFM-format input, producing a fixed-length embedding of size FIELD_COUNT * dim.

The linear part (_build_linear) implements a standard linear regression over the raw sparse features, providing a first-order feature interaction baseline.

The FM part (_build_fm) implements a traditional second-order factorization machine using the efficient sum-of-squares minus square-of-sums formula, capturing pairwise feature interactions.

The CIN part (_build_CIN) is the key innovation of xDeepFM. The Compressed Interaction Network computes explicit vector-wise higher-order feature interactions at each layer. At each CIN layer, outer products are computed between the original embedding layer and the previous CIN hidden layer, producing a tensor of dimension (D, B, F, H). This is then compressed via 1D convolution filters to produce the next hidden layer. The CIN supports residual connections (sum of all layer outputs as a base score), self-interaction masking (removing diagonal interactions in the first layer), direct/indirect connections (splitting hidden units between output and next layer), and optional bias terms. The efficient variant _build_fast_CIN reduces parameters through matrix decomposition, replacing the full outer product and convolution with separate convolutions on the two input components.

The DNN part (_build_dnn) implements a standard multi-layer perceptron with batch normalization and dropout, providing implicit higher-order feature interactions. It uses the same _active_layer mechanism from BaseModel.

Usage

Instantiate XDeepFMModel with hyperparameters that specify which components to enable (use_Linear_part, use_FM_part, use_CIN_part, use_DNN_part), the CIN layer sizes (cross_layer_sizes), and the DNN layer configuration. Use with a standard DeepRec data iterator that provides sparse feature inputs.

Code Reference

Source Location

Repository: Recommenders
File: recommenders/models/deeprec/models/xDeepFM.py
Lines: 1-534

Signature

class XDeepFMModel(BaseModel):
    """xDeepFM model"""

    def _build_graph(self):
    def _build_embedding(self):
    def _build_linear(self):
    def _build_fm(self):
    def _build_CIN(self, nn_input, res=False, direct=False,
                   bias=False, is_masked=False):
    def _build_fast_CIN(self, nn_input, res=False, direct=False, bias=False):
    def _build_dnn(self, embed_out, embed_layer_size):

Import

from recommenders.models.deeprec.models.xDeepFM import XDeepFMModel

I/O Contract

Inputs (inherited from BaseModel `init`)

Name	Type	Required	Description
hparams	HParams	Yes	Hyperparameters object containing model configuration, feature counts, field counts, component toggles, and CIN/DNN layer sizes
iterator_creator	callable	Yes	Data iterator class that provides sparse feature inputs in FFM format with `dnn_feat_indices`, `dnn_feat_values`, `dnn_feat_weights`, `fm_feat_indices`, `fm_feat_values`
graph	tf.Graph	No	Optional TensorFlow graph
seed	int	No	Random seed

Key Hyperparameters

Name	Type	Description
FEATURE_COUNT	int	Total number of unique features across all fields
FIELD_COUNT	int	Number of feature fields
dim	int	Embedding dimension per feature
use_Linear_part	bool	Whether to include the linear regression component
use_FM_part	bool	Whether to include the second-order FM component
use_CIN_part	bool	Whether to include the Compressed Interaction Network
use_DNN_part	bool	Whether to include the deep neural network component
cross_layer_sizes	list	Sizes of each CIN layer (e.g., `[100, 100, 50]`)
cross_activation	str	Activation function used in CIN layers (e.g., `"identity"`)
fast_CIN_d	int	Decomposition rank for fast CIN; if `<= 0`, standard CIN is used
layer_sizes	list	Sizes of each DNN hidden layer
activation	list	Activation functions for each DNN hidden layer
enable_BN	bool	Whether to enable batch normalization
dropout	list	Dropout rates for each layer

Outputs

Name	Type	Description
logit	tf.Tensor	Sum of prediction logits from all enabled components (linear + FM + CIN + DNN)
self.pred	tf.Tensor	Final prediction score after applying sigmoid (classification) or identity (regression) to the logit

Component Outputs

Component	Output Shape	Description
Linear	(batch, 1)	Linear regression score from raw sparse features
FM	(batch, 1)	Second-order factorization machine interaction score
CIN	(batch, 1)	Explicit higher-order vector-wise interaction score via compressed interaction network
DNN	(batch, 1)	Implicit higher-order interaction score via multi-layer perceptron

Usage Examples

Basic Usage

from recommenders.models.deeprec.models.xDeepFM import XDeepFMModel
from recommenders.models.deeprec.io.iterator import FFMTextIterator
from recommenders.models.deeprec.deeprec_utils import prepare_hparams

# Prepare hyperparameters
hparams = prepare_hparams(
    "xdeepfm.yaml",
    FEATURE_COUNT=1000,
    FIELD_COUNT=10,
    dim=16,
    use_Linear_part=True,
    use_FM_part=True,
    use_CIN_part=True,
    use_DNN_part=True,
    cross_layer_sizes=[100, 100, 50],
    cross_activation="identity",
    fast_CIN_d=0,
    layer_sizes=[256, 128],
    activation=["relu", "relu"],
    learning_rate=0.001,
    epochs=10,
    loss="cross_entropy_loss",
    method="classification",
)

# Initialize and train
model = XDeepFMModel(hparams, FFMTextIterator)
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.82, "logloss": 0.45}

Using Fast CIN

# Enable fast CIN with decomposition rank d=2
hparams = prepare_hparams(
    "xdeepfm.yaml",
    FEATURE_COUNT=1000,
    FIELD_COUNT=10,
    dim=16,
    use_CIN_part=True,
    use_DNN_part=True,
    cross_layer_sizes=[200, 200, 100],
    fast_CIN_d=2,
    layer_sizes=[256, 128],
    activation=["relu", "relu"],
)

model = XDeepFMModel(hparams, FFMTextIterator)
model.fit(train_file="train.txt", valid_file="valid.txt")

CIN-Only Model

# Use only the CIN component for pure explicit feature interactions
hparams = prepare_hparams(
    "xdeepfm.yaml",
    use_Linear_part=False,
    use_FM_part=False,
    use_CIN_part=True,
    use_DNN_part=False,
    cross_layer_sizes=[200, 200, 200],
)

model = XDeepFMModel(hparams, FFMTextIterator)
model.fit(train_file="train.txt", valid_file="valid.txt")

Related Pages

Depends On

Implementation:Recommenders_team_Recommenders_DeepRec_Base_Model

Requires Environment

Uses Heuristic

Heuristic:Recommenders_team_Recommenders_TensorFlow_Session_Ordering

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment