Gin 配置与 CLI API¶
配置模型¶
当前项目使用 Gin-config,没有 DatasetConfig、TextEncodingConfig、TrainingConfig 配置层级,也没有 YAML/JSON 配置 loader。可配置对象直接是带 @gin.configurable 的函数或类。
标准执行链:
python trainer.py CONFIG.gin --split SPLIT --gin BINDING ...
-> parse_config()
-> 文本替换 {split}
-> gin.parse_config(config_content)
-> gin.parse_config(cli_bindings)
-> 调用 @gin.configurable train 函数
parse_config¶
位置与选项:
行为:
- 读取整个
config_path; - 对配置文本做全局字符串替换:
{split}→args.split; - 调用
gin.parse_config; - 对每个
--ginbinding 做同样的{split}替换,再解析; - 把
split、config_path放入进程级_RUN_CONTEXT; - 返回
argparse.Namespace(config_path, split, gin)。
返回最近一次 parse_config() 解析的 split;在未调用时返回 default。它是进程全局上下文,不适合同一进程并发运行两份不同配置。
文件不存在会抛 FileNotFoundError;Gin 语法、未知 selector、重复/非法 binding 由 Gin 抛异常。函数不捕获这些异常,也不自动验证路径、维度或 checkpoint 兼容性。
命令示例¶
# 基本训练
python genrec/trainers/sasrec_trainer.py \
config/sasrec/amazon.gin --split beauty
# 多个 override 必须重复 --gin
python genrec/trainers/hstu_trainer.py \
config/hstu/amazon.gin --split sports \
--gin 'train.epochs=100' \
--gin 'train.use_temporal_bias=False'
# 带列表/字符串的 binding;外层用单引号保护 shell
python genrec/trainers/onerec_sft_trainer.py \
config/onerec/amazon/sft.gin --split beauty \
--gin 'AmazonOneRecSFTDataset.enabled_tasks=["sidsft","title2sid"]'
{split} 是纯文本替换,不是 Python format 安全解析。若普通 prompt/正则文本本来包含同名花括号,也会被替换。
配置中的三类绑定¶
函数参数¶
selector 必须匹配当前进程已注册的 configurable。很多 trainer 的入口都叫 train;配置只能与相应 trainer 脚本一起使用,不能把 config/tiger/... 交给 SASRec trainer。
OneRec/GRAM/RPG 使用明确函数名:
train_sft.learning_rate = 8e-5
train_grpo.num_generations = 8
train_clm.max_length = 256
train_rpg.n_codebook = 32
train_gram.num_beams = 50
fit_rqkmeans.codebook_size = 256
类参数¶
只有 trainer 没有显式传同名参数时,类 binding 才决定值。
对象引用与宏¶
include "config/base.gin"
import genrec.data.amazon
train.dataset = @AmazonSeqDataset
AmazonSeqDataset.encoder_model_name = %MODEL_HUB_SENTENCE_T5_XL
@Name传 configurable/callable 引用;对应模块必须先 import。%NAME引用 Gin macro。include路径按启动工作目录解析,项目命令假设从仓库根目录运行。
config/base.gin¶
源文件:config/base.gin
当前定义五个固定路径宏:
MODEL_HUB_SENTENCE_T5_BASE
MODEL_HUB_SENTENCE_T5_XL
MODEL_HUB_QWEN3_EMBEDDING_8B
MODEL_HUB_QWEN3_1_7B
MODEL_HUB_QWEN3_4B
文件中的实际值是 /root/workspace/models_hub/... 字符串。parse_config() 没有读取 MODEL_HUB 环境变量或展开 ${MODEL_HUB} 的逻辑;换机器时应通过 CLI 重绑 macro 或维护本地配置,而不能只设置环境变量后假定自动生效。
示例:
配置文件索引¶
| 路径 | 入口 selector | 用途 |
|---|---|---|
config/sasrec/amazon.gin |
train |
Amazon 2014 SASRec |
config/sasrec/amazon2023.gin |
train |
Amazon 2023,经预处理后的 2014-compatible raw schema |
config/hstu/ |
train |
CE / sampled-softmax / Amazon 2023 compatible raw schema |
config/tiger/amazon/rqvae.gin |
train |
TIGER 上游 RQVAE |
config/tiger/amazon/tiger.gin |
train |
TIGER 推荐器 |
config/lcrec/ |
train |
RQVAE 与 LCRec |
config/cobra/ |
train |
RQVAE、sparse-only、mixed variants |
config/onerec/amazon/ |
fit_rqkmeans / train_sft / train_grpo / train_clm |
OneRec 三阶段与 CLM |
config/rpg/ |
train_rpg |
Beauty/Sports/Toys 数据集特定配置 |
config/notellm/amazon.gin |
train |
NoteLLM 对称 GCL + 可选 CSFT |
config/gram/amazon/gram.gin |
train_gram |
GRAM |
Amazon 2023 baseline 的实际路由
sasrec_trainer.py 与 hstu_trainer.py 没有构造 genrec.data.amazon2023.Amazon2023SASRecDataset,而是继续使用 AmazonSASRecDataset / AmazonHSTUDataset。prepare_amazon2023() 会写出 Amazon 2014-compatible gzip;DATASET_CONFIGS 当前登记 books、arts_crafts_and_sewing。配置运行前必须先生成这些 raw 文件,新增 category 还须增加文件名映射。
Enum binding¶
QuantizeForwardMode 用 @gin.constants_from_enum 注册,可在 RQVAE 配置中写:
train.vae_codebook_mode = %genrec.models.rqvae.QuantizeForwardMode.GUMBEL_SOFTMAX
train.vae_codebook_last_layer_mode = %genrec.models.rqvae.QuantizeForwardMode.SINKHORN
合法值为 GUMBEL_SOFTMAX、STE、ROTATION_TRICK、SINKHORN。QuantizeDistance 没有同样的 Gin constants decorator。
常见错误¶
No configurable matching ...:缺少import genrec.data...,或把配置交给了错误 trainer。- override 没生效:selector 写错,例如
train与train_sft混用;查函数装饰器和配置原绑定。 - 路径仍指向旧 split:某个字符串没有
{split}或被硬编码;用rg检查 config。 - 列表被 shell 拆开:外层用单引号包住整个 binding。
- 相同维度 checkpoint 能加载但语义错误:Gin 只配置形状,不验证 encoder/codebook provenance。
- 尝试
load_config_from_file():不存在该 API;配置只在 CLIparse_config()中解析。 - split 与输出目录不一致:检查解析后的配置与
results.json。NoteLLM 已同时绑定train.split和AmazonNoteLLMDataset.split,标准--split sports会更新两处。