可复现与实验运行工作流¶
本页给出从代码到可进入 benchmark 的 artifact 流程。179 上的动态任务状态、卡占用和阶段优先级以 179-reproduction-runbook.md 为准;这里维护稳定的工程合同。
什么叫“可复现 cell”¶
一个结果 cell 的身份至少为:
但重跑所需 identity 还包括:
source bundle SHA256 + Git SHA
raw data manifest / preprocessing
base model & encoder revision/checksum
tokenizer artifact + C/K/geometry + item order
resolved Gin config
checkpoint selection rule
hardware/software environment
只记录 Git SHA 不够:研究 worktree 可能有未提交修改。只记录 checkpoint 路径也不够:路径内容可能被覆盖。
运行前冻结协议¶
在启动 GPU 前确定:
- 模型及具体 config 文件;
- split;
leave_one_out或global_temporal;- seed 集合;
max_seq_len、candidate universe、headline metrics;- tokenizer 是否跨下游 seed 固定;
- valid selection 和 test 刷新规则;
- 输出目录,必须隔离 protocol/model/split/seed。
推荐输出:
不要在同一目录重跑不同 protocol、C/K 或 encoder。--force 只代表允许覆盖执行,不会替你保存旧 artifact。
环境与依赖¶
安装边界见安装文档。正式运行前记录:
python -VV
python -c 'import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())'
python -c 'import transformers, accelerate, gin; print(transformers.__version__, accelerate.__version__)'
nvidia-smi
git rev-parse HEAD
git status --short
推荐从 pyproject.toml 安装对应 extras:RPG 需要 FAISS;LoRA 需要 PEFT;Parquet 需要可用 pandas engine。正式任务使用本地模型镜像,并为模型目录做 manifest/checksum;不要让 Hugging Face “最新 revision”静默改变输入。
179 的 Python 环境是 /root/workspace/code/genrec/venv。模型必须从 AFS backup 恢复到 /root/workspace/models_hub/ 后再训练,禁止直接从 AFS 路径流式读取。
数据验收¶
至少记录 review/meta 文件:相对路径、字节数、SHA-256。然后验证:
- gzip 可完整解压;
- unique item/user/interaction 数;
- mapping 与 embedding/SID row 数一致;
- train/valid/test 样本数;
- protocol cutoff 和过滤前/后用户数;
- target 不进入自己的 history,global temporal history 不跨 cutoff。
global_temporal 仍使用全 catalog metadata/SID,是 transductive catalog 设置。报告中应写“future-interaction leakage-resistant”,不要称为冷物品归纳评测。
Amazon 2023 先确认兼容 gzip 实际位于通用 Dataset 读取的 raw/<split>;不要在没有目录迁移说明时直接实例化读取 processed/<split> 的早期专用类。
tokenizer / 表征 stage¶
TIGER / LCRec / COBRA 的 RQ-VAE¶
三个 family 的几何不兼容,分别训练:
python genrec/trainers/rqvae_trainer.py config/tiger/amazon/rqvae.gin --split beauty
python genrec/trainers/rqvae_trainer.py config/lcrec/amazon/rqvae.gin --split beauty
python genrec/trainers/rqvae_trainer.py config/cobra/amazon/rqvae.gin --split beauty
训练后用同一个 encoder 和 catalog 做全量健康检查:
python scripts/verify_codebook_health.py \
--kind rqvae \
--checkpoint out/tiger/amazon/beauty/rqvae/checkpoint_epoch_4999.pt \
--dataset-folder dataset/amazon \
--split beauty \
--encoder /absolute/path/sentence-t5-xl
记录各 layer usage/dead/max-frequency、完整 tuple collision 和最大碰撞组。下游三个 seeds 推荐固定使用同一份已验证 tokenizer,以测 recommender seed 方差;tokenizer seed 方差另做实验。
OneRec RQ-KMeans¶
python genrec/trainers/rqkmeans_trainer.py \
config/onerec/amazon/rqkmeans.gin --split beauty
python scripts/verify_codebook_health.py \
--kind rqkmeans \
--checkpoint out/onerec/amazon/beauty/rqkmeans/rqkmeans.pt \
--dataset-folder dataset/amazon \
--split beauty \
--encoder /absolute/path/Qwen3-Embedding-8B
小 catalog 使用当前 K=256,C=3 主配置。健康检查中的 collapse signature 不是硬性论文结论,但 usage<80% 或单 code max_freq>10% 必须停下解释,不能直接进入 RL。
进一步碰撞报告:
RPG¶
RPG Dataset 首次构造会生成文本 embedding 和 OPQ SID。OPQ 只用 protocol training prefix 中出现的 items 拟合,cache 名已包含 protocol/PCA/factory。LOO 与 global temporal 不能共用 SID cache。
smoke test¶
在完整训练前按风险递增:
pytest -q;- Dataset 构造 + 第一条样本/一个 collated batch;
- 单 forward/backward,检查 loss 有限;
- 一小批 eval,检查 prediction shape、item范围和去重;
- 一个 epoch/极少样本的独立 debug 输出目录;
- checkpoint round-trip;
results.jsonschema/metric range。
示例只用于 smoke,不能与正式结果共目录:
python genrec/trainers/sasrec_trainer.py config/sasrec/amazon.gin \
--split beauty \
--gin 'train.epochs=1' \
--gin 'train.wandb_logging=False' \
--gin 'train.save_dir_root="out/smoke/sasrec/beauty"'
大模型可用 max_train_samples/max_eval_samples 的 trainer 才能做 sample cap;不要给不支持该参数的 trainer 传 Gin binding。
单次正式训练¶
baseline¶
python -m genrec.trainers.sasrec_trainer config/sasrec/amazon.gin --split beauty \
--gin 'train.seed=42'
python -m genrec.trainers.hstu_trainer config/hstu/amazon.gin --split beauty \
--gin 'train.seed=42'
多阶段生成模型¶
TIGER: matching RQ-VAE → tiger trainer
LCRec: matching RQ-VAE → lcrec trainer
COBRA: matching RQ-VAE → cobra trainer
OneRec: RQ-KMeans → SFT 或 CLM
SFT checkpoint_best → GRPO
RPG: Dataset 内 OPQ cache → rpg trainer
OneRec SFT 多 GPU 示例:
accelerate launch --config_file config/accelerate_4gpu.yaml \
-m genrec.trainers.onerec_sft_trainer \
config/onerec/amazon/sft.gin --split beauty
config/accelerate_4gpu.yaml 当前写死物理 gpu_ids: 3,4,5,6。在共享主机必须让它与外层分配一致,或使用显式 CUDA_VISIBLE_DEVICES/匹配配置;不能因文件名叫 4gpu 就默认可用任意四张卡。
train_onerec_grpo.sh 当前使用存在的 Amazon-2014 GRPO 配置;train_rpg.sh 按域选择配置。部分历史 run_v2_* / grid shell 编排脚本仍引用旧 sft_k256_v2.gin 名称。执行前必须检查脚本引用是否在当前 tree 存在;正式命令以当前 config/ 和 matrix registry 为准。
矩阵规划与运行¶
先 dry-run,逐条审阅 config、split、protocol、seed、save dir:
python scripts/run_matrix.py \
--preset amazon2014_20261022 \
--models sasrec hstu \
--splits beauty sports toys \
--seeds 42 43 44 \
--evaluation-protocol leave_one_out \
--dry-run
实际运行去掉 --dry-run。runner:
- 串行启动子进程;
- 只有 item-level 元数据、model/split/protocol/seed 均匹配时才 skip;使用 preset 时还要求保存的命令及配置哈希一致;否则拒绝覆盖,须换目录或显式
--force; - 可
--continue-on-error; - 可用
--log-dir重定向 cell stdout/stderr; - 给 seed/save dir/protocol 注入 Gin override;
- 不创建 RQ-VAE/RQ-KMeans/OPQ prerequisite;
- preset 检查 TIGER/LCRec/COBRA/OneRec 的 tokenizer 路径,并检查 GRPO 匹配的 SFT
checkpoint_best。
--preset amazon2014_20261022 与已发布 CSV 配方绑定,使用 LCRec 4B/4-code/seq20 和 COBRA optimized-light,不能与 --config 混用。完整 tokenizer 准备及两个协议各 81 cell 的命令见 README。不指定 preset 的 runner 保留通用/历史默认配置,不等于本次矩阵配方。
RPG 根据 split 路由 Beauty/Sports/Toys 专用 config。若使用通用模式的 --config model=path,要重新审计跨阶段 artifact。python scripts/check_benchmarks.py 检查逐种子 CSV、汇总 JSON、README、BENCHMARKS 和双语首页数字是否一致;它不启动训练。原始 checkpoint 与 embedding 缓存未随 Git 发布,随机评测模板等限制仍存在,因此重新训练不承诺逐位相同的数字。
在 179 上“一个 MCP task 一个 cell”,不要把整个矩阵包装成一个不透明长任务。可用 dry-run 得到命令,再分别提交并用相同目录/命名规则。
179 并发安全流程¶
同步源码¶
本地:
它创建 source-only tar,排除 .git、数据、模型、out、secret 和大权重,计算 SHA-256,通过带 token/header 的上传服务提交。上传本身不改远端代码;随后在 179 执行脚本打印的:
bash /root/workspace/uploads/genrec-apply-....sh \
/root/workspace/uploads/genrec-code-....tar.gz <sha256>
apply helper 会:
- 只接受 upload root 内 archive,并核对 SHA-256;
- 获取独占 source sync lock;
- 拒绝 stale bundle;
- 检查 path traversal 和 GenRec 正在运行的进程;
- staging 后 rsync,保留远端 dataset/models/out/venv;
- 记录最后 bundle、SHA 与可解析 Git SHA。
当前 rsync 没有 --delete:bundle 会新增/覆盖源码,但本地已经删除的旧文件可能继续留在远端 tree。涉及重命名/删除 importable 模块时,必须额外核对远端文件清单并通过受控变更处理,不能仅凭“apply 成功”断言远端 tree 与 bundle 完全同构。不要绕过 helper 直接覆盖训练中的 repo。
提交前只读检查¶
每次任务先同时查看远端 task list 的 running 项和 GPU 状态。显存看似空闲不代表没有另一个 session 已提交待启动任务。不得取消/kill 未知任务来抢卡。
MCP task 名:
wrapper cell ID:
每个任务必须加锁¶
scripts/run-locked-179.sh \
--gpus 2 \
--cell sasrec.beauty.leave_one_out.s42.train \
-- venv/bin/python -m genrec.trainers.sasrec_trainer \
config/sasrec/amazon.gin --split beauty \
--gin 'train.seed=42' \
--gin 'train.save_dir_root="out/matrix/leave_one_out/sasrec/beauty/seed42"'
MCP task_submit.gpu 的物理卡列表必须和 --gpus 完全相同。wrapper:
- 获取运行期间共享 source lock;
- 获取唯一 cell lock;
- 对每张物理 GPU 获取独占锁;
- 精确设置
CUDA_VISIBLE_DEVICES; - 获锁后再次用
nvidia-smi检查非协作进程; - 只放行
[Not Found]且不超过 2 GiB 的已知 auto-yield hold signature; - 注入 cell/GPU/source bundle provenance 到环境。
CPU-only 数据任务也用唯一 cell:
结果验收¶
2026-10-22 已验收的快照包含 162 个主矩阵 cell 与 6 个独立补充 cell。
逐 seed 指标、配方、源码基线、原始 artifact 路径和 SHA256 已提交到
results/matrix_20261022.csv,
汇总与源码补丁校验和见
matrix_20261022.summary.json。
162 格检查了完整的 9 管线 × 3 数据集 × 2 协议 × 3 seed 覆盖;4 码 OneRec
与 HSTU sampled-softmax 消融各自单列,不能直接对整个历史 out/ 聚合。
结构校验通过不保证 prompt 确定性:OneRec/LCRec 当前仍随机选择评测模板,
GRPO 16/18 格选回 SFT,因此微小的 SFT→GRPO 分差不能视为隔离 RL 收益。
先严格验证:
python scripts/validate_matrix_results.py out/matrix/leave_one_out \
--preset amazon2014_20261022 \
--models sasrec hstu \
--splits beauty sports toys \
--protocols leave_one_out \
--seeds 42 43 44
再聚合:
python scripts/aggregate_results.py out/matrix/leave_one_out \
--metrics Recall@5 Recall@10 NDCG@10 \
--format md
聚合器使用跨规划 seed 的总体标准差 pstdev。缺失/重复 cell 必须显式修复,不能用旧 SID 指标、不同 protocol 或不同 tokenizer 补位。
结果审计清单:
metrics是 item-level,Recall 单调;- SID 模型记录 training-only resolver 与 SID diagnostic;
config.evaluation_protocol存在;extra.evaluation_level="item";- source bundle 名/SHA、具体 Git SHA、cell/GPU 信息存在;
- best epoch 与所报告 test/checkpoint 对应;
- log 中没有 NaN、OOM 后继续或缺失 eval shard;
- tokenizer/codebook 健康报告与下游 artifact 同源。
provenance 回填¶
旧 results.json 只有在**确知**它来自某个 exact bundle 时才可用 stamp_results_provenance.py:
python scripts/stamp_results_provenance.py out/path/results.json \
--bundle-name genrec-code-....tar.gz \
--sha256 <64-lowercase-hex> \
--git-sha <7-to-40-hex> \
--cell-id model.split.protocol.s42.eval \
--physical-gpus 2
脚本原子写入并拒绝覆盖冲突值,但它无法推断历史来源。没有证据时保持 provenance 缺失并让 validator fail,比伪造 lineage 更正确。
已知非位级确定性¶
set_seed(..., deterministic=False)默认不强制 cuDNN deterministic;- CUDA kernel、FSDP/DDP reduction 和混合精度可能有数值非确定性;
- Python hash seed 在 trainer 内设置得较晚;
- DataLoader 多 worker、运行时随机负采样会消费 RNG;
- RPG graph 路径可能受 eval 前 RNG 状态影响;
- 外部 encoder/LM 若只记目录名而不记 revision/checksum,会漂移;
- basename-only embedding/text cache 不能证明输入等价。
因此 benchmark 采用多 seed 均值/总体标准差,而不是宣称跨机器 bit-exact。若研究问题需要 bit-exact,应在进程启动前设置 hash seed、开启 deterministic algorithms、固定依赖/硬件,并单独记录由此产生的性能与算子限制。
失败恢复¶
- 保留原 log、输出目录和 source provenance;
- 判断 checkpoint 是否包含 optimizer/scheduler;原始 state dict 不能完整 resume;
- 不在同一目录混入改变过的 Gin 参数;若必须恢复,记录 resume source 和 next epoch;
- 检查上游 tokenizer/cache 没有在失败期间被重建;
- 179 重提仍使用同一稳定 cell ID,wrapper 会防止并行重复;
- 成功产出后再运行 validator,不以文件存在作为完成证明。