How akalikong/minionerec works
1. What this repository is
- MiniOneRec is an end-to-end generative recommendation pipeline.
- The architecture is staged: raw item/user data is cleaned, item text is embedded, those embeddings are compressed into discrete item codes called SIDs, and then an LLM is trained and refined for recommendation.
2. Core data flow
- Raw Amazon review data enters the preprocessing layer.
- Preprocessed user histories and item metadata feed the embedding/SID construction layer.
- SID mappings and converted interaction sequences feed supervised fine-tuning.
- The fine-tuned model then enters a reinforcement-learning stage.
- Offline evaluation consumes generated recommendations and computes ranking metrics.
3. Dataset preparation boundary
- data/amazon18_data_process.py, data/amazon23_data_process.py, and their .sh wrappers build train/valid/test splits from Amazon datasets.
- These scripts produce time-filtered interaction CSVs plus item info files.
- There are GPR-flavored variants that enrich the dataset with heterogeneous signals for the “unified input representation” path.
- The checked-in data/Amazon/... directory contains ready-to-use processed splits for Industrial and Office datasets.
4. Text-to-embedding subsystem
- rq/text2emb/amazon_text2emb.py turns each product’s title/description into a dense embedding.
- This stage depends on an external embedding model checkpoint and, optionally, multi-GPU orchestration via Accelerate.
- Output is a .npy embedding matrix that becomes the input to SID construction.
5. SID construction subsystem
- The rq/ package is the discrete-item-code factory.
- It contains multiple alternatives: rqvae.py for RQ-VAE, rqkmeans_faiss.py for standard RQ-Kmeans, rqkmeans_constrained.py for constrained clustering, and rqkmeans_plus.py for the plus variant.
- rq/generate_indices.py and rq/generate_indices_plus.py export the final SID-to-item indices and item metadata mappings used downstream.
- The checked-in data/Amazon/index/*.json and .npy files are artifacts of this stage.
6. Role of the SID artifacts
- SIDs are the central boundary object in the system.
- They bridge continuous semantic item representations and discrete token generation.
- Downstream training no longer predicts raw item IDs directly; it predicts SID tokens that correspond to catalog items through the generated index files.
7. Training-data conversion layer
- convert_dataset.py reshapes the interaction data into the sequence format expected by the recommendation LLM.
- The GPR variant injects simulated heterogeneous tokens to match the unified representation used in that line of experiments.
- This is the main handoff between the SID construction world and the model-training world.
8. Supervised fine-tuning stage
- sft.py is the main SFT entrypoint, with sft_gpr.py providing the GPR-inspired variant.
- minionerec_trainer.py contains the specialized trainer logic for the generative recommendation objective.
- LogitProcessor.py handles constrained decoding so generation stays within the valid SID/item space.
- zero2_opt.yaml indicates DeepSpeed-style distributed training support for large models.
9. Reinforcement-learning stage
- rl.py and rl_gpr.py implement the post-SFT optimization phase.
- This stage refines recommendation quality using group-based policy optimization logic and reward shaping.
- The trainer remains grounded in the SID vocabulary, so RL is optimizing over a closed item-code action space rather than open-ended text.
10. Evaluation and diagnostics
- evaluate.py computes offline ranking metrics such as HR@K and NDCG@K.
- calc.py appears to handle validity/constrained-decoding diagnostics, including detection of invalid generated items.
- evaluate.sh is the top-level evaluation wrapper for reproducing reported results.
11. Supporting model code and legacy components
- sasrec.py and SASRecModules_ori.py provide SASRec-style sequential recommendation components or baselines.
- utility.py, split.py, and merge.py support data manipulation and experiment plumbing.
- rq/models/ contains the architectural pieces used by the SID-construction models, including RQ/VQ-related layers.
12. TS-Rec extension
- The ts_rec_* files and ts_rec_data/ directory form a newer branch of the codebase focused on fine-grained semantics integration.
- This is structurally parallel to the main MiniOneRec pipeline, but aimed at the TS-Rec method described in the README announcement.
13. Infrastructure and external dependencies
- The repository is Python-based and assumes GPU training.
- Important runtime dependencies include DeepSpeed/Accelerate-style distributed training, FAISS for k-means acceleration, and k_means_constrained/polars for constrained clustering workflows.
- External LLM providers are used for text enrichment tasks; the repo supports OpenAI, DeepSeek, and MiniMax through a provider abstraction.
14. How to draw the architecture
- A useful diagram should show four major layers: data preprocessing, SID construction, model training, and evaluation.
- The key artifacts flowing between them are processed interaction CSVs, item text embeddings, SID index files, and model checkpoints.
- The main architectural constraint is that all recommendation generation is ultimately grounded in the discrete SID catalog built from item semantics.
Main entry points: Industrial_and_Scientific.emb-qwen-td.npy Emb matrices · sft.py SFT · generate_indices.py SID export · Amazon Processed data
Components 18
Data prep
Raw Amazon reviews are filtered, split, and reshaped into model-ready interaction files.
- Amazon splits · Builds train/valid/test splits and item info from Amazon review data.
data/amazon18_data_process.py - Processed data · Checked-in Amazon CSV splits and info files used by training and SID construction.
data/Amazon - Sequence convert · Reshapes interactions into the sequence format consumed by recommendation training.
convert_dataset.py
SID pipeline
Item text is embedded, clustered, and converted into discrete SID catalogs and mappings.
- Text embeddings · Turns item title/description text into dense embeddings for clustering.
rq/text2emb/amazon_text2emb.py - Emb matrices · Saved item embedding matrices used as input to SID construction.
data/Amazon/index/Industrial_and_Scientific.emb-qwen-td.npy - RQ-VAE · Alternative discrete representation model for item code learning.
rq/rqvae.py - RQ-Kmeans · Main clustering path for building discrete item codes from embeddings.
rq/rqkmeans_faiss.py - Plus variant · Variant clustering path for the plus formulation and constrained settings.
rq/rqkmeans_plus.py - SID export · Produces SID-to-item index files and item mappings for downstream training.
rq/generate_indices.py - SID catalog · Checked-in SID index, item map, and embedding artifacts used as the discrete catalog boundary.
data/Amazon/index/Industrial_and_Scientific.index.json
Training
Supervised fine-tuning and reinforcement learning over the SID vocabulary.
- SFT · Main supervised fine-tuning entrypoint for recommendation generation.
sft.py - Rec trainer · Specialized training logic for the generative recommendation objective.
minionerec_trainer.py - Decode guard · Restricts generation to valid SID/item outputs during decoding.
LogitProcessor.py - RL optimize · Post-SFT reinforcement learning stage that refines recommendation quality.
rl.py
Evaluation
Offline metrics and validity checks for generated recommendations.
- Offline eval · Computes ranking metrics such as HR@K and NDCG@K.
evaluate.py - Validity check · Checks constrained-decoding validity and generated item diagnostics.
calc.py
TS-Rec
Parallel branch for fine-grained semantic integration and TS-Rec experiments.
- TS-Rec data · Parallel TS-Rec dataset and keyword artifacts for fine-grained semantic experiments.
ts_rec_data - TS-Rec SFT · TS-Rec branch for supervised fine-tuning with semantic integration.
ts_rec_sft.py
Connections 20
- Amazon splits → Processed data: builds · Raw Amazon data is filtered and split into processed datasets.
- Processed data → Text embeddings: feeds · Processed item metadata and histories drive text embedding generation.
- Processed data → Sequence convert: feeds · Processed interactions are reshaped into model sequences.
- Text embeddings → Emb matrices: writes · Text embedding stage outputs dense item vectors.
- Emb matrices → RQ-VAE: input · Embeddings can be modeled by RQ-VAE.
- Emb matrices → RQ-Kmeans: input · Embeddings are clustered into discrete codes.
- Emb matrices → Plus variant: input · Embeddings feed the plus/constrained clustering variants.
- RQ-VAE → SID export: codes · Learned codes are exported into index mappings.
- RQ-Kmeans → SID export: codes · Cluster assignments are exported as SID mappings.
- Plus variant → SID export: codes · Plus variant assignments are exported as SID mappings.
- SID export → SID catalog: writes · SID indices and item maps are materialized as artifacts.
- SID catalog → Sequence convert: grounds · Discrete SID catalog constrains sequence conversion.
- Sequence convert → SFT: train data · Converted sequences become supervised training inputs.
- SFT → Rec trainer: uses · SFT delegates optimization to the specialized trainer.
- SFT → Decode guard: decodes with · Constrained decoding keeps outputs inside the SID space.
- SFT → RL optimize: handoff · Fine-tuned checkpoints feed the RL refinement stage.
- RL optimize → Offline eval: outputs · RL-generated recommendations are evaluated offline.
- Offline eval → Validity check: checks · Evaluation is paired with validity and constraint diagnostics.
- TS-Rec data → TS-Rec SFT: feeds · TS-Rec semantic data supports the parallel training branch.
- SID catalog → TS-Rec SFT: grounds · TS-Rec training remains tied to the SID catalog boundary.