# 搜广推开源项目实战清单

> 写给会一点 Python、想把推荐系统知识变成实际结果的你。
>
> 版本：2026-10-30 第 2 版（初学者修订）。配套阅读：[推荐系统机器学习学习指南](推荐系统机器学习学习指南.md)。
>
> 这是一份工具地图。第一次只选一条路线、一个数据集、一个主要框架，先完成小实验，再决定下一步。

---

## 0. 先选一件你想做的事

想象你要开一家小店：教程像菜谱，模型库像厨房工具，数据集像食材，工业框架像大型后厨。先做出一道菜，再研究怎样同时服务一万人。

| 你想做什么 | 第一步 | 做到什么算完成 |
|---|---|---|
| 给朋友推荐电影 | 学习指南第 5.3 节小例子 → MovieLens 100K → 热门推荐、ItemCF | 输出一张片单，解释推荐原因，算出 Recall/NDCG |
| 让模型学习用户偏好 | 从 Torch-RecHub 或 RecBole 中选一个，跑一个小示例 | 说清输入、标签、切分和指标，再与简单基线比较 |
| 给一次广告曝光预测点击概率 | 先用 FuxiCTR 的 tiny 示例熟悉流程，再用小规模曝光数据 | 跑通 LR/DeepFM 对照，报告 AUC、LogLoss 和校准限制 |
| 做一个能搜资料的小搜索器 | 小语料 BM25 → Pyserini；语义模型可用 Sentence-Transformers | 输入查询，返回相关文本，检查前几个结果为什么对或错 |

**如果你还不知道选哪条，先选电影推荐。** 热门榜和 ItemCF 可以用普通 CPU 完成，数据字段也容易理解。先按学习指南第 15 章固定评估规则，再考虑框架；不必一开始就部署服务。

第一次实验可以很小：一个脚本、一份配置、一张对比表、一段错误分析。能把结果讲明白，已经是扎实的第一步。

## 1. 搜、广、推：像三种不同的导购

- **搜索**：顾客主动说“我要一双跑鞋”。系统先理解这句话，再找相关商品。
- **推荐**：顾客没提问，你根据已知兴趣猜“这些东西他可能想看”。
- **广告**：既要匹配用户需求，还涉及广告主预算、出价和计费。这里的入门项目只研究点击预测，不涉及真实投放。

三者都会用向量、特征、排序和实验，但一道题做得好，不代表另外两道题也做对了。

| 维度 | 推荐 | 搜索 | 广告 |
|---|---|---|---|
| 常见输入 | 历史行为、用户与场景特征 | 查询 query、文档与上下文 | 用户、广告、场景与商业约束 |
| 入门问题 | 用户接下来可能喜欢什么 | 哪篇文档回答了这个查询 | 这次曝光会不会被点击 |
| 常见离线指标 | Recall@K、NDCG@K | MRR@K、NDCG@K、Recall@K | AUC、LogLoss、校准误差 |
| 进阶时再考虑 | 冷启动、多样性、长期体验 | 查询理解、混合检索、多阶段排序 | 转化、多任务、延迟反馈、竞价机制 |

AUC 衡量正负样本的区分能力，不是用户满意度，也不能换算为线上点击率。数据切分、候选集合和标签不同，分数就不是同一张考卷上的成绩。

术语先认这几个：**baseline** 是用来比较的简单基线；**pipeline** 是数据到结果的一串步骤；**demo** 是演示；**serving** 是把模型接到实际请求中的服务。看到这些英文，不需要额外学一门新理论。

---

## 2. 推荐系统：从一张电影片单开始

### 2.1 教程和轻量模型库，各自怎么用

#### fun-rec：边看地图，边走一小段

