# facebookresearch/generative-recommenders architecture

> Architecture diagram of the GitHub repository facebookresearch/generative-recommenders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/generative-recommenders
- Repository: https://github.com/facebookresearch/generative-recommenders

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Preprocessing
    subgraph "Data & Preprocessing"
        direction TB
        Raw_Data["Raw Public Datasets (tmp/)"]:::data
        RD_Synthetic["Synthetic Data Generator"]:::data
        RD_PublicPrep["Public Data Preprocessor"]:::data
        DL_DatasetModule["DLRM-v3 Dataset Modules"]:::data
        Dataset_Store["Serialized Dataset Store"]:::data
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        Config_GlobalG["Global Gin Configs"]:::config
        Config_TrainGin["DLRM-v3 Training Gin"]:::config
        Config_InfGin["DLRM-v3 Inference Gin"]:::config
        SetupFiles["setup.py / requirements.txt"]:::config
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        Entry_PublicExp["main.py (Public Experiments Entrypoint)"]:::pipeline
        Entry_DL3Trainer["train_ranker.py (DLRM-v3 Trainer)"]:::pipeline
        Train_Utils["Training Utilities"]:::pipeline
        Core_Modules["Core Model Modules"]:::pipeline
        Ops_CPP["Custom Ops C++/CUDA"]:::ext
        Ops_Triton["Custom Ops Triton"]:::ext
        Ops_PyTorch["PyTorch Wrappers"]:::ext
        CheckpointMgr["Checkpoint Management"]:::pipeline
        TB_Logs["TensorBoard Logs (exps/)"]:::pipeline
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        Entry_Infer["inference/main.py"]:::pipeline
        DataProducer["DataProducer"]:::pipeline
        Inf_Modules["Inference Modules"]:::pipeline
        ModelLoader["Model Family Loader"]:::pipeline
        LoadGen["MLPerf LoadGen"]:::ext
        Inf_Config["Inference Config"]:::config
        PerfMetrics["Performance Metrics"]:::pipeline
    end

    %% Research & Extensions
    subgraph "Research & Analysis"
        direction TB
        Research_Data["Research Data & Indexing"]:::data
        Research_Model["Research Modeling"]:::pipeline
        Research_Trainer["Research Trainer & Experiments"]:::pipeline
        PublicScript["run_fractal_expansion.py"]:::data
    end

    %% Data & Preprocessing Flow
    Raw_Data -->|"read .csv"| RD_PublicPrep
    RD_Synthetic -->|"generate .csv"| DL_DatasetModule
    RD_PublicPrep -->|"output serialized"| Dataset_Store
    DL_DatasetModule -->|"load & serialize"| Dataset_Store

    %% Config Dependencies
    Config_GlobalG -.->|gin| RD_PublicPrep
    Config_GlobalG -.->|gin| Entry_PublicExp
    Config_GlobalG -.->|gin| Entry_DL3Trainer
    Config_TrainGin -.->|gin| Entry_DL3Trainer
    Config_InfGin -.->|gin| Entry_Infer
    SetupFiles -.->|env| Entry_PublicExp
    SetupFiles -.->|env| Entry_DL3Trainer

    %% Training Flow
    Dataset_Store -->|"Train Data"| Entry_PublicExp
    Dataset_Store -->|"Train Data"| Entry_DL3Trainer
    Entry_DL3Trainer --> Core_Modules
    Entry_DL3Trainer --> Train_Utils
    Entry_DL3Trainer --> Ops_CPP
    Entry_DL3Trainer --> Ops_Triton
    Entry_DL3Trainer --> Ops_PyTorch
    Core_Modules & Ops_CPP & Ops_Triton & Ops_PyTorch --> CheckpointMgr
    CheckpointMgr --> TB_Logs

    %% Inference Flow
    Dataset_Store -->|"Dataset"| Entry_Infer
    CheckpointMgr -->|"Checkpoint"| Entry_Infer
    Entry_Infer --> DataProducer
    DataProducer --> Inf_Modules
    Inf_Modules --> ModelLoader
    ModelLoader --> LoadGen
    LoadGen --> PerfMetrics
    Inf_Config -.->|gin| Entry_Infer

    %% Research Integration
    Research_Data --> Entry_PublicExp
    Research_Model --> Entry_DL3Trainer
    Research_Trainer --> Entry_PublicExp
    Research_Trainer --> Entry_Infer
    PublicScript --> Research_Data

    %% Click Events
    click RD_Synthetic "https://github.com/facebookresearch/generative-recommenders/blob/main/run_fractal_expansion.py"
    click RD_PublicPrep "https://github.com/facebookresearch/generative-recommenders/blob/main/preprocess_public_data.py"
    click DL_DatasetModule "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/datasets/dataset.py"
    click Config_GlobalG "https://github.com/facebookresearch/generative-recommenders/tree/main/configs/"
    click Config_TrainGin "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/dlrm_v3/train/gin/"
    click Config_InfGin "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/dlrm_v3/inference/gin/"
    click SetupFiles "https://github.com/facebookresearch/generative-recommenders/blob/main/setup.py"
    click SetupFiles "https://github.com/facebookresearch/generative-recommenders/blob/main/requirements.txt"
    click Entry_PublicExp "https://github.com/facebookresearch/generative-recommenders/blob/main/main.py"
    click Entry_DL3Trainer "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/train/train_ranker.py"
    click Train_Utils "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/train/utils.py"
    click Core_Modules "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/modules/"
    click Ops_CPP "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/ops/cpp/"
    click Ops_Triton "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/ops/triton/"
    click Ops_PyTorch "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/ops/pytorch/"
    click Entry_Infer "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/main.py"
    click DataProducer "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/data_producer.py"
    click Inf_Modules "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/inference_modules.py"
    click ModelLoader "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/model_family.py"
    click LoadGen "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/dlrm_v3/inference/thirdparty/loadgen/"
    click Inf_Config "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/dlrm_v3/inference/user.conf"
    click Research_Data "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/research/data/"
    click Research_Data "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/research/indexing/"
    click Research_Model "https://github.com/facebookresearch/generative-recommenders/tree/main/generative_recommenders/research/modeling/"
    click Research_Trainer "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/research/trainer/train.py"
    click Research_Trainer "https://github.com/facebookresearch/generative-recommenders/blob/main/generative_recommenders/research/trainer/data_loader.py"
    click PublicScript "https://github.com/facebookresearch/generative-recommenders/blob/main/run_fractal_expansion.py"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef pipeline fill:#90EE90,stroke:#333,stroke-width:1px
    classDef config fill:#FFA500,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
```
