基于协同过滤的电影推荐系统设计与实现

一、项目简介

本系统是一个基于 Python Flask + SQLite 的电影推荐 Web 平台，内置豆瓣电影数据集，采用 scikit-surprise 实现 UserCF / ItemCF 协同过滤算法，提供热门推荐、个性化「猜你喜欢」、电影检索与详情、相似电影推荐、评分收藏及 ECharts 数据可视化，并配备管理后台，适用于推荐系统课程设计与学习演示。

---

一、运行环境

项目	要求
操作系统	macOS / Windows / Linux
Python	3.12（macOS 用 python3.12，Windows 用 python）
数据库	SQLite（内嵌，无需额外安装）
浏览器	Chrome / Firefox / Edge 最新版
依赖管理	pip + venv

核心依赖

包	版本	用途
Flask	3.0.3	Web 框架
Flask-SQLAlchemy	3.1.1	ORM
scikit-surprise	1.1.4	协同过滤模型训练
pandas	2.2.2	数据处理
numpy	1.26.4	数值计算
pyecharts	2.0.6	数据可视化图表
joblib	1.4.2	模型序列化
requests	2.32.3	HTTP 请求（海报代理）
beautifulsoup4	4.12.3	HTML 解析（豆瓣爬虫）

---

二、项目功能说明

2.1 用户端

功能	说明
用户注册/登录	账号密码体系，管理员/普通用户角色区分
首页	热门推荐、高分佳作、猜你喜欢（个性化）三个板块
电影浏览	按关键词搜索、按类型筛选、分页浏览
电影详情	海报、评分、类型、导演、简介、相似推荐（ItemCF）
星级评分	1-5 星交互评分，实时更新平均分
收藏管理	收藏/取消收藏，我的收藏列表
个性化推荐	三级冷启动降级：UserCF → ItemCF → 热门推荐
推荐算法讲解	算法原理、相似度公式、三级策略详解页面

2.2 管理端

功能	说明
数据概览	电影总数、注册用户、评分总数、今日新增统计
用户管理	用户列表、删除用户（数据集用户不可删除）
电影管理	电影列表、搜索、编辑电影信息
图表分析	类型分布饼图、评分分布柱状图、热门 Top10、评分趋势折线图
模型重训	一键重训 ItemCF / UserCF 模型，显示 RMSE / MAE 指标

2.3 推荐算法

算法	说明
UserCF	基于用户的协同过滤（KNN, K=30, cosine），评分 ≥ 5 部时启用
ItemCF	基于物品的协同过滤（KNN, K=40, cosine），电影详情页相似推荐、冷启动二级
热门推荐	评分 0 部时的冷启动降级策略，推荐全站热门电影

---

三、文件目录

code/
├── app.py                      # Flask 应用工厂、路由注册、图片代理
├── config.py                   # 配置（数据库路径、端口、豆瓣参数）
├── requirements.txt            # Python 依赖清单
├── mac_run.sh                  # macOS 启动脚本
├── window_run.bat              # Windows 启动脚本
├── train_model.sh              # macOS 数据导入 & 模型训练脚本
├── _train_helper.py            # train_model.sh 调用的训练辅助脚本
├── fetch_posters.py            # 海报批量抓取脚本（OMDB + 豆瓣）
│
├── models/                     # 数据模型
│   ├── user.py                 #   User 模型
│   ├── movie.py                #   Movie 模型
│   ├── rating.py               #   Rating 模型
│   └── favorite.py             #   Favorite 模型
│
├── routes/                     # 路由蓝图
│   ├── auth_routes.py          #   注册 / 登录 / 登出
│   ├── movie_routes.py         #   电影列表 / 详情 / 评分 / 收藏
│   ├── recommend_routes.py     #   推荐中心 / 算法讲解
│   ├── user_routes.py          #   个人中心 / 收藏列表
│   └── admin_routes.py         #   后台管理（概览 / 用户 / 电影 / 图表 / 重训）
│
├── services/                   # 业务逻辑
│   ├── user_service.py         #   用户注册、验证、CRUD
│   ├── movie_service.py        #   电影查询、评分提交、收藏
│   ├── recommend_service.py    #   三级冷启动推荐策略
│   └── chart_service.py        #   Pyecharts 图表生成
│
├── recommend/                  # 推荐引擎
│   ├── train.py                #   ItemCF / UserCF 模型训练
│   ├── recommend_engine.py     #   模型加载与推荐推理
│   └── model/                  #   训练产物（.pkl）
│
├── utils/                      # 工具
│   ├── db.py                   #   SQLAlchemy 实例
│   ├── helper.py               #   装饰器、年份提取、时间格式化
│   ├── logger.py               #   日志
│   ├── data_loader.py          #   CSV 数据导入、管理员创建、用户补全
│   └── spinner.py              #   终端进度动画
│
├── database/                   # SQLite 数据库文件目录
├── cleaned_dataset/            # MovieLens 数据集
│   ├── movies.csv              #   电影元数据（34,894 部）
│   ├── ratings.csv             #   评分记录（1,198,272 条）
│   └── links.csv               #   MovieLens ↔ IMDb / 豆瓣 ID 映射
│
├── static/                     # 静态资源
│   ├── css/
│   │   ├── main.css            #   全局样式、导航栏、下拉菜单
│   │   ├── movie_card.css      #   电影卡片、网格、类型标签
│   │   └── admin.css           #   后台样式
│   ├── js/
│   │   ├── rating.js           #   星级评分交互
│   │   ├── favorite.js         #   收藏按钮交互
│   │   ├── retrain.js           #   模型重训交互
│   │   └── echarts/             #   Pyecharts 本地化资源
│   │       ├── echarts.min.js
│   │       └── themes/
│   └── img/
│       ├── avatars/            #   用户头像
│       └── default_poster.png  #   默认海报占位图
│
├── templates/                  # Jinja2 模板
│   ├── base.html               #   全局布局（导航栏、Flash）
│   ├── index.html              #   首页
│   ├── login.html              #   登录
│   ├── register.html           #   注册
│   ├── movie_list.html         #   电影列表
│   ├── movie_detail.html       #   电影详情
│   ├── recommend.html          #   推荐中心
│   ├── favorite.html           #   我的收藏
│   ├── profile.html            #   个人中心
│   ├── algorithm.html          #   算法讲解
│   └── admin/
│       ├── dashboard.html      #   数据概览
│       ├── user_manage.html    #   用户管理
│       ├── movie_manage.html   #   电影管理
│       ├── movie_edit.html     #   编辑电影
│       └── charts.html         #   图表分析
│
├── 模型训练.md                  # 训练步骤文档
└── 运行步骤必看/
    └── window.md               # Windows 运行步骤文档