- 入口：[GitHub](https://github.com/datawhalechina/fun-rec) · [在线阅读](https://datawhalechina.github.io/fun-rec/)。
- 它能帮什么：用中文串起推荐系统的基本流程，并提供算法与项目材料。
- 第一次做什么：选与当前进度对应的热门推荐、协同过滤或项目数据处理部分，先复述“输入什么、输出什么”。
- 下一步：把一个例子改成自己的数据，检查字段与评估逻辑，而不是把所有 Notebook 顺序点一遍。
- 注意：教程不等于一个装好就能上线的完整平台。章节会更新，代码示例也可能使用不同数据与依赖，不要默认它们可以直接拼起来。

#### Torch-RecHub：先试一把工具，再换另一把

- 入口：[仓库与使用示例](https://github.com/datawhalechina/torch-rechub)。
- 它能帮什么：提供 PyTorch 推荐模型、训练器和示例，覆盖召回、排序、多任务等方向。
- 第一次做什么：选一个排序示例，弄清特征列、标签、训练集和验证集如何传给模型。先复现一个小结果，再比较 LR 与 DeepFM 等单目标模型。
- 再往后：有真实历史序列时再加 DIN；有点击与转化标签时再研究 ESMM。
- 注意：**DeepFM、DIN、ESMM 不是拿同一份单标签表就能无条件公平对比的三个选项。** DIN 需要历史行为及其与候选的表示关系；ESMM 面向点击/转化关联任务。比较时应写清新增数据和特征，必要时做消融。
- 工程选做：仓库提供 ONNX 导出示例，但具体模型能否导出、运行在哪种设备，要按所用版本验证。导出后还要检查同一输入的原模型与 ONNX 输出是否一致，以及预处理是否一致。一个模型文件不是完整服务。

普通笔记本先选 CPU 和小批量数据。官方主分支的 Python/PyTorch 要求可能比旧教程高；**代码、依赖和文档尽量选同一版本**，不要把旧安装命令与新 API 混用。

#### 王树森《推荐系统》课程材料：回头看原理

- 入口：[课程仓库](https://github.com/wangshusen/RecommenderSystem)。
- 用法：带着问题查课程、图示和对应材料，例如“双塔为什么能提前算好物品向量”。
- 注意：课程资料不等于每个讲过的模型都有一份现成可运行脚本；先看目录与依赖，再决定动手范围。

### 2.2 想做统一实验，再看这些

| 项目 | 它适合帮你做什么 | 第一次只做一件事 |
|---|---|---|
| [RecBole](https://github.com/RUCAIBox/RecBole) | 在统一数据接口和评估设置下做推荐算法实验 | 跑官方小数据示例，再检查候选、采样和切分配置 |
| [Recommenders](https://github.com/recommenders-team/recommenders)（原 Microsoft Recommenders） | 查数据处理、模型和评估 Notebook | 带着一个问题读一个 Notebook，例如“如何排除已见物品” |
| [TensorFlow Recommenders](https://github.com/tensorflow/recommenders) | 在 TensorFlow 生态学习召回、排序 | 如果已经用 TF，跑一个双塔例子；暂时不为它切换技术栈 |
| [PaddleRec](https://github.com/PaddlePaddle/PaddleRec) | 在飞桨生态学习推荐模型 | 选一个与你已有环境匹配的单机示例 |

RecBole 提供多种评估配置，框架默认值不一定符合你的实验目标。复现论文用论文协议；练习未来推荐则按学习指南第 15 章检查时间与候选。

关于使用条款，RecBole 的 [LICENSE](https://github.com/RUCAIBox/RecBole/blob/master/LICENSE) 标为 MIT，而 [README 的 License 段](https://github.com/RUCAIBox/RecBole#license)另写了学术用途说明。这两处文字需要分别注意，不能仅凭页面上的许可证徽标或本清单断定用途范围；数据集也有独立条款。这里不对不一致之处作许可解释。

### 2.3 大型后厨：先知道名字，用到时再学

| 项目 | 主要关注什么 | 适合什么时候读 |
|---|---|---|
| [EasyRec](https://github.com/alibaba/EasyRec) / [TorchEasyRec](https://github.com/alibaba/TorchEasyRec) | 大规模推荐的特征配置、训练和部署流程 | 已能独立完成单机实验，想理解工业组织方式 |
| [Angel](https://github.com/Angel-ML/angel) | 参数服务器与分布式机器学习 | 开始研究参数如何跨机器存储与更新 |
| [TorchRec](https://github.com/meta-pytorch/torchrec) | 大规模 Embedding 分片、模型并行和分布式训练 | 单卡或单机已经成为具体瓶颈 |
| [HugeCTR](https://github.com/NVIDIA-Merlin/HugeCTR) | 面向 CTR 的高吞吐 GPU 训练 | 有匹配的 NVIDIA GPU 环境，并有规模实验需求 |

这些项目解决的是“数据和模型已经很大以后怎么办”。初学阶段先把一台机器上的结果做可靠。

---

## 3. 搜索：让机器帮你找对那篇文章

### 3.1 先让关键词搜索工作起来

假设你整理了几百篇学习笔记，想搜“负采样会影响什么”。可以按下面的顺序做：

1. **BM25 关键词检索**：看查询词与文档词是否匹配，同时考虑词频和文档长度。先有这个基线。
2. **双编码器语义检索**：分别把查询和文档编码成向量，用相似度找候选，尝试补上“措辞不同但意思相近”的结果。
3. **混合检索**：组合两路候选，检查它们是否真的互补。
4. **精细重排（选做）**：只对少量候选做更细的相关性判断。

关键词和向量像两种找书方法：一种按书里的用词找，一种按学到的语义表示找。哪一种更好，要看查询、语言、领域和模型。

| 项目 | 适合的步骤 | 入门时的注意点 |
|---|---|---|
| [Pyserini](https://github.com/castorini/pyserini) | BM25、稠密与混合检索实验 | Lucene 路线有 Java 依赖，先按官方安装说明跑小语料 |
| [Sentence-Transformers](https://github.com/huggingface/sentence-transformers) | 预训练双编码器召回、交叉编码器重排 | 先选匹配语言的模型；用预训练模型推理不等于已完成训练 |
| [BEIR](https://github.com/beir-cellar/beir) | 在不同检索数据集上评估 | 它是基准与工具集合；先选一个较小数据集，别下载全套 |
| [ColBERT](https://github.com/stanford-futuredata/ColBERT) | 理解多向量表示与延迟交互 | 属于进阶；保留 token 级向量，有自己的索引和检索流程 |

**双编码器与交叉编码器怎么区分？** 前者像双方先各写一张简介，匹配时比较简介，文档向量可以预计算；后者把查询和文档一起仔细读，通常更适合少量候选。ColBERT 的延迟交互又是另一种折中，不要把三者当成同一种模型。

**先过环境这一关**：本次查阅时，[Pyserini 安装说明](https://github.com/castorini/pyserini#-installation)列出 Python 3.12、Java 21 等要求；将来可能更新，按选定版本核对。几百行查询代码不代表环境、模型下载与大索引准备也只要几分钟。

混合时先用 RRF（倒数排名融合）通常更容易控制尺度：按各路排名位置取倒数后相加，例如 $score(d)=\sum_r 1/(c+rank_r(d))$。其中 $r$ 是检索路，$c>0$ 是平滑常数，未被某路召回的文档在该路贡献 0。原始 BM25 分数和向量相似度不宜直接相加；加权融合需要在验证查询上调权重。

### 3.2 第一份搜索报告，怎么做才不空泛

先选几十个查询和一份固定的小语料，每个查询有事先确定的相关文档标注；用于调参的查询与最终测试查询分开。你可以先人工标一批，报告中说明标注标准与规模。自己造的小数据用于学习流程，不能称为标准基准成绩。

- **最小结果**：BM25 的前 10 个文档、NDCG@10、几条典型错误查询。
- **增加一个变化**：加入预训练向量召回，比较它与 BM25 的命中差异，再尝试融合。
- **记录成本**：首次建索引耗时、索引体积、模型加载后查询延迟；固定硬件、候选数、批大小和查询集。
- **进阶数据**：再选 BEIR 的一个子集，或 MS MARCO Passage 的明确版本与官方评估划分。随意截取的语料子集会改变任务难度，分数不能直接对比全量榜单。

MRR@10 只关注第一个相关结果出现的位置：第一位命中得 1 分，第二位命中得 1/2，第十位以后才命中或没有命中得 0；最后对查询平均。多个相关结果的排列质量，则可一起看 NDCG@10。

### 3.3 什么时候需要搜索引擎或向量数据库

当你开始遇到增量更新、持久化、过滤和并发请求需求时，再挑基础设施：

| 项目 | 它主要是什么 | 初学时先分清 |
|---|---|---|
| [Faiss](https://github.com/facebookresearch/faiss) | 向量相似度检索库 | 有索引，不是一个开箱即用的完整数据库服务 |
| [Qdrant](https://github.com/qdrant/qdrant) / [Milvus](https://github.com/milvus-io/milvus) | 向量数据库 | 存取、过滤、更新与服务能力需要按版本、部署模式检查 |
| [OpenSearch](https://github.com/opensearch-project/OpenSearch) / [Elasticsearch](https://github.com/elastic/elasticsearch) | 搜索与分析引擎 | 可以承载检索服务，但不替你定义相关性标签与评估 |
| [Vespa](https://github.com/vespa-engine/vespa) | 搜索、推荐与多阶段排序平台 | 系统能力多，适合有明确服务需求后深入 |

小数据先精确计算向量相似度即可。换数据库不会自动提高模型对语义的理解。

---

## 4. 广告 CTR：猜这次会不会点开

把一行数据想成一次广告展示的快照：谁、什么广告、什么场景、之后是否点击。模型只能读取展示时已经知道的信息，不能读取之后发生的结果。

### 4.1 先跑一个小闭环，再加复杂模型

- [FuxiCTR](https://github.com/reczoo/FuxiCTR)：适合用配置组织 CTR 数据处理、模型与对照实验。先照官方 tiny 示例跑一个模型，再梳理配置和真实输入。模型多，不要求逐个尝试。
- [DeepCTR](https://github.com/shenweichen/DeepCTR) / [DeepCTR-Torch](https://github.com/shenweichen/DeepCTR-Torch)：可用于查经典特征交互和兴趣模型的实现；选与你当前框架一致的一版。
- [Monolith](https://github.com/bytedance/monolith)：适合读动态 Embedding 与在线训练的设计。本次查阅时仓库显示已于 2025-10-13 归档，作为设计阅读材料，不列为入门项目基座。

建议顺序是 **LR → DeepFM → 有合适历史数据后再试 DIN**。先问“多加的特征是否有效”，再问“换结构是否有效”。

DIN 的历史必须截止于当前曝光之前。还要检查历史行为与候选是否有可对齐的字段或表示：不能因为都有“ID”两个字，就把商品 ID、广告 ID 当成同一套编号。Alimama 多表数据尤其需要先读字段说明、检查关联键和缺失率。

### 4.2 数据集：先弄清每行是什么

| 数据集 | 适合练什么 | 开始前确认什么 |
|---|---|---|
| [Alimama 展示广告点击率数据](https://tianchi.aliyun.com/dataset/56) | 曝光点击、用户/广告属性、多表关联 | 数据说明、时间范围、表的关联键、历史行为字段；先做小规模处理 |
| [Criteo 1TB Click Logs](https://ailab.criteo.com/download-criteo-1tb-click-logs-dataset/) | 稀疏类别特征、哈希与规模实验 | 含 24 天数据，13 个整数特征、26 个类别特征；正负样本都按不同概率采样 |
| [Avazu](https://www.kaggle.com/c/avazu-ctr-prediction/data) | 时间、站点、应用与设备类特征 | 下载权限、公开标签范围、时间字段与类别基数 |

Criteo 1TB 不适合第一次就全量下载。官方说明指出正、负样本均经过采样，不能只写成“抽掉了部分负例”。在这个数据上做离线概率预测，不代表已经恢复原始业务的真实 CTR。

第一次可以用 tiny 数据检查代码；换真实数据后，先选连续时间窗口、再按时间划分，记录子集规模和规则。不要先随机抽几行，把时间顺序和标签比例改掉了却没有记录。

### 4.3 一份能讲清楚的 CTR 实验

1. **定义一行与一个标签**：曝光为一行，窗口结束后的点击为 1、未点击为 0。若数据本身已给定标签与划分，先读说明再决定是否采用。
2. **留出验证与测试**：未来预测优先按时间；类别字典、归一化参数等在训练集上拟合。验证/测试里的新类别使用事先定义的未知值。
3. **先训练 LR**：检查缺失、稀有类别、样本比例和明显泄漏。
4. **再训练 DeepFM**：先保持输入特征和切分一致，记录超参数搜索预算，避免某个模型被调了几十次而另一个只跑默认值。
5. **报告 AUC 与 LogLoss**：再画“预测概率分桶与实际点击比例”的可靠性曲线。GAUC 选做，须说明按用户还是请求分组、如何加权、排除了多少单标签组。
6. **做一次消融**：例如去掉一类历史统计，看效果怎样变化。统计只能使用曝光前已发生且线上可得的信息。

**校准的边界**：如果校准集同样来自有偏采样数据，校准后最多说明概率更贴合该采样分布。恢复原曝光分布还需要采样机制或代表性数据，不能凭一条好看的曲线宣布“真实 CTR 已经准确”。

**部署选做**：先保存原模型并跑离线预测；需要接口时再做最小服务。ONNX 是可选路径，需要验证算子支持、输出一致性与预处理。延迟测试要写清硬件、是否预热、批大小和是否包含特征处理。

位置特征也不是消除偏差的按钮。它可能帮助拟合已有展示机制，但不自动恢复用户的无偏偏好；加入时应说明预测阶段能否知道位置，以及你想预测哪种展示条件下的点击。

---

## 5. 生成式推荐：先了解新路线，再决定要不要上车

下面不是入门必做清单。先完成一个传统推荐或检索基线，再看它们替换了哪一步、引入了什么成本。

| 项目 | 先读什么 | 不要误会什么 |
|---|---|---|
| [OpenOneRec](https://github.com/Kuaishou-OneRec/OpenOneRec) | 任务定义、数据格式、模型与基准说明 | 模型推理、微调和从头训练是不同工作量；较小的参数版本也不等于普通笔记本能轻松训练 |
| [Meta Generative Recommenders / HSTU](https://github.com/facebookresearch/generative-recommenders) | 序列转导任务和 HSTU 结构 | 它不简单等同于“像语言模型那样逐 Token 生成语义 ID” |
| [RQ-VAE-Recommender](https://github.com/EdoardoBotta/RQ-VAE-Recommender) | 语义 ID 如何构建、如何映射回物品 | 这是 TIGER 类思路的第三方实现，不等于原论文官方复现结果 |
| [OneRec-Think](https://github.com/wangshy31/OneRec-Think) | 显式推理与推荐任务如何结合 | 解释文字合理，不代表推荐指标或真实体验已改善 |
| [Agent4Rec](https://github.com/LehengTHU/Agent4Rec) | 如何用语言模型模拟用户 | 模拟用户不是实际用户，模拟收益不能当作线上实验结果 |

语义 ID 路线像给商品编一串可以生成的地址：先生成地址，再查到商品。HSTU 等序列转导路线关注的建模与计算方式并不完全一样；“生成式推荐”不能只画成一个统一结构。进一步解释见学习指南第 16.4 节与 [HSTU 原论文](https://arxiv.org/abs/2402.17152)。

论文导航可看 [LLM4Rec-Awesome-Papers](https://github.com/WLiK/LLM4Rec-Awesome-Papers)。把它当检索入口，具体结论回到原始论文、数据与代码；这里不保证列表覆盖全部新工作。

---

## 6. 数据不是越大越好，先选能解释清楚的

| 数据 | 适合起步的范围 | 学到什么 | 容易误读的地方 |
|---|---|---|---|
| [MovieLens 100K](https://grouplens.org/datasets/movielens/100k/) | 先用这个固定小版本 | 热门、ItemCF、矩阵分解与 Top-K 评估 | 评分不是曝光；低分不是未点击 |
| [Amazon Reviews 2023](https://amazon-reviews-2023.github.io/) | 一个类目、明确时间与过滤规则的子集 | 序列、文本与商品内容 | 评论不是全部浏览或曝光；“没评论”不是不喜欢 |
| [KuaiRec](https://kuairec.com/) | 先看 small matrix 及数据说明 | 反馈偏差与评估 | 小矩阵接近全观测，不表示整个数据集或所有真实用户都全观测 |
| Criteo / Alimama / Avazu | 先 tiny 或可控的时间子集 | CTR、稀疏特征和样本构造 | 采样、曝光机制、标签可用范围各不相同 |
| BEIR / [MS MARCO](https://microsoft.github.io/msmarco/) | 一个明确的数据集或版本 | 查询—文档相关性与检索评估 | 未标注文档不一定真的不相关，子集成绩也不同于全量成绩 |

选定数据后，先写五句话：每行是什么、预测什么、何时预测、标签何时可得、哪些数据会被排除。答不清这五句，先别急着训练。

竞赛可以从天池、Kaggle、RecSys Challenge、KDD Cup、WSDM Cup 等往届题目里选一个。先确认数据仍可获取、评估说明完整，再看优秀方案。复现时遵循赛题协议，并单独讨论它与未来上线任务的差别；不保证所有赛题都按时间划分。

---

## 7. 四条项目路线：选一条，做到一个明确的终点

### 路线 A：电影推荐，建议作为第一个项目

- **最小版**：按学习指南第 15 章，使用 MovieLens 100K，完成热门推荐、ItemCF、Recall@10、NDCG@10 和一个用户的推荐解释。
- **升级一项**：加入 BPR-MF；需要框架时，Torch-RecHub 与 RecBole 二选一。保持候选、过滤和评估用户一致。
- **再选做**：内容兜底、类别打散、交互 demo。把深度排序与服务化留到有具体问题时。
- **交付物**：可运行命令、评估协议、两到三组实验结果、失败案例。MovieLens 上构造的分类负例不能包装成真实 CTR 训练。

### 路线 B：广告点击预测，适合想练特征与实验的人

- **最小版**：FuxiCTR 小示例熟悉配置，再在可控曝光数据上完成 LR 与 DeepFM 对比。
- **升级一项**：做特征消融和可靠性曲线；数据满足条件时再加 DIN。
- **再选做**：校准、分人群误差分析、最小推理接口；分别说明这些步骤验证了什么。
- **交付物**：字段字典、切分规则、AUC/LogLoss 对比、错误分析和概率解释边界。

### 路线 C：学习笔记搜索，适合想直观看到结果的人

- **最小版**：固定小语料与查询标注，完成 BM25，返回前 10 个结果并评估。
- **升级一项**：用 Sentence-Transformers 加预训练向量召回，再比较与融合。
- **再选做**：交叉编码器或 ColBERT、多查询分层评估、标准基准与服务。
- **交付物**：查询 demo 或命令、相关性标注、质量与成本对比、几类失败查询。

### 路线 D：生成式推荐，作为研究选题的起点

- **最小版**：选一个方法，画清输入、目标、解码和合法物品映射，再检查官方例子所需资源。
- **升级一项**：在资源允许时做小规模推理或训练，与相同任务和候选规则下的传统基线比较。
- **注意**：OpenOneRec 的指令任务、HSTU 的序列任务、语义 ID 检索任务不一定相同，不能拿任意一张 SASRec 成绩表直接对比。
- **交付物**：任务定义、资源记录、复现范围和局限。只读了论文就写阅读报告；跑了推理就写推理结果，二者都不称为完成训练复现。

## 8. 下载仓库前，先问这七个问题

1. **它解决的是我现在的问题吗？** 缺一个电影推荐基线，就先不解决多机训练。
2. **示例和数据能拿到吗？** 数据说明、标签、切分和评估入口比 star 数更有用。
3. **我的机器能跑最小例子吗？** 看 Python、框架、Java、系统、显卡与磁盘要求；macOS 的 MPS 不能直接替代 CUDA。
4. **能固定一个可用版本吗？** 记录提交或 release、依赖与运行命令；有新提交不保证旧例子还能运行，稳定老项目也不一定不可用。
5. **出了问题有路可查吗？** 看文档、测试与 issue；回复速度是参考，不是唯一判断标准。
6. **模型与评估能否替换、能否解释？** 指标一出来，就应知道候选范围、负例、过滤和平均方式。
7. **代码、数据、权重的条款分别是什么？** 分开读各自说明，不把仓库许可自动套给第三方数据与模型。

对于学习项目，先做到离线可复现；需要展示或理解延迟时再做服务。部署是另一个值得学的环节，不是所有算法实验的入场券。

## 9. 卡住时，先排查这些

| 看到的现象 | 先想一想 | 下一步 |
|---|---|---|
| 热门榜竟然比深度模型好 | 是数据少、训练没收敛，还是切分/过滤不同？ | 固定评估，抽查一个用户和一条样本，再看模型 |
| 随机切分很好，时间切分变差 | 是否发生分布变化，或随机实验用了预测时不可得的信息？ | 写清任务；未来预测用时间切分，评分补全可保留相应随机协议 |
| AUC 好，概率却普遍偏高 | 排序能力与概率数值是两回事；是否改变了类别比例？ | 看采样机制与代表性校准数据，不把 AUC 当概率准确率 |
| 抽了负例，指标明显提高 | 是否把全库考试换成了少量候选考试？ | 固定候选与采样规则；难负例也可能改变类内分布 |
| 加了位置特征就涨分 | 模型可能更会拟合旧展示策略 | 检查位置是否线上可得，不据此宣布曝光偏差已消除 |
| CTR 涨了，就想说系统更好 | 是否损害了满意度、投诉、留存或转化？ | 报告离线结论边界；线上判断需要真实且设计合理的实验 |
| 模型能导出，却服务结果不同 | 编码字典、缺失值、归一化、截断是否一致？ | 对同一输入逐步核对预处理与模型输出 |

“只保留曝光样本”是 CTR 的常见任务定义，不自动意味着模型只学到了曝光偏好；真正的问题是日志受旧策略选择影响，对未曝光物品的结论缺少直接依据。也别把未曝光物品全部补成标签 0。

## 10. 第一份实验报告，只要说清这些

- **问题**：例如“给训练期有历史的用户推荐未来高评分、且没评过的电影”。
- **数据与协议**：版本、时间边界、标签、候选、过滤、有效与排除用户数。
- **基线与变化**：先有什么，只改变了什么，验证集怎样选参数。
- **真实结果**：指标、耗时、几条成功和失败案例；没跑的填“未运行”，不编示例成绩。
- **复现入口**：环境、命令、配置、随机种子和数据处理步骤。
- **限制与下一步**：哪些结论只适用于当前子集，下一次实验要验证哪个具体猜想。

写完后问自己：“别人拿到同一数据和配置，能不能重做这张表？我能不能解释一条推荐为什么出现？”能回答这两句，再增加模型数量会更有价值。

## 附：本次查证与使用范围

本版结合项目官方仓库、论文与数据说明修订。正文中的项目名和数据名链接是进一步核对的入口；本次重点查证了 Torch-RecHub 的训练/导出示例、RecBole 的两处使用说明、Pyserini 的安装条件、Criteo 的采样说明、Monolith 的归档标记，以及 DIN/HSTU 的关键概念。

Alimama 页面本次只能读取到数据集入口标题，字段细节仍需下载前查看完整说明。本清单没有安装并运行所有外部框架，也不保证每个模型、数据下载或服务部署在你的环境中开箱可用。主分支文档会变化，开始实验时以选定提交对应的 README、数据说明和依赖为准。