How westlake-repl/pixelrec works
Project Type and Purpose
• This is an open-source, research-oriented machine-learning framework for benchmarking multi-modal recommender systems over a large image-interaction dataset (PixelRec).
• It provides data ingestion (raw CSV + images ➔ LMDB), configurable model training (IDNet/PixelNet/ViNet baselines), evaluation metrics, and experiment orchestration via YAML configs and entry scripts (main.py / run.py).
High-Level Components
a. Data Storage & Ingestion
• “dataset/” holds raw interaction files, item metadata, images.
b. Configuration Layer
• YAML files under code/IDNet/, code/PixelNet/, code/ViNet/, code/overall/ define model hyperparameters and encoder choices.
c. Core Library (code/REC/)
• Data module (REC/data/…) handles datasets, batching, collate functions.
• Model module (REC/model/…) houses generic base models, IDNet/PixelNet/ViNet implementations, layer definitions, loading utilities.
• Trainer (REC/trainer/trainer.py) orchestrates forward/backward passes, optimizer schedules, mixed-precision, checkpointing.
• Evaluator (REC/evaluator/…) collects predictions, computes metrics (HR, NDCG, etc.), registers new metrics.
• Utils (REC/utils/…) include logging (local + Weights & Biases), argument parsing, enum types.
d. Entrypoint & Orchestration
• code/main.py and code/run.py parse CLI arguments (--config_file, --device), bootstrap the configurator, instantiate data/train/eval pipelines, then execute training or evaluation loops.
e. External Services
• GPU cluster (NVIDIA A100), LMDB file store, optional Weights & Biases server for experiment tracking.
Relationships & Data Flow
• Raw Dataset ➔ LMDB Generator ➔ LMDB Files
• LMDB Files + YAML Config ➔ Configurator ➔ DataLoader + Model Factory
• DataLoader ➔ Batches ➔ Trainer
• Trainer + Model ➔ Predictions ➔ Evaluator ➔ Metrics + Logs
• Metrics/Checkpoints ➔ Local Disk / W&B
Architectural Patterns & Design Principles
• Modular separation of concerns (Config / Data / Model / Trainer / Evaluator).
• Factory pattern in model loading (loads different baseline classes by name).
• Convention-over-configuration in directory structure (one YAML per experiment).
• Use of dependency injection via configurator for decoupling components.
Key Points to Capture
• The distinction between IDNet (ID-only baselines), PixelNet (end-to-end image + ID), ViNet (visual-only baselines).
• The role of overall/*.yaml in selecting image encoders (ViT, Swin, BEiT, RN50).
• The flow from raw dataset to LMDB to PyTorch DataLoader.
• The split between experiment orchestration (entry scripts) and reusable library code (REC/).
• The evaluation loop and metric reporting pipeline.