CTR Interaction Lab

面向推广搜/广告算法岗位的可复现 CTR 实验仓库。主实验在固定分层数据划分上， 以 5 个独立模型初始化种子配对比较 DeepFM 的 baseline 与增强特征管线，并将 数据划分随机性和模型初始化随机性分离：split_seed 只生成一次 train/validation/test 索引，model_seed 只控制模型初始化和训练。

这个仓库不包含 Criteo 数据、预测文件或模型权重。实验结论仅代表本地离线数据， 不能解释为线上 CTR、收入或留存提升。

正式结果

100 万行数据、固定 72%/8%/20% 分层划分、DeepFM、5 model seeds、最多 3 epochs 并使用 early stopping：

指标	Baseline	Enhanced	变化
AUC	0.773037 ± 0.000183	0.779165 ± 0.000313	+0.006129
LogLoss	0.469653	0.464200	-0.005453
参数量	2,611,413	505,969	-80.6%
预测吞吐（5 seed 均值）	200.7k samples/s	170.4k samples/s	-15.1%

5 个配对 AUC 增量的 t 95% CI 为 [0.005676, 0.006581]。Enhanced 模型更小， 但预测吞吐下降，因而本项目不声称推理加速。正式结论、每 seed 的 200 次 stratified paired bootstrap、效率解释与探索性实验见 中文实验报告。

已固化的实验口径

• 分层 train/validation/test = 72%/8%/20%，索引具有 SHA-256 指纹；
• 词表、未知类别规则和 Min-Max 缩放器只在 train 上拟合；
• baseline 使用原始 26 个类别字段和 13 个连续字段；
• enhanced 固化最终组合：训练集低频类别合并 + 13 个零值指示器 + 13 个 训练集分位数分箱字段；
• rare_only / rare_zero / rare_bins 用于在同一划分上检查低频合并、 零值指示和数值分箱的边际贡献，避免只展示最终组合；
• 正式结论来自 DeepFM baseline/enhanced 的 5-seed 配对实验；
• LR、FM、DeepFM、DCN、AutoInt 五模型对照与特征组件消融仅作为 seed=42 的 探索性实验，不用于稳定模型排名或独立组件归因；
• 每个模型记录 AUC、Average Precision、LogLoss、Brier、ECE；
• 同时记录参数量、参数字节、训练吞吐、预测吞吐、平均 batch 时间和 CUDA 峰值显存；
• 每次运行写出 results.csv、run_metadata.json 和 split_indices.npz；默认不保存预测。

ECE 使用等宽置信度分箱。它依赖分箱数，因此不能脱离 ece_bins 横向比较。 平均 batch 时间是一次批量离线预测的总耗时除以 batch 数，不应包装成在线 P95。

数据要求

输入 Parquet 必须包含：

• label：0/1 点击标签；
• I1～I13：连续字段；
• C1～C26：类别字段。

当前本机数据可通过下面的命令核验，但数据文件不要提交：

Get-FileHash data\criteo_1M.parquet -Algorithm SHA256

已审计文件的 SHA-256 是 0B468148AECF6FA9464DEF4F2AD075B8843874F3469239AFD3504602579F767A。 该文件已经过预处理且所有字段无空值；因此项目使用“零值指示器”这一中性名称， 不能声称零值必然等价于原始缺失值。完整边界见 DATA_CARD.md。

运行

本项目在 Python 3.10 + CUDA 版 PyTorch 的 deepfm Conda 环境完成验证。 新机器可从声明文件创建环境：

conda env create -f environment.yml
conda activate deepfm

# Windows 且仓库路径含中文等非 ASCII 字符时，先启用 UTF-8 模式；ASCII 路径可省略。
$env:PYTHONUTF8 = "1"

# PyTorch 2.6+ 不再由官方 Conda channel 发布。下面是本项目实测的 CUDA 12.8 wheel。
python -m pip install torch==2.11.0 `
  --index-url https://download.pytorch.org/whl/cu128
python -m pip install -e ".[dev]"

# 快速冒烟：2万行、DeepFM、baseline/enhanced、1 epoch；不会启动完整实验。
python -m ctr_interaction_lab.benchmark `
  --data-path data\criteo_1M.parquet `
  --output-dir artifacts\smoke `
  --n-rows 20000 --models deepfm `
  --feature-variants baseline enhanced `
  --model-seeds 42 --epochs 1 --patience 1

