电影推荐系统 · 手写 FunkSVD 与混合推荐重排

这个项目解决什么问题

推荐系统教程最常见的两个偷懒：矩阵分解直接调 surprise 库、评估只看 RMSE 一个数。本项目反着来：FunkSVD 的随机梯度下降全程手写（注释里有完整的梯度推导），评估则补上覆盖率和新颖度这些"推荐系统才有的指标"，最后还回答一个真问题——推荐结果全是同类片怎么办？

核心亮点

• 自实现 FunkSVD：全局均值 + 用户偏置 + 物品偏置 + 隐向量内积，纯 numpy 手写 SGD 训练，带正则化、学习率衰减与早停。它与 sklearn 的 TruncatedSVD 做了对照实验——为什么显式建模偏置更好，结果和解释都给你。
• 混合推荐：四路算法的预测分归一化后加权融合，融合权重在验证集上搜索得出，而不是拍脑袋。
• MMR 多样性重排：用电影类型的 Jaccard 相似度做贪心重排，专治"猜你喜欢清一色"；重排前后"精度-多样性"的权衡画成散点图，一眼看懂代价与收益。
• 冷启动问卷式推荐：新用户没有历史评分？选 3 部喜欢的电影即可获得推荐——网页里有专门的引导页。
• 专业评估维度：RMSE、Precision@K 之外，补充覆盖率（Coverage@K）与新颖度（Novelty@K），这是工业界推荐系统报告的标配视角。
• Flask 网页可演示：命令行跑评估，浏览器看推荐，课程汇报现场效果直观。

效果预览

评分分布——推荐系统要建模的"口味"就藏在这条分布里：

四种算法 RMSE 与 Precision@10 对比，混合推荐拿下综合最优：

多样性重排的代价与收益，一张散点图说清：

预览图基于模拟数据演示实际运行效果，真实数据运行结果以你下载的数据集为准。

你将学到

• 协同过滤两大范式（User-Based / Item-Based）的相似度设计与向量化实现
• 矩阵分解的原理、手写实现与调参
• 混合策略与多样性重排的工程化做法
• 推荐系统离线评估的完整指标体系

适合谁

方向明确想做推荐系统、或需要在毕设里展示"手写算法能力"的学习者。难度 ★★★☆，FunkSVD 模块代码独立、注释带推导，可单独拿出来讲。

FunkSVD 每一轮迭代到底发生了什么、MMR 的贪心怎么做的——源码注释比这篇文档详细得多，留给你自己探索。

交付内容：完整可运行源码、README.md（逐步运行方法与实现说明）、requirements.txt。

数据集：第三方数据受原始授权限制不随包分发，按 README.md 里的官方链接下载放入 data/ 即可跑通全流程。

许可：个人使用，可用于自己的学习、课程实验与研究报告，请勿转售或公开传播。

环境与步骤

pip install -r requirements.txt

pip install -r requirements.txt
python main.py    # 训练 + 评估 + 推荐演示，结果落盘 outputs/
python app.py     # （可选）启动 Flask 推荐网页

注意事项

• 数据集不随包提供：先按 README.md 的链接下载放入 data/，再执行下面的命令。

Q：MovieLens 下哪个版本？

A：ml-100k 就够（grouplens.org/datasets/movielens/）。README 的“数据集准备”写了要哪几个文件、放进哪个目录。

Q：FunkSVD 是调库还是自己写的？

A：纯 numpy 手写：评分建模为全局均值 + 用户偏置 + 物品偏置 + p·q，SGD 更新带正则、学习率衰减与早停，梯度推导写在注释里；同时与 TruncatedSVD 做对照并解释差异来源。

Q：网页演示怎么起来？

A：python app.py 后浏览器打开 http://127.0.0.1:5000/ ；命令行模式跑 python main.py 出训练与评估结果。

Q：新用户没有历史记录怎么办？

A：冷启动走问卷式：选 3 部喜欢的电影，用物品相似度聚合出推荐（网页 /newuser 支持片名模糊搜索）。评估也不只看准确率，另补了 Coverage@K 与 Novelty@K，说明推荐结果不是只会推热门。