FunnelRec - 漏斗级联推荐系统

基于 PyTorch 实现的四阶段漏斗推荐系统（召回 → 粗排 → 精排 → 重排），模拟工业界主流推荐架构。

漏斗架构

全量物品 (2000)
    │
    ▼  Stage 1: 召回 (Two-Tower 双塔)
候选 200 个
    │
    ▼  Stage 2: 粗排 (轻量 MLP + 特征交叉)
候选 50 个
    │
    ▼  Stage 3: 精排 (DeepFM)
候选 10 个
    │
    ▼  Stage 4: 重排 (MMR 多样性 + 新鲜度)
最终推荐 10 个

各阶段模型

阶段	文件	模型	说明
召回	recall.py	Two-Tower 双塔	用户塔 + 物品塔，内积计算相似度，生产环境可用 FAISS 加速
粗排	prerank.py	MLP + 特征交叉	拼接用户/物品特征，加入交叉表示，轻量快速
精排	rank.py	DeepFM	FM 一阶/二阶交叉 + Deep 深度网络，自动学习特征交互
重排	rerank.py	MMR + 新鲜度加权	Maximal Marginal Relevance 保证多样性，新鲜度策略提升新品曝光

文件结构

Recomm/
├── main.py          # 入口：生成数据 → 训练 → 推理 → 打印漏斗
├── run.sh           # 一键运行脚本
├── data.py          # 合成数据生成 + Dataset/DataLoader
├── recall.py        # Stage 1: 召回
├── prerank.py       # Stage 2: 粗排
├── rank.py          # Stage 3: 精排 (DeepFM)
├── rerank.py        # Stage 4: 重排 (MMR)
├── pipeline.py      # 串联四阶段的漏斗 Pipeline
└── README.md

环境要求

• Python 3.8+
• PyTorch 1.10+
• CUDA（可选，自动检测，无 GPU 则用 CPU）

快速开始

# 方式一：直接运行
python main.py

# 方式二：使用脚本
bash run.sh

运行结果示例

设备: cuda
用户数: 5000, 物品数: 2000

训练 召回 (Recall)    → Avg Loss: 0.5494
训练 粗排 (Pre-rank)  → Avg Loss: 0.4892
训练 精排 (Rank)      → Avg Loss: 6.2325

漏斗推荐 - 用户 0
  全量物品:    2000 个
       ↓ 召回 (双塔)
  召回候选:     200 个
       ↓ 粗排 (轻量MLP)
  粗排候选:      50 个
       ↓ 精排 (DeepFM)
  精排候选:      10 个
       ↓ 重排 (MMR多样性)
  最终推荐:      10 个

  推荐物品 ID: [89, 558, 114, 189, 594, 119, 102, 86, 22, 9]

超参数调优

在 main.py 中可调整：

参数	默认值	说明
NUM_USERS	5000	用户数量
NUM_ITEMS	2000	物品数量
EMBED_DIM	64	召回 embedding 维度
EPOCHS	3	训练轮数
BATCH_SIZE	512	批大小

在 pipeline.py 中可调整漏斗各级候选数量：

参数	默认值	说明
recall_k	200	召回数量
prerank_k	50	粗排保留数量
rank_k	10	精排保留数量
final_k	10	最终推荐数量

在 rerank.py 中可调整重排策略：

参数	默认值	说明
lambda_param	0.6	MMR 相关性 vs 多样性权衡（越大越偏相关性）
freshness_factor	0.1	新鲜度加权系数