# 正式主实验：完整100万行、DeepFM两版本、五个独立初始化种子。
python -m ctr_interaction_lab.benchmark `
  --data-path data\criteo_1M.parquet `
  --output-dir artifacts\full-1m-20260813 `
  --n-rows 0 --split-seed 2026 `
  --model-seeds 42 3407 2026 2027 2028 `
  --models deepfm `
  --feature-variants baseline enhanced `
  --rare-min-count 5 --numeric-bins 10 `
  --epochs 3 --patience 1 --batch-size 4096 --device cuda:0 `
  --save-predictions

# 组件消融：固定 DeepFM 和单一 model seed，逐项检查特征组贡献。
python -m ctr_interaction_lab.benchmark `
  --data-path data\criteo_1M.parquet `
  --output-dir artifacts\ablation-1m-seed42 --n-rows 0 --split-seed 2026 `
  --model-seeds 42 --models deepfm `
  --feature-variants baseline rare_only rare_zero rare_bins enhanced `
  --rare-min-count 5 --numeric-bins 10 --epochs 3 --patience 1 `
  --batch-size 4096 --device cuda:0 --save-predictions

# 五模型 baseline 对照：固定单一 seed，只作为探索性结果。
python -m ctr_interaction_lab.benchmark `
  --data-path data\criteo_1M.parquet `
  --output-dir artifacts\model-benchmark-1m-seed42 `
  --n-rows 0 --split-seed 2026 --model-seeds 42 `
  --models lr fm deepfm dcn autoint --feature-variants baseline `
  --epochs 3 --patience 1 --batch-size 4096 --device cuda:0

CPU 机器或其他 CUDA 版本请使用 PyTorch 官方安装选择器，不要将上述 cu128 命令原样套用。environment.yml 只创建 Conda 基础环境； PyTorch 通过官方 wheel 安装，DeepCTR-Torch 由本仓库的 pyproject.toml 依赖声明安装并锁定到官方仓库 commit 9eccef78e5810c61d6a04ddc7d96279e3db9c970。该 commit 与 PyPI 的 0.3.0 标签实现不同；runner 会核验 PEP 610 安装来源，并拒绝被 PYTHONPATH 中本地副本 遮蔽的依赖；同时校验 35 个 Python 源文件的规范化清单 SHA-256 8111a21625fe87d6a11616021f1d29659fa5ee744dd0eee62e291c62ee1e6083， 避免 commit 元数据正确但实际源码被静默修改。

results.csv 以 model × feature_variant × model_seed 为一行。例如 deepfm__baseline 与 deepfm__enhanced 使用完全相同的行索引和 model seed。 参数量、词表规模、未知类别数量以及特征配置均随行记录。

正式实验完成后，汇总跨 seed 结果，并对同一 test 样本做分层 paired bootstrap：

python -m ctr_interaction_lab.summary `
  --run-dir artifacts\full-1m-20260813 `
  --output-dir reports\full-1m-final `
  --baseline deepfm__baseline `
  --candidates deepfm__enhanced `
  --bootstrap-metrics auc logloss `
  --n-resamples 200 --confidence 0.95

汇总器输出跨 model seed 的均值/样本标准差、每个 seed 的配对 bootstrap CI，及 SUMMARY.md。reports/ 只保存可公开的聚合结果；预测只写入本地 artifacts/.../predictions/，受 .gitignore 保护。 复现实验的完整步骤和失败恢复规则见 REPRODUCIBILITY.md。

当前 17 项单元测试覆盖数据切分、train-only 预处理、指标与配对汇总、五类模型 构造，以及 DeepCTR-Torch 固定 commit/安装来源校验。另已在上述锁定依赖下完成 5,000 行、baseline/enhanced、CUDA 单 epoch 端到端冒烟；该结果只验证执行链路， 不作为公开质量结论。

结果解释与后续研究

1. 正式结论只使用固定 DeepFM、固定 split 和相同 model seed 的 baseline→enhanced 配对结果。
2. 单 seed 的 LR/FM/DeepFM/DCN/AutoInt 只用于探索交互机制，不支持稳定排名。
3. rare_only/rare_zero/rare_bins 是单 seed 非完整析因实验；组合收益不能替代 多 seed、完整消融中的独立组件归因。
4. 只在 validation 上选择低频阈值、分箱数和 early-stopping epoch；test 只用于最终评估。
5. 参数更少不代表更快；结论必须同时引用吞吐、batch 时间和峰值显存。
6. 匿名 Criteo 字段不能可靠构造 user-level GAUC，也不能声称某个字段是“用户/广告 ID”。

目录

src/ctr_interaction_lab/
  data.py       # Parquet读取与train-only预处理
  splits.py     # 固定分层split和索引指纹
  metrics.py    # AUC/AP/LogLoss/Brier/ECE与paired bootstrap
  models.py     # LR/FM/DeepFM/DCN/AutoInt统一构造
  benchmark.py  # CLI、训练、效率与运行manifest
  summary.py    # 跨seed汇总和paired bootstrap CI
tests/          # 不依赖真实数据的协议测试
reports/        # 可提交GitHub的聚合表和报告，不含逐行预测

DeepCTR-Torch 由原作者以 Apache-2.0 许可发布；本仓库只调用其公开 API，不复制 或冒充其上游源码。