Django+MySQL电影推荐系统：冷启动/实时评分/多路召回实战

简介：这是一套基于Python+Django+MySQL实现的电影推荐系统完整源码，专为计算机专业本科生毕业设计与课程实践打造，覆盖Web开发、数据库设计与协同过滤推荐算法落地全流程。资源共2000个文件，主体为1159个Python后端逻辑与Django视图/模型代码，辅以124个HTML前端模板、16个CSS样式文件、40个JS交互脚本及148张JPG/PNG界面截图与系统示意图，另有7个CSV格式的示例电影数据集与用户行为记录，便于快速部署与本地调试。压缩包大小28.03MB，结构清晰，包含完整的manage.py入口、settings配置、迁移脚本及requirements依赖清单。目前已有7816人学习下载，读者可直接获取可运行的全栈项目工程，含用户注册登录、电影浏览评分、基于用户的推荐列表、后台管理模块及MySQL建表语句，是理解推荐系统工程化实现的优质参考范例。

1. 这不是又一个“用户协同过滤”Demo：Django+MySQL电影推荐系统源码，真能跑通冷启动、实时评分、多路召回闭环

去年帮某高校毕业设计辅导组做中期检查，翻了37份标着“推荐系统”的毕设——90%卡在「用MovieLens数据集跑通Surprise库的SVD」，剩下10%连用户登录页都还没渲染出来。直到看到这份python+django+mysql电影推荐系统源码，我当场把测试机清空重装了Python 3.9环境。它不靠调包糊弄，而是用原生Django ORM写透了用户行为埋点→特征实时落库→基于物品相似度的离线召回→热度衰减加权排序→前端动态渲染推荐卡片整条链路。MySQL里建了8张表，从user_profile到movie_tag_weight，每张表都有带业务语义的索引和外键约束；recommend/views.py里那个HybridRecommender类，把基于内容的标签匹配和基于行为的协同过滤结果做了可配置权重融合。适合两类人：一是需要交一份能现场演示、数据库可查、代码有注释、答辩能讲清技术选型理由的毕设学生；二是想快速验证推荐逻辑是否合理、不想被Spark或Flink环境配置拖垮的算法初学者。它不承诺“秒级响应千万用户”，但保证你照着README跑完，能在本地看到用户刚打完分，下一页“猜你喜欢”就变了。

2. 从解压到首页渲染：5步走通Django推荐系统本地部署全流程

2.1 环境准备：Python版本、依赖隔离与MySQL初始化

这份源码明确要求Python 3.8–3.10（requirements.txt里Django==4.2.7和mysqlclient==2.2.0对Python 3.11支持不稳定）。我建议用venv而非conda，因为mysqlclient在conda-forge上常因编译器版本错配报_mysql.c:33:10: fatal error: 'my_config.h' file not found。执行以下命令：

# 创建独立虚拟环境（路径中不要含中文或空格） python3.9 -m venv ./recsys_env source ./recsys_env/bin/activate # Linux/macOS # recsys_env\Scripts\activate.bat # Windows # 升级pip并安装基础依赖（注意：先装mysqlclient再装Django） pip install --upgrade pip pip install mysqlclient==2.2.0 pip install Django==4.2.7 pip install -r requirements.txt

提示：requirements.txt里pandas==1.5.3和scikit-learn==1.2.2是用于离线计算物品相似度的，非Web运行必需，但若跳过会导致management/commands/calculate_item_similarity.py执行失败。

MySQL需提前创建数据库和用户。源码默认配置在settings.py的DATABASES字典里：

DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'recsys_db', 'USER': 'recsys_user', 'PASSWORD': 'recsys_pass123', 'HOST': '127.0.0.1', 'PORT': '3306', 'OPTIONS': { 'init_command': "SET sql_mode='STRICT_TRANS_TABLES'", } } }

对应执行SQL（请勿直接复制密码，按需修改）：

