Runnable examples¶
Trainer + Gin is the supported execution path. Handwritten training loops easily omit checkpoint selection, evaluation semantics, or provenance, so CLI examples come first. Direct Python snippets below are for API orientation only.
Single-model smoke test¶
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"'
A smoke test checks the code path, not model quality. Never reuse an _smoke checkpoint as a benchmark artifact.
Multiple Gin overrides¶
python genrec/trainers/hstu_trainer.py \
config/hstu/amazon.gin --split sports \
--gin 'train.seed=7' \
--gin 'train.loss_type="sampled_softmax"' \
--gin 'train.ss_sampling_strategy="local"' \
--gin 'train.num_negatives=256' \
--gin 'train.save_dir_root="out/hstu_ss/amazon/sports/s7"'
For real sampled-softmax work, start from config/hstu/amazon_ss.gin; the long override list mainly demonstrates syntax.
Change the evaluation protocol¶
python genrec/trainers/sasrec_trainer.py \
config/sasrec/amazon.gin --split beauty \
--gin 'AmazonSASRecDataset.evaluation_protocol="global_temporal"' \
--gin 'train.seed=42' \
--gin 'train.save_dir_root="out/sasrec/amazon/beauty/global_temporal/s42"'
Include the protocol in the output path so it cannot overwrite a leave-one-out results.json.
Inspect tokenizer health¶
python scripts/verify_codebook_health.py \
--kind rqkmeans \
--checkpoint out/onerec/amazon/beauty/rqkmeans/rqkmeans.pt \
--dataset-folder dataset/amazon \
--split beauty \
--encoder /data/models/Qwen3-Embedding-8B
Use --kind rqvae for RQ-VAE. Inspect per-layer usage, dead codes, maximum frequency, and full-SID collisions together.
Dry-run a result matrix¶
python scripts/run_matrix.py --help
python scripts/run_matrix.py \
--models sasrec hstu \
--splits beauty sports toys \
--seeds 42 43 44 \
--dry-run
python scripts/validate_matrix_results.py --help
python scripts/aggregate_results.py --help
Treat each script's local --help as authoritative. The validator rejects headline artifacts with incomplete protocol, metric-level, or source provenance.
Call SASRec directly¶
import torch
from genrec.models.sasrec import SASRec
model = SASRec(
num_items=100,
max_seq_len=5,
embed_dim=16,
num_heads=2,
num_blocks=2,
ffn_dim=64,
dropout=0.0,
loss_type="ce",
)
input_ids = torch.tensor([[0, 0, 4, 8, 3]])
targets = torch.tensor([[0, 0, 8, 3, 9]])
logits, loss = model(input_ids, targets)
top5 = model.predict(input_ids, top_k=5)
print(logits.shape) # [1, 5, 101]
print(float(loss), top5)
Use the trainer's full-dataloader evaluation for real metrics; this snippet has no data protocol or result writer.
Call HSTU directly¶
import torch
from genrec.models.hstu import HSTU
model = HSTU(
num_items=100,
max_seq_len=5,
embed_dim=16,
num_heads=2,
num_blocks=1,
dropout=0.0,
use_temporal_bias=True,
)
items = torch.tensor([[0, 2, 5, 7, 8]])
times = torch.tensor([[0, 100, 200, 260, 400]])
logits, _ = model(items, times)
print(logits.shape) # [1, 5, 101]
Sampled-softmax score normalization is constructed by the trainer; do not toggle one model argument and omit the associated normalization and temperature settings.
Load RQ-VAE and generate SIDs¶
import numpy as np
import pandas as pd
import torch
from genrec.models.rqvae import RqVae
df = pd.read_parquet(
"dataset/amazon/processed/beauty/item_emb_sentence-t5-xl.parquet"
)
x = torch.tensor(np.stack(df["embedding"].values), dtype=torch.float32)
model = RqVae.from_pretrained(
"out/tiger/amazon/beauty/rqvae/checkpoint_epoch_4999.pt",
map_location="cpu",
).eval()
with torch.no_grad():
sid = model.get_semantic_ids(x).sem_ids
print(sid.shape) # [num_items, num_codebooks]
Use the exact restoration and semantic-ID methods shown above, and keep the item mapping with the SID array.
Resolve SID collisions honestly¶
import torch
from genrec.modules.metrics import SemanticIdItemMapper
catalog_sids = [[1, 2], [1, 2], [3, 4]]
training_sequences = [[0, 0, 1, 2], [1, 2, 2, 0]]
mapper = SemanticIdItemMapper.from_sequences(
catalog_sids,
training_sequences,
train_holdout=2,
)
beam = torch.tensor([[[1, 2], [1, 2], [3, 4], [9, 9]]])
items = mapper.map_predictions(beam)
print(items)
Duplicate SIDs resolve to the same representative item and are deduplicated. Unknown SIDs are dropped and missing positions are filled with -1.
Inspect results.json¶
import json
from pathlib import Path
payload = json.loads(Path("out/sasrec/amazon/beauty/results.json").read_text())
for key in ["model", "split", "seed", "metrics", "config"]:
print(key, payload.get(key))
The real schema also carries source provenance. Do not use this read-only snippet to write results; generation goes through save_run_results.
OneRec stages¶
python genrec/trainers/rqkmeans_trainer.py \
config/onerec/amazon/rqkmeans.gin --split beauty
accelerate launch --config_file config/accelerate_4gpu.yaml \
-m genrec.trainers.onerec_sft_trainer \
config/onerec/amazon/sft.gin --split beauty
accelerate launch --config_file config/accelerate_4gpu.yaml \
-m genrec.trainers.onerec_grpo_trainer \
config/onerec/amazon/grpo.gin --split beauty
Before GRPO, run python scripts/check_grpo_readiness.py --help to verify the SFT checkpoint, tokenizer, and reward sparsity.