Implementation:Recommenders team Recommenders LightGCN

Knowledge Sources	Recommenders LightGCN: Simplifying and Powering Graph Convolution Network for Recommendation
Domains	Recommender Systems, Deep Learning, Graph Neural Networks, Collaborative Filtering
Last Updated	2026-02-10 00:00 GMT

Overview

Implements the LightGCN model, a simplified graph convolution network for collaborative filtering that achieves strong performance by removing feature transformation and nonlinear activation from standard GCN.

Description

The LightGCN class implements the LightGCN architecture from He et al. (SIGIR 2020). Unlike the DeepRec models that extend BaseModel, LightGCN is a standalone class that manages its own TensorFlow session, training loop, and evaluation pipeline because it operates on graph-structured implicit feedback data rather than sequential feature-based input.

During initialization, user and item embeddings are created using Xavier initialization via _init_weights. The GCN propagation is constructed in _create_lightgcn_embed, which stacks n_layers of sparse matrix multiplications with the normalized adjacency matrix (provided by the ImplicitCF data object). After propagation, embeddings from all layers (including the initial embedding layer) are stacked and averaged to produce the final user and item representations. This layer-averaging is a key design choice that distinguishes LightGCN from other GCN approaches.

Training uses BPR (Bayesian Personalized Ranking) loss computed in _create_bpr_loss, which maximizes the difference between positive and negative item scores using a softplus function. L2 regularization is applied to the original pre-propagation embeddings (not the propagated ones), controlled by the decay hyperparameter. The Adam optimizer is used for training.

The fit method runs the training loop, sampling positive and negative items via the data object's train_loader. Optional periodic evaluation is triggered every eval_epoch epochs using run_eval, which computes top-k recommendation metrics (MAP, NDCG, Precision, Recall).

The score method computes ratings for all items for a batch of users via matrix multiplication of their propagated embeddings. It optionally removes items already seen during training by setting their scores to negative infinity. The recommend_k_items method generates a pandas DataFrame of top-k recommendations using get_top_k_scored_items.

The infer_embedding method exports the learned user and item embeddings to TSV files for external use.

Usage

Instantiate LightGCN with hyperparameters and an ImplicitCF data object that provides the normalized adjacency matrix and train/test splits. Call fit() to train (no file arguments needed since data is provided at initialization). Use recommend_k_items() to generate recommendations and score() to compute raw scores.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/models/deeprec/models/graphrec/lightgcn.py
• Lines: 1-417

Signature

class LightGCN(object):
    """LightGCN model"""

    def __init__(self, hparams, data, seed=None):

    def _init_weights(self):
    def _create_lightgcn_embed(self):
    def _create_bpr_loss(self, users, pos_items, neg_items):
    def _convert_sp_mat_to_sp_tensor(self, X):

    def fit(self):
    def load(self, model_path=None):
    def run_eval(self):
    def score(self, user_ids, remove_seen=True):
    def recommend_k_items(self, test, top_k=10, sort_top_k=True,
                          remove_seen=True, use_id=False):
    def output_embeddings(self, idmapper, n, target, user_file):
    def infer_embedding(self, user_file, item_file):

Import

from recommenders.models.deeprec.models.graphrec.lightgcn import LightGCN

I/O Contract

Inputs (__init__)

Name	Type	Required	Description
hparams	HParams	Yes	Hyperparameters object with model configuration
data	ImplicitCF	Yes	A recommenders.models.deeprec.DataModel.ImplicitCF object that loads and processes implicit feedback data, provides the normalized adjacency matrix, and exposes train_loader, n_users, n_items
seed	int	No	Random seed for TensorFlow and NumPy reproducibility

Key Hyperparameters

Name	Type	Description
epochs	int	Number of training epochs
learning_rate	float	Learning rate for the Adam optimizer
embed_size	int	Dimension of user and item embedding vectors
batch_size	int	Mini-batch size for training
n_layers	int	Number of GCN propagation layers
decay	float	L2 regularization coefficient for BPR loss
eval_epoch	int	Evaluate every N epochs; set to -1 to disable periodic evaluation
top_k	int	Number of top items for evaluation metrics
metrics	list	List of evaluation metrics: "map", "ndcg", "precision", "recall"
save_model	bool	Whether to save model checkpoints
save_epoch	int	Save a checkpoint every N epochs
MODEL_DIR	str	Directory for saving model checkpoints

Inputs (recommend_k_items)

Name	Type	Required	Description
test	pandas.DataFrame	Yes	Test data containing user and item columns
top_k	int	No	Number of top items to recommend. Defaults to 10
sort_top_k	bool	No	Whether to sort top-k results. Defaults to True
remove_seen	bool	No	Whether to remove items seen in training. Defaults to True
use_id	bool	No	Whether user IDs in the test set are internal integer IDs. Defaults to False

Outputs

Name	Type	Description
score return	numpy.ndarray	Matrix of predicted scores with shape (n_test_users, n_items)
recommend_k_items return	pandas.DataFrame	DataFrame with columns for user, item, and prediction score, containing top-k recommendations per user
run_eval return	list	List of metric values corresponding to the configured self.metrics

Usage Examples

Basic Usage

from recommenders.models.deeprec.models.graphrec.lightgcn import LightGCN
from recommenders.models.deeprec.DataModel.ImplicitCF import ImplicitCF
from recommenders.models.deeprec.deeprec_utils import prepare_hparams

# Load data
data = ImplicitCF(train=train_df, test=test_df)

# Prepare hyperparameters
hparams = prepare_hparams(
    "lightgcn.yaml",
    epochs=50,
    learning_rate=0.005,
    embed_size=64,
    batch_size=1024,
    n_layers=3,
    decay=1e-4,
    eval_epoch=5,
    top_k=10,
    metrics=["ndcg", "recall"],
)

# Initialize and train
model = LightGCN(hparams, data, seed=42)
model.fit()

Generating Recommendations

# Generate top-10 recommendations for test users
topk_scores = model.recommend_k_items(test_df, top_k=10, remove_seen=True)
print(topk_scores.head())
#   userID  itemID  prediction
# 0      1     234    0.95432
# 1      1     567    0.87654
# ...

Exporting Embeddings

# Export learned user and item embeddings
model.infer_embedding(
    user_file="output/user_embeddings.tsv",
    item_file="output/item_embeddings.tsv",
)
# Each line: id<TAB>dim1 dim2 dim3 ...

Related Pages

Requires Environment

• Environment:Recommenders_team_Recommenders_Python_Core_Dependencies
• Environment:Recommenders_team_Recommenders_GPU_CUDA_Environment

Uses Heuristic

• Heuristic:Recommenders_team_Recommenders_TensorFlow_Session_Ordering