CREATE DATABASE recsys_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'recsys_user'@'localhost' IDENTIFIED BY 'recsys_pass123'; GRANT ALL PRIVILEGES ON recsys_db.* TO 'recsys_user'@'localhost'; FLUSH PRIVILEGES;

2.2 数据库迁移与初始数据注入

Django的manage.py脚本已预置了完整的迁移文件（共12个，从0001_initial.py到0012_add_recommendation_log.py）。关键点在于：必须按顺序执行，且首次迁移后要立即注入种子数据，否则Movie表为空，后续所有推荐逻辑将返回空列表。

# 进入项目根目录（含manage.py的目录） cd /path/to/your/unzipped/folder # 执行迁移（会自动创建所有表） python manage.py migrate # 注入初始电影数据（含1000部电影、20个标签、5000条模拟评分） python manage.py loaddata initial_movies.json python manage.py loaddata initial_tags.json python manage.py loaddata initial_ratings.json # 验证数据是否写入（应返回 Movie对象数量） python manage.py shell -c "from recommend.models import Movie; print(Movie.objects.count())" # 正常输出：1000

initial_movies.json等文件是用Django的dumpdata导出的结构化数据，包含id、title、year、director、genres等字段。其中genres是JSONField存储的列表（如["Action", "Sci-Fi"]），这决定了后续基于内容的推荐能精准匹配。若你看到Movie.objects.count()返回0，请立刻检查loaddata命令是否报错——常见原因是MySQL字符集未设为utf8mb4，导致JSON字段插入失败。

2.3 启动Django服务并验证核心接口

Django默认监听8000端口，但源码在settings.py中设置了DEBUG=True和ALLOWED_HOSTS=['*']，仅限本地开发使用。启动前确认SECRET_KEY已生成（manage.py会自动生成，无需手动改）：

# 启动开发服务器 python manage.py runserver 0.0.0.0:8000 # 浏览器访问 http://127.0.0.1:8000/ # 应看到首页轮播图+“热门电影”列表+搜索框

此时可验证三个核心API端点（用curl或浏览器直接访问）：

• http://127.0.0.1:8000/api/movies/?page=1&size=10：分页获取电影列表（含id,title,rating_avg,rating_count）
• http://127.0.0.1:8000/api/recommend/?user_id=1：为用户ID=1生成推荐（返回movie_id,score,reason字段）
• http://127.0.0.1:8000/api/rate/：POST提交评分（需user_id,movie_id,rating）

注意：/api/recommend/端点依赖离线计算的物品相似度矩阵。若首次访问返回空列表，请先执行2.4节的相似度计算命令。

2.4 离线计算物品相似度：基于余弦相似度的Movie-Movie矩阵生成

推荐系统的核心之一是“喜欢这部电影的人，也喜欢哪些电影”。源码采用基于物品的协同过滤（ItemCF），用用户评分矩阵计算电影两两之间的余弦相似度，并存入item_similarity表。该过程由Django管理命令实现，避免在Web请求中实时计算拖慢响应：

# 执行离线计算（耗时约2-5分钟，取决于CPU） python manage.py calculate_item_similarity # 查看计算日志（会输出处理了多少对电影、平均相似度等） # 日志位于 logs/item_similarity_calculation.log

该命令逻辑如下：

1. 从Rating表读取所有user_id, movie_id, rating三元组，构建稀疏矩阵（行=用户，列=电影）
2. 对每部电影i，找出所有评过分的用户集合U_i
3. 对另一部电影j，计算共同用户集合U_i ∩ U_j
4. 若|U_i ∩ U_j| < 5，跳过（冷门电影不参与相似度计算，防噪声）
5. 计算余弦相似度：sim(i,j) = dot(rating_i, rating_j) / (norm(rating_i) * norm(rating_j))
6. 将结果存入ItemSimilarity模型（含movie_a_id,movie_b_id,similarity_score,common_users_count）

计算完成后，ItemSimilarity.objects.filter(movie_a_id=1).count()应大于50（表示电影1有50+部相似电影）。这是后续HybridRecommender.get_similar_movies()方法的数据基础。

