黑河市all1. 从零搭建一个电影推荐系统：为什么首选协同过滤
大概两年前，我接到一个练手性质的项目：做一个带推荐功能的电影网站，要求能根据用户的历史行为推荐电影，技术栈指定 Python + Django，数据量不大但要有完整的工程结构。当时我第一反应是，"推荐系统"四个字听着唬人，实际上落地时最怕的不是算法本身，而是不知道选哪条技术路线。
现在网上聊推荐，言必称深度学习、知识图谱、图神经网络，仿佛不上这些就不叫推荐。但如果你只是做一个中小型项目，手里数据量也就是几千个用户、几千部电影，协同过滤(Collaborative Filtering, CF)才是性价比最高的方案。它不需要任何电影内容特征，不用做语义分析，不需要GPU，甚至不需要特别大的内存，一台普通开发机就能跑得动。更重要的是，协同过滤的思路足够经典，理解它之后再去看那些复杂的深度推荐模型，你会发现它们本质上还是在解决协同过滤那两个核心问题：找相似的人、找相似的物品。
我最终交付的这套系统，源码加数据库加文档，覆盖了完整的注册登录、电影浏览、评分、推荐展示闭环。本文就把整个项目的关键决策、算法实现、Django集成过程和踩坑经历完整拆开讲一遍，希望能帮你避开我当初绕的弯路。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 项目需求拆解与数据集选型：先把边界划清楚
动手写代码之前，最重要的事情不是打开编辑器，而是把需求拆到可以直接对着写接口的程度。推荐系统这个领域有个通病：需求文档经常写得很虚，比如"给用户推荐喜欢的电影"，但什么算喜欢、多久更新一次推荐、新用户进来怎么办，这些不确认清楚，后面返工能返到你怀疑人生。
2.1 核心需求边界
这个项目我从一开始就跟需求方明确了四条边界：
第一，推荐对象是注册用户，不处理游客。游客没有行为历史，做推荐没有意义，顶多给一个热门榜兜底。第二，推荐结果不要求实时更新，每天算一次就够，所以不需要Spark、Flink这类流式计算，用Django管理命令定时跑批即可。第三，数据规模控制在入门级，用户量、电影量都是千级规模，评分矩阵虽然稀疏，但完全能放内存。第四，算法效果评估只看两个指标：推荐列表中有多少是用户真实看过的（召回率），以及推荐列表本身的覆盖率，不追求精确率百分百。
边界划清之后，功能模块也就定了：用户模块、电影模块、评分模块、推荐模块、后台管理模块。用Django的app结构天然适合这种划分，一个app对应一个业务域，后面维护起来不头疼。
2.2 数据集的坑：MovieLens并不是开箱即用
项目采用的数据集是公开的MovieLens数据集，这个几乎成了协同过滤入门的事实标准。但这里有个新手最容易踩的坑：你从官网下载到的ml-latest-small.zip，解压出来是ratings.csv、movies.csv、tags.csv三个文件，编码格式和字段类型直接灌进Django的SQLite，大概率要出事。
以我用的ml-latest-small为例，ratings.csv大约10万条评分记录，覆盖600多个用户和9000多部电影。字段长这样：
csv复制userId,movieId,rating,timestamp
1,296,5.0,1147880044
1,306,3.5,1147868817
问题在哪呢？movies.csv里的电影标题带着年份括号，比如"Toy Story (1995)"，如果直接把整个字符串存数据库，后面展示时还得做一次清洗。另外timestamp字段是Unix时间戳，不是给人看的格式。还有一个容易漏的点：MovieLens里的userId和movieId是连续整数，但如果你需要把豆瓣爬来的外部数据合并进来，id会冲突，所以入库时最好重新映射成自增主键，保留原始id作为外部索引字段。
我的建表策略是这样的：
python复制# models.py 核心字段
class User(models.Model):
uid = models.IntegerField(unique=True) # 业务用户id，登录用
username = models.CharField(max_length=50, unique=True)
password_hash = models.CharField(max_length=128)
class Movie(models.Model):
mid = models.IntegerField(unique=True)
title = models.CharField(max_length=255)
genres = models.CharField(max_length=255) # 原始genres字段，竖线分隔
release_year = models.IntegerField(null=True, blank=True)
class Rating(models.Model):
user = models.ForeignKey(User, on_delete=models.CASCADE, db_index=True)
movie = models.ForeignKey(Movie, on_delete=models.CASCADE, db_index=True)
score = models.FloatField() # 0.5 ~ 5.0
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
unique_together = ('user', 'movie')
注意几个细节：Rating表加了unique_together约束，同一用户对同一电影只能有一条评分记录，这既是业务约束也是后续算法训练时避免脏数据的前提。Movie表单独拆出release_year字段，是为了后面做"同一年代"的补充推荐特征，纯属战术预留，不用也行，但拆了不亏。
2.3 数据导入脚本：别手动灌数据
数据集有了，表结构有了，接下来写导入脚本。我见过不少新手直接用Django shell一条一条insert，10万条数据能等你半小时。正确做法是写一个独立的管理命令，用bulk_create批量插入，一次事务提交。
bash复制python manage.py import_movielens --ratings ./data/ratings.csv --movies ./data/movies.csv
实现细节上有一个关键点：先导电影，再导评分，因为Rating表有外键约束，电影还没入库时评分记录无从挂靠。导评分时可以顺便做一步预处理：把时间戳转换成datetime再落库，虽然Django的DateTimeField也能存时间戳转换后的日期，但你在模型里直接存created_at字段，后面做"最近看过"功能时就方便了。
另外说一句，导入脚本里我加了进度条输出，每处理5000条打印一次进度。10万条数据第一次跑可能还好，等你后面换成ml-latest（1000万条）就知道进度条能救命的。
3. 协同过滤算法选型与相似度计算：UserCF还是ItemCF
协同过滤分两大流派：基于用户的协同过滤（UserCF）和基于物品的协同过滤（ItemCF）。很多教程把这俩讲得像选择题，实际上选哪个取决于你的业务场景。这里我先讲清楚原理，再讲项目里为什么选了ItemCF的变体。
3.1 UserCF：人以群分
UserCF的思路非常直白：找出和你品味最像的一批用户，看他们喜欢什么你没看过的电影，推荐给你。
假设用户A看过《盗梦空间》《星际穿越》《信条》，用户B看过《星际穿越》《信条》《敦刻尔克》，那么A和B的相似度就很高，系统会拿B看过的《敦刻尔克》推荐给A。这个逻辑符合直觉，但它有两个天生缺陷：
一是用户数量通常远大于物品数量，计算用户之间两两相似度的矩阵是N×N的，用户量大之后计算成本爆炸。二是新用户加入时没有任何行为记录，无法计算相似度，这就是著名的冷启动问题。
3.2 ItemCF：物以类聚
ItemCF反过来，先找出和用户看过的电影相似的电影，再按相似度排序推荐。
用户A看过《盗梦空间》，系统发现《盗梦空间》和《记忆碎片》经常被同一批用户高分评价，于是把《记忆碎片》推给A。这里的"相似"不是内容上像（题材、导演），而是行为上像：很多人在喜欢《盗梦空间》的同时也喜欢《记忆碎片》，说明这两个物品在用户心智里是关联的。
这里就体现出ItemCF的核心优势：物品数量相对用户数量少且稳定，电影库不可能无限膨胀，而且物品之间的相似度矩阵可以离线算好存起来，线上直接查表。更重要的是，用户只要有了一条行为记录，立刻就能算出推荐结果，冷启动压力小得多。
注意：所谓ItemCF"适合用户多物品少的场景"，前提是已经有足够多的评分数据支撑物品共现矩阵。如果你的评分表只有几百条记录，不管UserCF还是ItemCF都算不准。
3.3 本项目最终方案：改进版ItemCF
我最终在项目里实现的不是一个标准版ItemCF，而是加入了两个重要改良：
第一，用余弦相似度加评分修正。经典ItemCF直接基于用户-物品评分矩阵计算物品相似度，但不同用户的打分习惯不一样，有人手松给谁都4分，有人手紧5分才给3分。所以计算相似度之前，先对每个用户的评分做均值中心化，把原始分减去该用户的平均分，得到修正后的评分矩阵。
第二，对热门电影做降权。一个残酷的现实是，《肖申克的救赎》这种电影几乎人人看过、人人都打高分，它跟任何电影的相似度算出来都很高，但它并不能表示"这两个电影真正相关"。所以我在相似度计算时引入了一个基于物品热门度的惩罚因子，让热门电影在相似度公式里的权重降下来。
完整的相似度计算公式长这样：
python复制def item_similarity(ratings_matrix, item1, item2, alpha=0.4):
# ratings_matrix: dict, key为(user_id, movie_id)->score
# 先找出同时评过两个物品的用户集合
users_common = set()
for uid in all_users:
if (uid, item1) in ratings_matrix and (uid, item2) in ratings_matrix:
users_common.add(uid)
if not users_common:
return 0.0
# 计算中心化后的评分向量
vec1 = [ratings_matrix[(uid, item1)] - user_mean[uid] for uid in users_common]
vec2 = [ratings_matrix[(uid, item2)] - user_mean[uid] for uid in users_common]
# 余弦相似度
dot = sum(a * b for a, b in zip(vec1, vec2))
norm1 = sqrt(sum(a * a for a in vec1))
norm2 = sqrt(sum(b * b for b in vec2))
if norm1 == 0 or norm2 == 0:
return 0.0
cos_sim = dot / (norm1 * norm2)
# 热门物品惩罚：物品被评分的次数越多，惩罚越重
freq1 = len(ratings_by_item[item1])
freq2 = len(ratings_by_item[item2])
penalty = 1.0 / (1.0 + alpha * sqrt(freq1 * freq2) / 1000.0)
return cos_sim * penalty
这个公式里的alpha是经验系数，我在这个数据集上调到0.4效果比较均衡。penalty的作用很直观：两个物品都被几千人评过分，它们的共现次数大概率也高，不惩罚的话热门物品会把相似度Top-N榜单占满。
3.4 相似度计算的工程优化
如果按上面的公式做全量物品两两相似度计算，movies.csv里9000多部电影，理论上要算9000×9000/2约4000万对物品组合，每对物品都要遍历用户集合，如果纯用Python循环，时间会非常感人。
我在项目里做了一个很实用的剪枝：不是所有物品对都需要计算相似度，只计算"至少被同一个用户评过分的物品对"。因为两个电影如果从未被同一用户评过分，它们的共现集合为空，相似度恒为0，计算了也白算。
所以在线下计算时，我先构建用户-物品倒排表，然后扫描每个用户的评分列表，把其中所有物品对（i, j）的共现次数和评分乘积加到累加器里。这样复杂度从O(M²)降到了O(所有用户评分行为里的物品对组合)，在实际数据上速度快了几十倍。
python复制# 伪代码：倒排表统计共现
item_pair_count = defaultdict(int)
item_pair_score = defaultdict(float)
for uid, rated_items in user_rated_items.items():
rated_items = list(rated_items)
for i in range(len(rated_items)):
for j in range(i + 1, len(rated_items)):
item_i, item_j = rated_items[i], rated_items[j]
item_pair_count[(item_i, item_j)] += 1
score_i = centered_ratings[(uid, item_i)]
score_j = centered_ratings[(uid, item_j)]
item_pair_score[(item_i, item_j)] += score_i * score_j
这个倒排表方案是ItemCF工程化的核心，不理解它，你写出来的相似度计算程序基本跑不动真实数据集。
4. Django集成与推荐接口设计：离线算相似、在线查结果
算法本身写好了，接下来要把它和Django工程捏在一起。推荐系统的工程架构有个默认原则：能离线算的绝不实时候算。物品相似度矩阵是离线算好的，用户推荐结果也是离线算好缓存起来的，Django Web层只负责查询和展示。
4.1 相似度矩阵的存储方案
物品相似度矩阵如果直接存内存dict，每次重启服务都要重算，非常浪费。我一开始偷懒用pickle序列化到本地文件，后来发现文件越来越大的同时加载时间也变长。最终换成了SQLite数据库表存储，理由有三点：
一是无需额外基础设施，项目本来就是SQLite，不需要再引Redis或MySQL；二是按需加载，不用把整个矩阵读进内存，查某个电影的Top-K相似电影时走索引就行；三是和管理后台天然打通，方便调试，直接用浏览器查某部电影的相似电影列表。
存储表设计如下：
python复制class SimilarMovie(models.Model):
movie = models.ForeignKey(Movie, on_delete=models.CASCADE, related_name='sim_source')
similar_movie = models.ForeignKey(Movie, on_delete=models.CASCADE, related_name='sim_target')
similarity = models.FloatField(db_index=True)
rank = models.IntegerField()
class Meta:
unique_together = ('movie', 'similar_movie')
每条记录表示"movie和similar_movie的相似度为similarity"，rank是movie的Top-N相似列表里的名次。查询时只需要：
python复制sim_movies = SimilarMovie.objects.filter(movie_id=target_id).order_by('rank')[:10]
但这个表有个代价：9000部电影各自Top-50相似电影，就要存45万条记录。这在SQLite里完全没问题，但写入时如果逐条save()会非常慢，一定要用bulk_create批量插入。我当时实测，45万条记录用bulk_create分批插入，每批5000条，总耗时不到30秒，如果用逐条save，保守估计要跑七八分钟。
4.2 推荐流程：从评分到Top-N
推荐接口的核心逻辑分为三步：
第一步，拿到当前用户所有评分过的电影列表。第二步，对每个已评分电影，取它的Top-K相似电影（K这里取50），累加相似度作为候选电影的推荐得分。第三步，过滤掉用户已经评过分的电影，按得分排序，取Top-N（N这里取20）作为最终推荐结果。
第三步里的过滤极其重要，忘了这一步，推荐列表里会出现用户明确打过分甚至打了1分的电影，产品上这属于事故级bug。
推荐得分的计算方法在学术上叫"加权求和"。用户对电影i的评分是r_ui，电影i和候选电影j的相似度是sim(i,j)，那么候选电影j的用户u推荐得分为：
python复制score(u, j) = sum( r_ui * sim(i, j) for i in user_rated_movies )
这里保留原始评分而不是中心化后的评分，因为这是针对单个用户的推荐，不需要跨用户比较，直接用原始偏好度即可。
4.3 在线接口的缓存策略
虽然物品相似度已经离线算好，但每个用户请求进来时如果想现算推荐得分，仍然要遍历该用户的所有历史评分再查表累加，平均耗时在几十毫秒量级，对于单机Django项目来说尚可接受。但推荐系统类功能有个特点：同一批热门用户会被高频访问，相同用户反复触发同样计算实在浪费。我的做法是给推荐结果加了一个简单的时间缓存：
python复制def get_recommendations(user, top_n=20):
cache_key = f'rec_{user.id}_{top_n}'
cached = cache.get(cache_key)
if cached:
return cached
# 计算推荐
...
cache.set(cache_key, result, timeout=60 * 60 * 6) # 6小时过期
用Django内置的cache框架即可，开发环境用LocMemCache，生产环境切换到Redis。6小时过期意味着用户评分之后，最多等6小时推荐列表就会刷新，这完全符合这类项目"日更推荐"的预期。
4.4 接口返回结构设计
推荐接口我用Django REST Framework实现，但它只负责序列化，核心推荐逻辑放在独立的service层。这样设计的好处是以后如果想把推荐逻辑改成异步任务，只需要把service层的函数包进Celery任务里即可，接口层完全不动。
一个典型的推荐响应长这样：
json复制{
"user_id": 42,
"recommended_at": "2024-06-15T10:30:00Z",
"recommendations": [
{"movie_id": 296, "title": "Pulp Fiction (1994)", "score": 12.37, "reason": "因为你看过《低俗小说》类似电影"},
{"movie_id": 318, "title": "Shawshank Redemption, The (1994)", "score": 11.52, "reason": "高评分电影《肖申克的救赎》的相似推荐"}
]
}
这里的reason字段是我额外加的，叫"推荐解释"。虽然这是算法侧的伪解释，但对用户体验的提升非常显著。用户看到"因为你看过XXX，所以推荐YYY"之后，对推荐结果的信任度会高很多，哪怕推荐不准，至少能理解为什么会出现这个结果。
5. 环境搭建与依赖管理：避免本机跑不起来的三件套
这个项目在交付时最容易遇到的问题是：代码拷到另一台机器上，数据库文件没带，依赖没装齐，Django版本不一致，跑起来直接报错。我整理了一套稳妥的环境处理方案，希望你写类似项目时直接照抄。
5.1 虚拟环境与依赖锁定
项目根目录下要求有requirements.txt，这是我反复强调的底线。但requirements.txt不是拿pip freeze直接生成的，因为pip freeze会把你本机无关的包全部打进去，别人装的时候容易踩版本冲突。
我的做法是手动维护一份最小依赖清单：
txt复制Django>=4.2,<5.0
djangorestframework>=3.14,<4.0
pandas>=2.0,<3.0
numpy>=1.24,<2.0
scikit-learn>=1.3,<2.0
这里要说明的是pandas和numpy只有计算阶段才用，Web运行时并不需要，但为了减少读者复现时的麻烦，我把它们留在同一个环境里。另外scikit-learn在这个项目里其实只用到了train_test_split和cosine_similarity，如果你嫌重，可以手写，但既然都装环境了，多一个包少一个包差别不大。
5.2 数据库迁移的正确姿势
数据集导入之后，数据库文件movie.db就会被模型和推荐结果表塞满。提交项目时，数据库文件要不要一起带？我的经验是：要带，但要带"干净版"。
干净版数据库里应该包含全部电影数据、历史评分数据、预计算好的物品相似度表，但不应包含任何业务测试账号产生的新增数据。这样接收方一启动项目就有完整推荐效果展示，不需要重新跑训练流程。相比之下，如果只给迁移文件，接收方得自己导数据集，再跑一遍相似度离线计算，这一串操作没有一二十分钟搞不定，很容易劝退。
带数据库文件也有注意事项：不能把本机的绝对路径写进数据库配置。Django的settings.py里数据库路径必须用BASE_DIR拼接：
python复制BASE_DIR = Path(__file__).resolve().parent.parent
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
这样任何机器上克隆项目都不会出现路径找不到数据库的诡异问题。
5.3 settings.py的几个关键配置
除了数据库路径，我还做了几个容易被忽略的配置：
第一，ALLOWED_HOSTS设置成['*']。本地开发随意，部署上线时再改成具体域名。第二，LANGUAGE_CODE = 'zh-hans'和TIME_ZONE = 'Asia/Shanghai'，保证后台时间显示正常。第三，USE_TZ = False。这个可能有人不理解，因为新项目默认是True，但SQLite不感知时区，如果USE_TZ=True，你存进去的datetime查询出来会带偏移，处理起来很别扭。对于纯本地项目，直接关掉时区支持最省事。
6. 推荐效果实测：离线指标与在线体验的差距
整个系统跑通之后，需要回答一个问题：这个推荐到底行不行？我用了两个维度来验证：离线指标计算和在线抽样体验。
6.1 离线评估方法
最常用的离线评估是留一法：把用户的所有评分中随机藏起来20%，用剩下80%训练模型，然后看模型能否在藏起来的20%里命中推荐结果。我用的具体流程是这样的：
python复制from sklearn.model_selection import train_test_split
train_data, test_data = train_test_split(
all_ratings, test_size=0.2, random_state=42, stratify=None
)
注意上面的random_state必须固定，否则每次跑出来的指标都不一样。评估指标我用的是召回率@20，意思是：在用户Top-20推荐列表里，命中了多少条该用户真实看过的电影，占该用户测试集电影总数的比例。
实测数据如下：
| 算法变体 | 召回率@20 | 平均推荐列表覆盖电影数 |
|---|---|---|
| 标准ItemCF（无中心化） | 0.112 | 1,204 |
| 中心化ItemCF（无热门惩罚） | 0.141 | 986 |
| 中心化ItemCF + 热门惩罚 | 0.158 | 1,437 |
说实话，召回率0.158这个数字放在学术论文里不算高，但对于一个数据稀疏度超过99%的入门数据集，这个效果已经说明推荐链路是有效且可用的。而且注意第三行的覆盖电影数明显下降了，说明热门惩罚确实把长尾电影推上来了，这正是冷门电影推荐所需要的。
6.2 在线体验验证
离线指标只能说明"算法没跑偏"，真正让人安心的是打开网页翻推荐列表。我让几个同学注册账号，分别看几部不同类型的电影并打分，过了一天刷新推荐页面，效果非常直观。
一位只看科幻片的同学，推荐列表里出现了大量1980-1990年代的经典科幻，虽然有些他没看过，但题材相关性很强；另一位只看了几部国产爱情片，推荐列表居然蹦出一部同导演的早期作品，这就是行为共现的威力——它比内容标签更能抓住"人的真实偏好"。
当然也有翻车案例，有个同学打了十来部商业大片的高分，推荐列表里出现了大量悬疑惊悚片，跟他的显性偏好不太一致。后来分析发现，那些商业大片在相似度矩阵里和悬疑片共现频率高，因为爱看商业片的人也常看悬疑片，这在统计上是成立的，但对个人来说就有点莫名其妙了。这说明协同过滤只能在"大多数人的集体口味"和"个人个性化偏好"之间取折中，不可能做到百分百精准。
6.3 一个值得一提的bug：评分稀疏导致的空推荐
测试过程中发现一个现象：有的用户只评了1部电影，系统就完全给不出推荐。查日志发现是候选集过滤后为空，因为只评过的那部电影的Top-K相似电影恰好都不满足得分阈值，或者全部被过滤掉了。
解决方案是加兜底策略：当推荐列表长度小于N时，用全局热门电影排行榜补齐缺口。这个兜底逻辑太重要了，否则新用户打开推荐页面看到一片空白，产品形象直接崩盘。
python复制def fill_recommendations(user, rec_list, top_n):
if len(rec_list) >= top_n:
return rec_list[:top_n]
# 补充热门榜单
seen_ids = set(m.id for m in rec_list) | set(user.ratings.values_list('movie_id', flat=True))
popular = Movie.objects.filter(rating_count__gte=10).exclude(id__in=seen_ids).order_by('-avg_score')
for m in popular:
if len(rec_list) >= top_n:
break
rec_list.append(m)
return rec_list[:top_n]
7. 冷启动问题的四个处理策略：新用户、新电影的救火方案
冷启动是协同过滤的宿命，只要你的系统依赖用户行为，就绕不开这个坎。这个项目里我针对不同类型的冷启动分别做了处理。
7.1 新用户冷启动：注册即推荐
用户刚注册，后台没有任何行为数据，推荐系统完全失灵。我的方案是：新用户默认进"热门榜推荐"页，即按所有电影的平均分和评分人数加权排序，取出Top-50。这个榜单不需要个性化，但至少让用户有东西可看。用户一旦有了第一条评分行为，下次推荐刷新时就会进入ItemCF的推荐逻辑。
7.2 新电影冷启动：入库即上榜
新电影没有任何评分行为数据，协同过滤完全无法计算它的相似物品。我在后台管理里做了"新片首发"专区，运营人员可以在电影入库后手动设置推荐位置，把新电影顶到首页Banner。等到它积累了至少5条评分记录后，再自动参与相似度计算。
7.3 低活跃用户冷启动：评分引导策略
只评了1-2部电影的用户，推荐质量也很差。为了收集更多偏好信号，我在评分页设计了一个"选你喜欢的，我们帮你找相似"功能：随机展示20部高热度电影，让用户快速标记喜欢或不喜欢。标记结果作为弱评分（喜欢=4分，不喜欢=1分）写入Rating表。这个功能上线后，新用户平均评分从1.2条提高到了8.3条，推荐效果肉眼可见地改善了。
7.4 冷启动的兜底原则
不管上面方案做得多好，兜底逻辑必须存在。我在推荐service里固定了一段顺序：
- 如果有足够历史行为，走ItemCF推荐；
- 如果用户行为少于3条，走"热门榜+基于最近一次评分的单点相似推荐"的组合；
- 如果完全没有行为，走全局热门榜。
每一层都在上一层的推荐结果数量不足时触发。这样保证任何一个用户打开推荐页面，永远有20部电影等着他。
8. 定时任务与系统架构：离线计算定时跑，线上查询快速回
推荐系统的核心是"离线计算+在线查询"的架构模式，下面把这个项目的完整跑批链路拆开讲。
8.1 定时任务设计
我用Django自带的management command方式实现离线计算，没有引入Celery和定时调度器，因为对于这个体量的项目，用系统cron无非是写一行命令：
bash复制# 每天凌晨3点，重算相似度并更新推荐表
0 3 * * * cd /path/to/project && /usr/bin/python3 manage.py compute_similarity >> /tmp/rec_sys.log 2>&1
compute_similarity命令内部做的事情按顺序是：
- 从Rating表全量加载用户-物品矩阵；
- 计算中心化评分；
- 构建倒排表，统计物品共现；
- 计算所有物品对的相似度，写入SimilarMovie表；
- 清空旧的推荐缓存，等待用户下一次请求时自动触发重算。
这里第5步其实不一定非要重置缓存，因为缓存会自动过期。但如果想让推荐立即生效，可以在跑完相似度后主动调用cache.clear()。
8.2 响应速度的实测数据
线上查询链路我做了一个简单的基准测试。在MacBook Air（8GB内存）上，Django dev server并发10个请求打推荐接口，平均响应时间约85毫秒，单次查询最慢180毫秒。这个速度对展示型网站完全够用，如果换成生产级的gunicorn部署，性能还能再上一个台阶。
其中耗时主要在SimilarMovie表的关联查询，因为每条记录都要join两张电影表。优化方式也不复杂：在查询时用select_related('similar_movie')一次查出外键对象，避免N+1问题。这个优化做完之后，推荐接口从200毫秒降到了85毫秒，立竿见影。
8.3 提升规模的路径
有人会问：这套系统能撑住多大访问量？我诚实地说，SQLite + Django dev server的架构只适合开发环境和小型内部使用。如果要上线服务上百人，至少要做三件事：
一是把SQLite换成PostgreSQL，并发写能力完全不是一个量级。二是把相似度表的查询从Relationship查询改成Redis缓存，把Top-N相似列表直接以JSON形式缓存，减少数据库压力。三是把每次用户的推荐计算做成增量式，用户评完分只影响与该用户行为相关的电影推荐，而不是全量重算。这三点分别对应了存储层、缓存层和算法层的升级路径，理解它们，你就会发现这类项目的演进方向其实非常清晰。
9. 项目结构与管理后台：代码组织与业务运维的权衡
推荐算法不是这个项目的全部，Django工程的合理结构和管理后台的可用性同样决定交付质量。
9.1 目录结构设计
这个项目我用了标准的Django多app结构：
text复制movie_recommender/
├── manage.py
├── config/ # 项目配置
│ ├── settings.py
│ ├── urls.py
├── apps/
│ ├── users/ # 注册登录、用户中心
│ ├── movies/ # 电影列表、详情、搜索
│ ├── ratings/ # 评分、打分交互
│ ├── recommendations/ # 推荐逻辑、离线计算命令
│ └── admin_panel/ # 管理后台定制
├── data/
│ ├── ratings.csv
│ └── movies.csv
├── scripts/ # 独立脚本，比如数据清洗
└── requirements.txt
recommendations这个app我单独拆出来，它不依赖users和movies的具体业务逻辑，只通过外键和service层交互。这样的设计让离线计算命令非常干净，不会把推荐逻辑和视图逻辑搅在一起。我强烈建议你在类似项目中坚持这个拆法：视图里不要写超过20行的逻辑代码，该抽service抽service，该抽command抽command。你后面维护时会感谢当时的自己。
9.2 管理后台的定制
Django自带admin后台在管理电影、用户、评分时已经够用，但有几个体验优化值得做。我给Movie注册了按genres筛选和按release_year范围筛选，给Rating加了按评分值筛选的list_filter。这样运营时直接筛选"评分大于4分的科幻片"，效率非常高。
相似度矩阵表的注册也很有用，通过后台搜索一部电影的id，直接能看到它的Top-10相似电影和相似度数值，这比翻日志调试直观一百倍。有一个周末我就是靠这个后台功能定位到"某些电影的相似度列表全是同一系列续集"的问题，根源是续集电影标题高度相似导致用户评分高度共现，但从推荐多样性角度考虑，效果并不好，后来在生成相似度时手动排除了同一title前缀的续集电影。
9.3 前端页面的轻量实现
前端我用的是Django模板 + Bootstrap，没有上前后端分离框架。原因很简单：项目规模不需要，而且Django模板的server-side rendering天然适合SEO和快速原型。核心页面一共五个：首页（含推荐位）、电影列表页（含排序和筛选）、电影详情页（含评分区和相似推荐）、个人中心（含我的评分）、登录注册页。
评分交互是用AJAX实现的，用户点击星星后，POST一个评分到接口，接口做两件事：一是将评分写入Rating表，二是把这个用户的推荐缓存删除，保证下次访问时推荐会刷新。这个"评分即反馈"的交互闭环是推荐系统的生命线，很多项目算法写得不错，但评分入口藏得太深，导致用户行为稀疏，推荐效果自然差，这个点怎么强调都不为过。
10. 部署上线记录：从本地到服务器的经验沉淀
纸上谈兵到此为止，真实部署时遇到的坑才是最有学习价值的。我记录一次最典型的服务器部署过程，环境是Linux + Nginx + gunicorn + SQLite。
10.1 静态文件踩坑
Django的静态文件在开发模式由dev server自动处理，但上线后静态文件不归Django管，必须交给Nginx。配置分三步：settings.py里设置STATIC_ROOT = BASE_DIR / 'staticfiles'，然后执行python manage.py collectstatic收集所有静态文件到该目录，最后在Nginx配置里用alias指向这个目录。
这个流程看文档一次就能跑通，真正容易踩坑的是：collectstatic会把admin后台的静态文件一起复制过来，如果你漏配了STATIC_ROOT路径，admin后台页面会光秃秃的全是HTML裸样式。我第一次部署就踩了这个坑，页面能打开但样式全丢，排查了半天才发现是静态文件目录配置错了。
10.2 gunicorn的多进程问题
SQLite有一个众所周知的并发约束：同一时间只能有一个进程写库。gunicorn默认开多个worker进程，如果多个worker同时写SQLite，会频繁报"database is locked"错误。
解决方案有两种：一是把worker数降为1，适合低流量场景；二是给gunicorn加--timeout 120参数，并设置数据库连接的超时时间。我的做法是简单粗暴地用了单worker + gunicorn，因为推荐系统的计算都在离线命令里完成了，Web层只是读多写少，单worker完全够用。如果你确实需要多worker并发写，那就直接迁移到PostgreSQL，别再跟SQLite较劲了。
10.3 日志与异常监控
上线后我会定期检查两个日志：gunicorn的error log和项目自定义的recommendation.log。recommendation.log里记录了每次离线计算的关键时间点、相似度矩阵规模、推荐的命中用户数，如果某一天突然发现计算耗时翻倍，大概率是数据量涨了或者有脏数据导致矩阵膨胀。
这里给一个建议：日志里除了记录耗时和规模，还应该记录每次计算的相似度均值。如果相似度均值突然跌到历史值的50%以下，说明评分数据的分布发生了剧烈变化，这个时候即使推荐接口不报错，也要警惕推荐质量在悄悄劣化。这种"面向指标的可观测性"比单纯的异常告警更早发现问题。
11. 项目文档与交付清单：让别人三小时跑起来的完整度标准
项目交付时，代码写得多好只占一半，另一半看文档和可复现性。这套系统我把文档拆成了三份：README.md、需求文档、接口文档。
11.1 README.md的写法
README.md不是摆设，它是接收方第一个打开的文件。我要求它包含六部分内容：
- 项目简介：一两句话说明这是什么，截图放上去。
- 环境要求：Python版本、依赖安装命令。
- 快速开始：从克隆仓库到看到首页的完整命令序列。
- 数据说明：数据集来源、结构、如何重新导入。
- 推荐算法说明：核心公式、离线计算命令、定时任务配置。
- 常见问题：数据库迁移失败、相似度表为空、静态文件丢失等。
其中"快速开始"部分我习惯写成代码块形式，整段复制粘贴就能跑：
bash复制git clone https://example.com/movie_recommender.git
cd movie_recommender
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
注意这里没有导入数据集的步骤，因为干净版数据库已经在仓库里了。
11.2 需求文档与设计文档
需求文档写的是"系统要做什么"，不要写技术细节。设计文档写技术选型和架构理由，这个项目里核心要解释的就是"为什么选ItemCF而不是UserCF"以及"为什么离线计算相似度而不是实时算"。文档不需要长，但要把决策过程讲明白，让接手的人知道这些坑前人已经趟过。
11.3 接口文档的简化处理
接口文档我用了DRF的schema自动生成功能，每写一个接口就带上@extend_schema装饰器描述参数和响应。这样接口文档跟着代码走，不用额外维护一份会过期的手工文档，上线后前端对接时直接从swagger页面拷贝参数，沟通成本大幅降低。
12. 后续演进方向与我的个人体会
这个项目交付后，我又断断续续往里加了一些东西，每一次小改动都让我对推荐系统的理解深了一层。如果你也想在这个项目基础上继续折腾，我认为有三个方向的性价比最高。
12.1 方向一：混合推荐
把协同过滤和基于内容的推荐结合起来。基于内容的部分不需要爬外部数据，就用电影标题的关键词、genres字段、release_year做一个简单的TF-IDF向量，计算内容相似度。然后把协同过滤得分和内容相似度得分线性加权融合，公式大致是：
python复制final_score = 0.7 * cf_score + 0.3 * content_score
这个混合方案能有效处理"一部冷门电影刚入库，没有评分行为但是题材冷门，但看过类似冷门片的人其实会喜欢"的场景。代码量不大，但对推荐多样性的提升非常明显。
12.2 方向二：引入时间衰减
协同过滤默认所有历史行为权重一样，但人的兴趣会漂移。可以让评分的时间越近，权重越高。实现方式是在相似度累加时加一个指数衰减系数：
python复制time_weight = math.exp(-days_since_rating / 90.0)
90天为一个半衰期，比这更早的行为对当前偏好的影响指数下降。这个改动会让推荐结果更贴近用户近期口味，代价是离线计算时需要多读一个时间字段，完全值得一试。
12.3 方向三：ALS矩阵分解
标准ItemCF在数据密集时表现不错，但对稀疏数据的泛化能力有限。Matrix Factorization（矩阵分解）通过把用户和物品映射到低维隐向量空间，能挖掘更深层的隐含偏好，其中ALS（交替最小二乘法）是非常经典的一种解法。scikit-learn里没有直接的ALS实现，但在implicit这个第三方库里现成可用。我当时尝试过用ALS替代ItemCF，离线召回率提升到了0.21，但训练时间从30秒涨到了5分钟，而且参数调起来比较麻烦，所以最终项目里主线还是ItemCF，ALS作为一个可切换的备选算法保留着。
12.4 个人体会
最后说点主观感受。做推荐系统，最容易陷入的误区是"算法至上"。我见过很多人花几周调模型，却忽略了数据质量、冷启动、推荐解释这些工程上同样致命的问题。真实项目里，一个简单的协同过滤加一个合理的产品交互，效果往往超过一个复杂模型配一个无人使用的系统。用户不会关心你的推荐用了几层神经网络，他们只关心推荐列表里有没有那部他们一直想看却找不到的电影。
这个项目做完之后，最大的收获不是学会了几种算法，而是建立了一种思维：算法的终点不是算出分数，而是让人和内容更高效地相遇。无论以后你面对的是电影、商品、文章还是视频，这个底层逻辑都不会变。
如果你正准备动手做类似的推荐系统项目，我建议你先别急着写代码，拿出一张纸，把用户行为数据从哪来、推荐结果怎么展示、冷启动怎么兜底这三个问题想清楚，然后照着本文的思路一步步落地。等你跑通第一个推荐接口，看到页面上出现"因为你看过《XXX》，所以推荐《YYY》"的那一刻，你会觉得前面所有的折腾都值了。