Getting started¶
This path produces one auditable SASRec run before introducing the dependencies of generative pipelines. Run commands from the repository root.
1. Install¶
For CUDA, optional dependencies, and local model mirrors, see Installation.
2. Prepare Amazon 2014 Beauty¶
SASRec and HSTU read the raw gzip files directly, so prepare them explicitly:
Expected files:
The preparation script verifies gzip CRC and SHA-256 and writes atomically. Existing files are revalidated.
3. Run a baseline¶
python genrec/trainers/sasrec_trainer.py \
config/sasrec/amazon.gin --split beauty \
--gin 'train.wandb_logging=False'
The default may train for up to 300 epochs with early stopping on validation Recall@10. For a code-path smoke test, isolate the output and shorten the run:
python genrec/trainers/sasrec_trainer.py \
config/sasrec/amazon.gin --split beauty \
--gin 'train.epochs=1' \
--gin 'train.patience=1' \
--gin 'train.wandb_logging=False' \
--gin 'train.save_dir_root="out/_smoke/sasrec/beauty"'
Do not publish smoke-test metrics. A normal output directory contains best_model.pt, a timestamped log, and results.json; the JSON artifact, not a copied console number, is the aggregation input.
4. Choose a pipeline¶
SASRec / HSTU¶
python genrec/trainers/sasrec_trainer.py config/sasrec/amazon.gin --split beauty
python genrec/trainers/hstu_trainer.py config/hstu/amazon.gin --split beauty
python genrec/trainers/hstu_trainer.py config/hstu/amazon_ss.gin --split beauty
HSTU cross-entropy and sampled-softmax runs are different experiments; keep their outputs and labels separate.
RQ-VAE → TIGER / LCRec / COBRA¶
Each downstream model has its own RQ-VAE geometry. Train and load the matching checkpoint:
# TIGER
python genrec/trainers/rqvae_trainer.py config/tiger/amazon/rqvae.gin --split beauty
python genrec/trainers/tiger_trainer.py config/tiger/amazon/tiger.gin --split beauty
# LCRec
python genrec/trainers/rqvae_trainer.py config/lcrec/amazon/rqvae.gin --split beauty
python genrec/trainers/lcrec_trainer.py config/lcrec/amazon/lcrec.gin --split beauty
# COBRA
python genrec/trainers/rqvae_trainer.py config/cobra/amazon/rqvae.gin --split beauty
python genrec/trainers/cobra_trainer.py config/cobra/amazon/cobra.gin --split beauty
Check the Sentence-T5 path in config/base.gin. Do not, for example, pass TIGER's 3×256 tokenizer checkpoint to a COBRA 3×32 pipeline.
TIGER currently uses ordinary beam search. It does not use Trie-constrained decoding; catalog-invalid SIDs are removed during item mapping.
RQ-KMeans → OneRec¶
# Stage 1: item embeddings + 3×256 residual K-Means
python genrec/trainers/rqkmeans_trainer.py \
config/onerec/amazon/rqkmeans.gin --split beauty
# Stage 2a: multi-task SFT
accelerate launch --config_file config/accelerate_4gpu.yaml \
-m genrec.trainers.onerec_sft_trainer \
config/onerec/amazon/sft.gin --split beauty
# Stage 2b: alternative CLM training, not a required post-SFT stage
python -m genrec.trainers.onerec_clm_trainer \
config/onerec/amazon/clm.gin --split beauty
# Stage 3: GRPO, which depends on an SFT checkpoint
accelerate launch --config_file config/accelerate_4gpu.yaml \
-m genrec.trainers.onerec_grpo_trainer \
config/onerec/amazon/grpo.gin --split beauty
The default pipeline expects local Qwen3-Embedding-8B and Qwen3-1.7B assets. Read the OneRec page before changing rewards, codebook size, collision policy, or checkpoint paths.
RPG / NoteLLM / GRAM¶
python -m genrec.trainers.rpg_trainer \
config/rpg/amazon.gin --split beauty
python -m genrec.trainers.notellm_trainer \
config/notellm/amazon.gin --split beauty
python -m genrec.trainers.gram_trainer \
config/gram/amazon/gram.gin --split Beauty
RPG requires FAISS. NoteLLM's default LoRA path requires PEFT; its config binds
{split} to both the trainer and dataset, so the standard --split flag is
sufficient. GRAM consumes paper-style preprocessed assets under dataset/gram;
the regular Amazon adapter does not build every lexical-index and similar-item
artifact.
5. Gin overrides¶
The first positional argument is a Gin config. --split first replaces literal {split} placeholders in its text; repeated --gin arguments are then parsed as overrides:
python genrec/trainers/hstu_trainer.py config/hstu/amazon.gin \
--split sports \
--gin 'train.seed=7' \
--gin 'train.batch_size=64' \
--gin 'train.wandb_logging=False'
The configurable is not always named train: OneRec uses train_sft, train_clm, and train_grpo; RPG uses train_rpg; GRAM uses train_gram. Copy the selector from the actual config.
6. Evaluation contract¶
The default protocol is leave_one_out; compatible Amazon adapters also support global_temporal. Separate results by protocol, seed, and metric level.
For semantic-ID generators, only item-level metrics are suitable as headlines:
SID-tuple exact match, NoteLLM in-batch recall, and sampled-negative metrics are diagnostics, not cross-model headline results. See Evaluation system.
7. Before a matrix run¶
python scripts/run_matrix.py --help
python scripts/validate_matrix_results.py --help
python scripts/aggregate_results.py --help
Dry-run the matrix before using a remote experiment cell. Runs on the primary 179 host must follow the concurrency-safe reproduction runbook.