2.5 用户注册、登录与实时评分闭环验证

系统实现了完整的用户生命周期管理。注册页面路径为/accounts/register/，登录为/accounts/login/。关键验证点在于：用户评分后，推荐结果是否实时更新？

操作步骤：

1. 浏览器打开http://127.0.0.1:8000/accounts/register/，注册新用户（如testuser/TestPass123!）
2. 登录后访问http://127.0.0.1:8000/，点击任意电影进入详情页（如/movie/1/）
3. 在详情页底部找到评分组件，给该电影打5分 → 提交
4. 立即刷新首页或访问/recommend/，观察“为你推荐”区域是否出现新电影

背后机制：

• 前端通过AJAX POST到/api/rate/，携带{user_id: 101, movie_id: 1, rating: 5}
• 后端RateView.post()接收后，保存Rating记录，并触发update_user_profile_rating_stats()信号
• 该信号更新UserProfile的avg_rating和rated_count，并异步调用recompute_user_based_recommendations.delay(user_id)（Celery任务，但源码中已降级为同步调用，见tasks.py注释）
• recompute_user_based_recommendations()重新计算该用户的Top-N推荐，存入UserRecommendation缓存表

若第4步未看到变化，请检查Rating表是否新增记录：python manage.py shell -c "from recommend.models import Rating; print(Rating.objects.filter(user_id=101).count())"。若为0，则是前端AJAX未发送成功或CSRF token缺失（Django默认开启CSRF保护，需确保模板中{% csrf_token %}存在）。

3. 推荐逻辑深度拆解：HybridRecommender如何融合内容与协同过滤

3.1 混合推荐架构设计：为什么不用纯协同过滤？

纯协同过滤（如UserCF）在冷启动场景下完全失效——新用户无历史行为，无法找到相似用户；新电影无评分，无法被推荐。而纯内容过滤（如基于TF-IDF的电影简介匹配）又缺乏个性化，所有用户看到的“相似电影”都一样。这份源码的HybridRecommender类（位于recommend/recommenders.py）采用**加权混合（Weighted Hybrid）**策略，公式为：

Final_Score(movie_m) = α × Content_Score(movie_m) + β × Collaborative_Score(movie_m) + γ × Popularity_Score(movie_m)

其中：

• Content_Score：基于电影标签（Genres）的Jaccard相似度。若用户A喜欢["Action","Sci-Fi"]，电影B标签为["Action","Adventure"]，则Jaccard = |{Action}| / |{Action,Sci-Fi,Adventure}| = 1/3 ≈ 0.33
• Collaborative_Score：来自ItemSimilarity表的相似度加权求和。对用户已评过分的电影集合R_u，计算∑_{i∈R_u} similarity(i,m) × rating(u,i)
• Popularity_Score：电影平均分×热度衰减因子（1 / log(1 + days_since_release)），防止老片霸榜

权重α=0.4,β=0.45,γ=0.15在settings.py中可配置。这种设计让新用户注册后，即使没评分，也能基于注册时选择的兴趣标签（UserProfile.preferred_genres）获得内容推荐；随着评分增多，协同过滤权重逐渐主导。

3.2 内容推荐模块：标签权重与用户偏好动态匹配

ContentRecommender.get_recommendations()方法不简单匹配标签字符串，而是引入**标签权重（Tag Weight）**概念。movie_tag_weight表存储每部电影每个标签的权重（如《阿凡达》的"Sci-Fi"权重为0.92，《泰坦尼克号》的"Romance"权重为0.88），该权重由电影简介的TF-IDF向量经人工规则校准得出（详见scripts/generate_tag_weights.py）。

用户偏好通过UserProfile.preferred_genres字段存储，格式为JSON：{"Action": 0.8, "Comedy": 0.6}。推荐时计算：

# 伪代码示意 user_pref = user.profile.preferred_genres # {"Action": 0.8, "Comedy": 0.6} movie_tags = movie.get_tag_weights() # {"Action": 0.92, "Adventure": 0.75} content_score = 0 for tag, user_weight in user_pref.items(): if tag in movie_tags: content_score += user_weight * movie_tags[tag] # 《阿凡达》得分 = 0.8 * 0.92 = 0.736

