How facebookresearch/generative-recommenders works
Project Type and Purpose
• This is a machine-learning research codebase implementing “Generative Recommenders” (GRs) and a DLRM-v3 model. It includes data preprocessing, training pipelines, inference (with MLPerf loadgen), custom operators (CUDA/Triton/C++), and configuration management (Gin).
• The goal is to (a) reproduce and benchmark sequential recommendation experiments (MovieLens, Amazon Books, synthetic ML-3B), (b) run the DLRM-v3 training/inference, and (c) develop and test novel high-efficiency kernels (HSTU, M-FALCON).
A. Data Layer
• Raw public datasets (MovieLens, Amazon Reviews) under tmp/
• Synthetic data generator (run_fractal_expansion.py)
• Preprocessing script (preprocess_public_data.py, generative_recommenders/dlrm_v3/preprocess_public_data.py)
• Output: serialized datasets for training/inference
B. Configuration Layer
• Gin config files under configs/ and generative_recommenders/*/gin/
• requirements.txt, setup.py
• Manages hyperparameters, dataset choices, model variants (SASRec, HSTU, HSTU-large)
C. Training Pipeline
• Entry point: main.py for public experiments; generative_recommenders/dlrm_v3/train/train_ranker.py for DLRM-v3
• Core modules: generative_recommenders/modules (encoders, transducers, preprocessors)
• Custom ops: generative_recommenders/ops (cpp, pytorch wrappers, triton)
• Dependencies: PyTorch, torchrec, fbgemm_gpu, gin-config
• Output: model checkpoints, TensorBoard logs under exps/
D. Inference Pipeline
• Entry point: generative_recommenders/dlrm_v3/inference/main.py
• DataProducer reads serialized dataset, serves queries to model
• MLPerf loadgen third-party library for performance measurement
• Model family loader + inference modules run forward pass via custom kernels
• Output: latency/throughput metrics, inference results
E. Research & Analysis
• generative_recommenders/research/… for data indexing, embedding modules, loss definitions
• run_fractal_expansion.py, research/trainer/train.py for custom research experiments
Relationships and Data Flow
• Data Layer → Configuration Layer: Gin configs parameterize data paths and preprocessing options.
• Data Layer → Preprocessor → Dataset store → Training Pipeline
• Training Pipeline ↔ Custom ops & Modules (runtime loads CUDA/Triton/C++ extensions)
• Training Pipeline → Checkpoint storage + TensorBoard logs
• Checkpoint + Dataset → Inference Pipeline → MLPerf loadgen → Performance metrics
• Research components plug into both training and inference pipelines to try new architectures or losses.
Architectural Patterns and Principles
• Modular separation: data, config, core modules, ops library, pipelines, and research code.
• Extension libraries: custom CUDA/C++ and Triton kernels compiled separately and loaded via Python bindings.
• Pluggable configuration: Gin-config files control experiments without code changes.
• Benchmarking harness: MLPerf loadgen integrated as a third-party submodule under inference.