提示：get_tag_weights()方法会缓存结果，避免每次查询数据库。若你修改了movie_tag_weight表，需重启Django服务或调用cache.clear()。

3.3 协同过滤模块：从ItemSimilarity表到实时推荐

CollaborativeRecommender.get_recommendations()的执行流程严格遵循ItemCF标准：

1. 查询用户u已评分的电影集合R_u = [m1, m2, ..., mk]
2. 对每个mi ∈ R_u，从ItemSimilarity表查出Top-20最相似电影（movie_a_id=mi，按similarity_score降序）
3. 合并所有相似电影，去重后按∑ similarity(mi, mj) × rating(u, mi)加权排序
4. 过滤掉用户已评分的电影（exclude(movie_id__in=R_u)）

关键参数在settings.py中：

# 协同过滤参数 ITEM_CF_MAX_SIMILAR_MOVIES = 20 # 每部已评电影最多取20部相似电影 ITEM_CF_MIN_COMMON_USERS = 5 # 相似度计算要求至少5个共同用户 ITEM_CF_WEIGHTED_BY_RATING = True # 是否用用户评分加权相似度

若发现推荐结果过于集中（如总推荐同一部电影），请检查ITEM_CF_MAX_SIMILAR_MOVIES是否过小，或ITEM_CF_MIN_COMMON_USERS是否过高导致相似电影过少。

3.4 热度衰减模块：用时间戳抑制长尾效应

PopularityRecommender.get_hot_movies()不直接按rating_avg排序，而是计算：

import math from datetime import date def decay_popularity(movie): days_diff = (date.today() - movie.release_date).days decay_factor = 1 / math.log(1 + days_diff/30) # 每月衰减一次 return movie.rating_avg * decay_factor

release_date字段在Movie模型中为DateField，初始数据已填充（如《肖申克的救赎》为1994-09-23）。该设计确保2023年上映的高分新片（如rating_avg=8.5）在热度分上远超1994年的同分老片（8.5 * 0.32 ≈ 2.72），解决“经典永流传”导致的新片曝光不足问题。

3.5 混合推荐调度器：RequestContext如何决定最终排序

HybridRecommender.get_recommendations()并非简单加权求和，而是采用分层调度（Tiered Scheduling）：

• 第一层：对用户u，先用ContentRecommender生成50部候选电影（基于偏好标签）
• 第二层：对这50部，用CollaborativeRecommender计算协同分，筛选出Top-30
• 第三层：对Top-30，叠加PopularityRecommender的热度衰减分，最终排序取Top-10

这种设计避免了全量电影（1000部）参与协同计算的开销，同时保证内容相关性为基线。调度逻辑在recommend/views.py的RecommendView.get()中清晰体现：

# recommend/views.py def get(self, request): user_id = request.GET.get('user_id') recommender = HybridRecommender(user_id=user_id) # 分层调用，非全量计算 candidates = recommender.get_content_candidates(limit=50) collaborative_ranked = recommender.rank_by_collaborative(candidates) final_list = recommender.apply_popularity_decay(collaborative_ranked[:30]) return JsonResponse({'movies': final_list[:10]})

4. 避坑指南：五个血泪经验换来的必踩雷区与排查方案

4.1 现象：python manage.py migrate报错django.core.exceptions.ImproperlyConfigured: Error loading MySQLdb module

原因：mysqlclient未正确编译安装。常见于macOS Monterey/M1芯片或Ubuntu 22.04，系统缺少MySQL开发头文件（mysql.h）或pkg-config未找到MySQL配置。
解决：

• macOS：brew install mysql-client，然后export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"，再重装pip install mysqlclient==2.2.0
• Ubuntu：sudo apt-get install libmysqlclient-dev python3-dev，再pip install mysqlclient==2.2.0
• Windows：直接下载预编译wheel（ https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient ），用pip install xxx.whl安装

4.2 现象：首页加载缓慢（>5秒），Chrome开发者工具Network标签显示/api/movies/响应时间长

原因：Movie模型的rating_avg和rating_count字段是FloatField和IntegerField，但源码未在Movie.objects.all()查询中使用annotate()预计算，导致模板中每部电影都触发Rating.objects.filter(movie_id=xx).aggregate(...)子查询（N+1问题）。
解决：修改recommend/views.py的MovieListView.get_queryset()：

from django.db.models import Avg, Count def get_queryset(self): return Movie.objects.annotate( rating_avg=Avg('rating__rating'), rating_count=Count('rating') ).order_by('-rating_avg')

并在Movie模型的rating_avg字段上添加数据库索引（db_index=True），重启服务后首页加载降至300ms内。

4.3 现象：/api/recommend/?user_id=1返回空列表，但ItemSimilarity.objects.count()显示有12000+记录

原因：HybridRecommender默认只对is_active=True的用户生成推荐，而initial_ratings.json中的用户is_active字段为False（为防刷单预留的开关）。
解决：执行Django Shell命令激活用户：

python manage.py shell -c " from django.contrib.auth.models import User; User.objects.filter(id__in=[1,2,3]).update(is_active=True) "

或在Admin后台（/admin/auth/user/）勾选用户“活跃”状态。

4.4 现象：用户打分后，/recommend/页面推荐结果不变，但Rating表已新增记录

原因：recompute_user_based_recommendations()函数中，UserRecommendation表的created_at字段未更新，导致前端缓存了旧结果。源码中该表未设置unique_together约束，同一用户多次计算会生成多条记录，但视图默认取最新一条（order_by('-created_at')），若created_at未更新则取到旧数据。
解决：修改recommend/recommenders.py的recompute_user_based_recommendations()，在保存前强制更新时间：

# 原代码可能只有 obj.save() obj.created_at = timezone.now() # 添加此行 obj.save()

并确保UserRecommendation.created_at字段定义为auto_now_add=True（检查模型定义）。

4.5 现象：搜索功能（/search/）返回空，控制台报错django.core.exceptions.FieldError: Unsupported lookup 'icontains' for JSONField

原因：Movie.genres字段是JSONField，但搜索视图SearchView.get_queryset()中写了genres__icontains=query，JSONField不支持icontains查找。
解决：修改搜索逻辑，改为解析JSON后匹配：

# recommend/views.py def get_queryset(self): query = self.request.GET.get('q', '') # 原错误写法：Movie.objects.filter(genres__icontains=query) # 正确写法：用JSON_CONTAINS（MySQL 5.7+） return Movie.objects.extra( where=["JSON_CONTAINS(genres, %s)"], params=[f'"{query}"'] )

或更兼容的方案：在Movie模型中添加genres_text字段（TextField），用save()方法自动同步JSON值为逗号分隔字符串，再对genres_text做icontains搜索。

5. 进阶技巧：三招让推荐效果肉眼可见地提升

5.1 用Django Debug Toolbar实时观测SQL与缓存命中率

django-debug-toolbar是调试Django应用的神器，能直观看到每页请求执行了多少SQL、耗时多少、缓存是否生效。源码已预留配置（settings.py中INSTALLED_APPS含debug_toolbar，MIDDLEWARE含DebugToolbarMiddleware），只需两步启用：

1. 安装：pip install django-debug-toolbar
2. 在浏览器访问http://127.0.0.1:8000/，右下角会出现黄色工具栏

重点观察：

• SQL面板：首页加载时，SELECT COUNT(*) FROM "recommend_movie"等聚合查询是否出现多次？若有，说明N+1问题未解决（见4.2节）。
• Cache面板：/api/recommend/请求是否命中default缓存？若Hit为0，检查recommend/views.py中cache_page(60*15)(RecommendView.as_view())装饰器是否生效（需CACHES配置正确）。
• Templates面板：movie_list.html渲染耗时是否超过200ms？若是，检查模板中是否有{{ movie.director }}等未预取的外键访问。

提示：DEBUG_TOOLBAR_CONFIG = {'SHOW_TOOLBAR_CALLBACK': lambda request: True}确保始终显示，避免生产环境误用。

5.2 手动触发物品相似度重算：应对数据突增场景

线上系统中，用户评分数据可能每小时增长数百条。源码的calculate_item_similarity命令默认全量重算，耗时长。实际可优化为增量更新：只对过去24小时内新增评分的电影，重新计算其相似度。

修改management/commands/calculate_item_similarity.py的handle()方法：

from django.utils import timezone from datetime import timedelta def handle(self, *args, **options): # 原逻辑：all_movies = Movie.objects.all() # 新逻辑：只取最近评分活跃的电影 recent_rating_movie_ids = Rating.objects.filter( created_at__gte=timezone.now() - timedelta(hours=24) ).values_list('movie_id', flat=True).distinct() all_movies = Movie.objects.filter(id__in=recent_rating_movie_ids) # 后续计算逻辑不变...

执行python manage.py calculate_item_similarity --verbosity=2，日志会显示“Processing 47 movies”而非“Processing 1000 movies”，耗时从5分钟降至20秒。

5.3 用Admin后台批量管理推荐策略参数

源码在admin.py中注册了RecommendationConfig模型，但未暴露权重参数。我们可扩展Admin，让导师或产品同学在后台直接调整α,β,γ：

# recommend/admin.py from django.contrib import admin from .models import RecommendationConfig @admin.register(RecommendationConfig) class RecommendationConfigAdmin(admin.ModelAdmin): list_display = ('name', 'alpha_weight', 'beta_weight', 'gamma_weight', 'updated_at') fields = ('name', 'alpha_weight', 'beta_weight', 'gamma_weight') readonly_fields = ('updated_at',) # recommend/models.py class RecommendationConfig(models.Model): name = models.CharField(max_length=50, default="Default") alpha_weight = models.FloatField(default=0.4, help_text="Content weight") beta_weight = models.FloatField(default=0.45, help_text="Collaborative weight") gamma_weight = models.FloatField(default=0.15, help_text="Popularity weight") updated_at = models.DateTimeField(auto_now=True)

迁移后，访问/admin/recommend/recommendationconfig/即可修改权重。修改后，HybridRecommender会自动读取最新配置（RecommendationConfig.objects.first()），无需重启服务。

5.4 构建最小可行推荐报告：用Pandas验证算法合理性

光看页面推荐不够，需量化验证。在Django Shell中运行以下脚本，生成用户1的推荐报告：

# python manage.py shell import pandas as pd from recommend.recommenders import HybridRecommender from recommend.models import Movie, Rating # 获取用户1的推荐（Top-10） recommender = HybridRecommender(user_id=1) rec_list = recommender.get_recommendations(limit=10) # 构建分析DataFrame df = pd.DataFrame(rec_list) df['title'] = df['movie_id'].apply(lambda x: Movie.objects.get(id=x).title) df['user_rated'] = df['movie_id'].apply( lambda x: Rating.objects.filter(user_id=1, movie_id=x).exists() ) print(df[['title', 'score', 'reason', 'user_rated']])

正常输出应类似：

title score reason user_rated 0 The Dark Knight 0.821 collaborative: similar to Inception 1 Inception 0.795 collaborative: similar to Interstellar 2 Interstellar 0.762 content: matches preferred genre Sci-Fi

若user_rated列全为True，说明推荐全是用户已看过的——算法失效，需检查exclude()逻辑；若reason列全为content，说明协同过滤未生效，检查ItemSimilarity表数据。

从那以后我每次帮学生调推荐系统，都强制走一遍这个Pandas报告流程：先看user_rated是否为False，再看reason分布是否合理，最后看score是否梯度下降。三步下来，90%的“推荐不准”问题当场定位。希望帮到你。

本文还有配套的精品资源，点击获取