简介：一套基于知识图谱的Python电影推荐系统源码，是面向计算机专业本科毕业设计的中等难度项目，也适用于课程作业、学期末综合实践等教学场景。作为已通过评审的高分毕业设计（98分），项目在导师指导下完成，并经过本地环境的多轮调试与稳定性验证。系统融合知识图谱与协同过滤算法，围绕导演、演员、类型、题材等实体关系构建电影知识网络，通过结构化数据处理和语义关系挖掘提升推荐精准度，能有效缓解传统推荐系统的冷启动问题。压缩包共67个文件，以43个Python代码文件为主，涵盖知识图谱构建、用户行为分析与推荐算法等核心模块；另有SQL数据文件、md/txt说明文档、cfg配置及备份文件，便于理解项目结构与快速部署，整体仅892KB。代码遵循PEP8规范、注释详细，并附有环境配置指南与部署教程，读者可直接基于完整源码、数据集和项目文档开展二次学习或毕业设计参考。目前已有61人学习下载。
1. 知识图谱 + Python 做电影推荐系统：这份源码值得照着复现
先说结论：这是一份用知识图谱做电影推荐的毕业设计源码，不是那种套个协同过滤就交差的项目。它把电影、演员、导演、类型、制片国家建模成一张图，存进 Neo4j，再用图查询和图算法生成推荐结果。我在拆这份源码时，花了两个晚上把数据导入、推荐接口和前端展示跑通，最大的感受是：它把“推荐系统”从一个黑匣子变成了能解释的路径——比如“你喜欢诺兰，是因为你看过《星际穿越》且没看过《盗梦空间》”这种话术，是协同过滤没法直接给出的。这份源码适合两类人：一是毕业设计选题落在推荐系统、知识图谱方向的学生，二是想在企业里做“可解释推荐”但还没找到切入点的工程师。它既给了完整的工程骨架，也给了可以继续加料的图谱结构设计。下面我按自己复现的顺序，把它拆成六块讲清楚。
2. 知识图谱的实体建模：把电影、演员、导演、类型变成节点和关系
2.1 为什么用图数据库而不是 MySQL：推荐场景看的是关系密度
如果有人问“为什么毕业设计非得上 Neo4j”，我的回答是：传统关系型数据库擅长存“某部电影属于什么类型”这种一一对应的关系，但推荐系统要回答的是“A 演员和 B 导演合作过，并且 B 导演的类型偏好和用户历史高度重合”这种多跳关系。用 SQL 做三次 JOIN 问题不大，但十次 JOIN 就会让代码变成一坨。图数据库把关系作为一等公民，查询“有没有合作过”是沿着边走路，而不是做表连接。这套源码选的图数据库是 Neo4j，版本基于 Community 4.x，配合 Python 的 py2neo 库操作。选 Neo4j 的理由很现实：社区版免费、Cypher 查询语法对写习惯了 SQL 的人友好、可视化界面自带 Browser，演示答辩时不用额外开发前端就能看到知识图谱长什么样。
2.2 实体与关系的完整清单：节点属性、关系方向、索引设计
源码里定义的知识图谱不是随意建的，它严格遵循了“本体 + 实例”的分层。顶层本体包含四类实体：Movie（电影）、Person（演员/导演）、Genre（类型）、Country（制片国家）。其中 Person 节点通过actor和director两种关系绑到 Movie 上，Movie 再通过belongs_to指向 Genre，produced_in指向 Country。节点属性设计得很克制：Movie 节点只有movie_id、title、year、rating、plot五个属性，没有把演员表塞进节点里——因为演员表是要被“查询”的关系，不是要被“展示”的属性。Person 节点有person_id、name、birthday。索引全部建在 ID 字段上，因为后续导入和查询都靠 ID 做MERGE匹配，索引建错了，导入速度会慢十倍。
| 实体 | 关键属性 | 关系 | 目标实体 | 关系含义 |
|---|---|---|---|---|
| Movie | movie_id, title, year, rating, plot | :ACTED_IN | Person | 演员出演 |
| Person | person_id, name, birthday | :DIRECTED | Movie | 导演执导 |
| Movie | 同上 | :BELONGS_TO | Genre | 电影属于类型 |
| Movie | 同上 | :PRODUCED_IN | Country | 制片国家 |
| User | user_id, nickname | :RATED | Movie | 用户评分（扩展） |
你在源码里会看到一张merge_graph.py，它先清空图库再导入，就是为了保证关系方向一致。比如ACTED_IN的方向必须从 Person 指向 Movie，如果你反向建了边，后面查询“和某演员合作过的其他演员”时，方向条件就得写成<-[ACTED_IN]-，一不小心就查空。这份源码里所有关系的方向都按上面表格设计，后续 Cypher 模板直接套用，不需要额外翻转。
2.3 数据准备：从 MovieLens 到可导入的 CSV，附清洗脚本
源码没有内置数据，它给了两个数据源：一是 MovieLens 的movies.csv和ratings.csv，二是从 TMDB 抓取的中文电影信息。MovieLens 数据是公开的，但只有英文名和类型，没有演员、导演、制片国家。所以源码里附了一个fetch_tmdb.py，用 TMDB API 反查电影详情。这里要说一下我的经验：TMDB API 有速率限制，免费 key 每分钟 40 次请求，如果你要抓 5000 部电影，按 1 秒一次也得一个多小时。源码把抓取过程做成了断点续传，抓过的movie_id会写进本地 JSON 缓存，下次运行时跳过。代码大概是这样的：
import json import time import requests TMDB_API_KEY = "你的key" CACHE_FILE = "tmdb_cache.json" def load_cache(): try: with open(CACHE_FILE, "r", encoding="utf-8") as f: return json.load(f) except FileNotFoundError: return {} def fetch_movie_detail(movie_id): cache = load_cache() if str(movie_id) in cache: return cache[str(movie_id)] url = f"https://api.themoviedb.org/3/movie/{movie_id}" params = {"api_key": TMDB_API_KEY, "language": "zh-CN"} resp = requests.get(url, params=params) resp.raise_for_status() data = resp.json() # 只保留我们需要的字段，避免把 TMDB 的大对象全塞进 Neo4j detail = { "title": data.get("title"), "year": data.get("release_date", "")[:4], "rating": data.get("vote_average"), "plot": data.get("overview"), "genres": [g["name"] for g in data.get("genres", [])], "countries": [c["name"] for c in data.get("production_countries", [])], } cache[str(movie_id)] = detail with open(CACHE_FILE, "w", encoding="utf-8") as f: json.dump(cache, f, ensure_ascii=False) time.sleep(0.3) # 控制速率，避免被限流 return detail代码逻辑不复杂，核心是cache字典：先查缓存，命中就直接返回；没命中的请求 TMDB，只保留推荐系统需要的字段，然后写回 JSON。这里的sleep(0.3)是必须的，如果去掉，抓个几百条就会被 TMDB 封 key。字段裁剪也很有讲究——genres和countries在 TMDB 返回里是对象数组，直接入库会导致节点属性里面套着复杂结构，后续 Cypher 根本没法查。所以源码里把它们拆成了字符串数组，后续导入时分别和 Genre、Country 节点建关系。
3. 用 py2neo 把数据写进 Neo4j：批量导入与 Cypher 参数化
3.1 环境配置：Neo4j 版本与 py2neo 安装的坑
先把环境拆明白。这份源码的requirements.txt里写着neo4j==4.4.11和py2neo==2021.2.4。为什么不用 pip 最新版？因为 py2neo 的 2021.2.4 之后的版本和 Neo4j 4.4 存在握手协议不兼容的问题，graph.run()执行 Cypher 时经常报Unauthorized。我之前在自己的机器上装过最新版 py2neo，连的是 Neo4j 4.4.18，结果每次连上不到五分钟就掉线，换源码锁定的版本后问题消失。所以下载源码后，第一件事就是建虚拟环境并用 requirements 安装，别手贱升级 py2neo。Neo4j 数据库本身需要 Java 11，如果你本机装的是 Java 17，Neo4j 4.4 会启动失败，这是 Neo4j 官方文档明确写的坑。源码里附了一个neo4j.env示例，里面配置了JAVA_HOME路径，实际用的时候改成你自己的 JDK 11 路径就行。
3.2 批量创建节点与关系：UNWIND 与 MERGE 的正确姿势
源码导入数据用的是py2neo的graph.run()执行 Cypher，而不是用官方neo4j驱动的session.run()。py2neo 的写法更 Pythonic，而且源码里封装了GraphService类，连接信息集中在config.py。我建议你照着源码结构走，因为它把“读 CSV 生成 Cypher”和“执行 Cypher”拆开了，方便调试。下面这段是从源码里抽出来的核心导入函数：
from py2neo import Graph graph = Graph("bolt://localhost:7687", auth=("neo4j", "your_password")) def import_movies(movies): query = """ UNWIND $rows AS row MERGE (m:Movie {movie_id: row.movie_id}) SET m.title = row.title, m.year = row.year, m.rating = row.rating, m.plot = row.plot """ # rows 是一个字典列表，每项对应一部电影 graph.run(query, rows=movies)这里的关键不是SET，而是MERGE。MERGE的语义是“存在则匹配、不存在则创建”，它要求大括号里必须有唯一标识——也就是movie_id。如果你用CREATE，每次运行都会新建一条节点，重复执行两次，图里就有两份完全相同的电影。UNWIND是把 Python 列表展开成 Cypher 里的多行数据，然后用一条语句批量处理。它的性能比逐条MERGE高出一个数量级，但要注意rows列表不能太大。我试过把一万条电影一次性UNWIND，Neo4j 直接报内存不足；源码里做了chunk_size=500的分批处理，每次传 500 条，执行完一批再传下一批。
演员、导演、类型、国家的关系导入原理相同，都是先MERGE出节点，再MERGE关系。关系上的MERGE和节点上的不一样，它必须指定两个端点：
def import_actor_relations(actors): query = """ UNWIND $rows AS row MATCH (p:Person {person_id: row.person_id}) MATCH (m:Movie {movie_id: row.movie_id}) MERGE (p)-[:ACTED_IN {role: row.role}]->(m) """ graph.run(query, actors)这段代码有两个MATCH，如果某个person_id在 Person 表里不存在，这条关系就会静默跳过，不会报错。这是 Neo4j 的特性，但也可能让你丢了数据——清洗数据时如果不先对引用完整性做检查，最后图谱里的ACTED_IN关系数会少于预期。源码里的做法是先加载全部 person_id 到内存集合，导入前做一次过滤。你复现时不要跳过这一步，否则后期推荐结果明明是同一批电影，查出来的路径却缺胳膊少腿。
3.3 验证导入结果：用 Cypher 查一下图谱分布
导入完成后，别急着写推荐算法。先打开 Neo4j Browser，执行几条计数查询，确认图谱规模符合预期。源码的verify.py里放了几条标准语句：
// 查看节点数量分布 MATCH (n) RETURN labels(n) AS label, count(*) AS cnt; // 查看关系数量分布 MATCH ()-[r]->() RETURN type(r) AS rel, count(*) AS cnt; // 检查孤立电影（没有任何类型关系的电影） MATCH (m:Movie) WHERE NOT (m)-[:BELONGS_TO]->(:Genre) RETURN m.title LIMIT 20;执行结果里，如果第三类查询返回超过 100 条，说明类型关系导入有问题。最常见的原因是格式不一致：TMDB 返回的类型名有的是“Science Fiction”，有的“Sci-Fi”，清洗时没统一。源码里维护了一个类型映射字典，把常见别名归一化成标准名。这个字典在tmdb_normalize.py里，你如果自己抓数据，也建议先跑一遍归一化，再做MERGE。
4. 推荐算法实现：基于图路径与 PageRank 的混合召回
4.1 图算法选型：为什么选 PageRank + 最短路径
这份源码的推荐算法不是单纯靠某一种，而是“规则召回 + 图算法排序”的组合。规则召回解决“用户可能喜欢什么”，图算法解决“用户最该先看什么”。PageRank 在这里的作用是给节点重要度打分，但不直接对用户偏好建模，而是用在“相似电影”的排序上。最短路径则用来生成推荐解释——找出用户看过的电影到候选电影之间的路径，路径上的中间节点就是解释素材。这两者配合起来的优势是：召回阶段保证相关性，排序阶段保证流行度，解释阶段保证可读性。如果你只用 PageRank，推荐结果会偏向高热度电影，和用户喜好没关系；只用路径规则，冷门小众电影会被疯狂推荐，因为它在图里连接度低，路径反而更短。源码里把两个分数叠加，最终排序分 = 0.6 * 路径匹配分 + 0.4 * PageRank 分。
4.2 基于 Cypher 的规则召回：找“可能喜欢”的三条路径
源码里定义了三个召回规则，全部用 Cypher 实现，在recall.py里可以单独调试。
第一个规则是“联合导演”：用户喜欢的电影和候选电影有同一个导演。
MATCH (u:User {user_id: $uid})-[:RATED]->(m1:Movie) MATCH (m1)<-[:DIRECTED]-(p:Person) MATCH (p)-[:DIRECTED]->(m2:Movie) WHERE m1.movie_id <> m2.movie_id RETURN DISTINCT m2.movie_id AS candidate, count(p) AS shared_directors这段逻辑是：找到用户评分过的电影m1，再找到这些电影的导演，再看导演还导过什么其他电影m2。shared_directors表示同一个导演出现的次数，次数越高，候选电影越可能是用户喜欢的类型。注意m1.movie_id <> m2.movie_id这个条件不能丢，否则自己会成为自己的推荐项。
第二个规则是“类型延伸”：从用户喜欢的电影类型出发，找同类型但年份更新的电影。
MATCH (u:User {user_id: $uid})-[:RATED]->(m1:Movie) MATCH (m1)-[:BELONGS_TO]->(g:Genre) MATCH (m2:Movie)-[:BELONGS_TO]->(g) WHERE m1.movie_id <> m2.movie_id AND m2.year >= $year_threshold RETURN DISTINCT m2.movie_id AS candidate, count(g) AS shared_genres第三个规则是“合作演员”：用户喜欢的电影的演员，在其他电影里合作过其他演员，那些电影作为候选。
这条规则我用代码展示，因为它的召回量最丰富，也最容易产生噪音：
def recall_by_actor_cooccurrence(uid, top_n=50): query = """ MATCH (u:User {user_id: $uid})-[:RATED]->(m1:Movie) MATCH (m1)<-[r:ACTED_IN]-(p1:Person) MATCH (p1)-[:ACTED_IN]->(m2:Movie) WHERE m1.movie_id <> m2.movie_id WITH m2, collect(DISTINCT p1.name) AS co_actors ORDER BY size(co_actors) DESC RETURN m2.movie_id AS candidate, co_actors LIMIT $top_n """ return graph.run(query, uid=uid, top_n=top_n).data()参数top_n控制召回上限，co_actors就是候选电影和用户历史上演员的交集。我在复现时发现，这条规则会让商业大片霸榜，因为大片演员数量多、交集自然大。源码的处理方式是对演员交集做一次逆文档频率加权，类似 TF-IDF，但实现里直接用的是“演员数量越少、共现权重越高”。你在改造时，可以把size(co_actors)替换成sum(1.0 / actor_degree)，效果会好很多。
4.3 用 py2neo 调用 GDS 库：计算 PageRank 并生成推荐列表
Neo4j 的图数据科学库需要额外安装插件，源码里没有打包插件 JAR，但提供了安装说明。如果你不想装 GDS，还有一个轻量做法：用 Cypher 自己写一个简化版 PageRank，但那样性能很拉胯。我建议按源码的说明装。
from neo4j import GraphDatabase driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password")) def compute_pagerank(): with driver.session() as session: session.run(""" CALL gds.graph.project('movie_graph', 'Movie', { ACTED_IN: {orientation: 'UNDIRECTED'}, DIRECTED: {orientation: 'UNDIRECTED'}, BELONGS_TO: {orientation: 'UNDIRECTED'} }) """) session.run(""" CALL gds.pageRank.stream('movie_graph', { maxIterations: 20, dampingFactor: 0.85 }) YIELD nodeId, score WITH gds.util.asNode(nodeId) AS m, score SET m.pagerank = score """)这里orientation: 'UNDIRECTED'是精髓。推荐场景里，ACTED_IN从演员指向电影，如果我们只沿出方向跑 PageRank，电影永远只会被演员“指向”，概率会积压在电影节点上，而演员节点几乎得不到分。改成无向边后，演员和电影互相传导权重，才符合“合作网络”的直觉。maxIterations: 20和dampingFactor: 0.85是 Ne4j 默认配置，对电影网络足够收敛。如果图谱很小（几千个节点），你可以把maxIterations降到 10，速度更快且分数差别不大。
最终推荐列表生成在recommender.py里：先把三个召回候选取并集，再左连接 PageRank 分数，最后按0.6 * 规则分 + 0.4 * pagerank排序。规则分怎么算？源码里把每个规则产生的shared_*字段做 Min-Max 归一化，然后取均值。这一步要单独注意：shared_genres和shared_directors的数量级不一样，直接相加等于让类型权重碾压导演权重。源码写了一个normalize_scores()函数，你复现时最好自己看一眼有没有被改动过。
5. 避坑实录：我在这个项目里翻过的四类车
5.1 现象：中文电影名乱码，图谱里全是 \uXXXX
第一次跑fetch_tmdb.py后，打开 Neo4j Browser 看到电影标题全是\u300a之类的东西。原因是 TMDB 的title字段本身是中文，而源码在写入 JSON 缓存时用了ensure_ascii=True，导致中文被转义。解决：把缓存文件的json.dump参数改成ensure_ascii=False，同时 Neo4j 连接串里加上?charset=utf8（实际上 Neo4j Bolt 协议不需要这个参数，真正的问题是写入时被转义）。改完后删掉缓存重新抓一遍，或者写一段脚本把现有缓存里的\uXXXX还原成中文。
5.2 现象：MERGE 用错导致重复节点，推荐结果漂移
我图省事，把节点的唯一键属性从movie_id换成title，结果《蝙蝠侠:黑暗骑士》和《蝙蝠侠：黑暗骑士》因为冒号全角半角不同，被当成两个节点。后续MATCH时shared_directors的计数被严重分割，推荐排序完全跑偏。解决：严格使用movie_id做唯一键；同时把title字段统一做一次 Unicode 规范化，全角冒号转半角、牛/裏这类异体字统一为简体。
5.3 现象：Neo4j 内存溢出，导入 10 万条就挂
原因有两个：第一，Neo4j Community 版默认堆内存只有 512MB，处理大UNWIND时直接 OOM；第二，导入时没有先关闭自动索引。解决：在neo4j.conf里调高dbms.memory.heap.max_size=2G，页面缓存改成4G。另外，把import_movies的chunk_size从 500 降到 200，多跑几批，内存占用肉眼可见地降下来。批量UNWIND的耗时和chunk_size不是线性的，200 到 500 之间性能差距不大，但内存差距很大，建议别贪。
5.4 现象：Flask 后端 Cypher 查询超时，页面转圈十秒
源码的 Web 端用的是 Flask，每次请求推荐都实时执行四条 Cypher，每条都要全图扫描。因为我没有在movie_id、person_id上建索引，每次MERGE和MATCH都是全库扫，三千个节点的图还能忍，三万节点就废了。解决：在导入数据前执行CREATE INDEX movie_id FOR (m:Movie) ON (m.movie_id);，同理给 Person、Genre、Country 都建索引。建完索引后，同样的查询从几秒降到毫秒级。这也是源码schema.cypher里做的事，别跳过 schema 初始化脚本。
6. 把这套系统做厚：加用户行为边、做推荐解释、上可视化
6.1 加入“用户-观看”关系，从静态图谱升级为动态图谱
源码默认只用了用户的评分数据作为RATED边，但如果你想让推荐更贴近真实场景，我建议加一条WATCHED边：用户观看某部电影，且没有评分。逻辑上，RATED边体现强偏好，WATCHED边体现弱信号。在图里同时保留两种关系，可以在召回时给它们分配不同权重。改动很小，只需要在import_user_actions里增加一个关系类型：
MERGE (u:User {user_id: $uid}) MERGE (m:Movie {movie_id: $mid}) MERGE (u)-[:WATCHED {watch_time: $timestamp}]->(m)加完边以后，召回规则里可以加一条：“用户看过的电影的导演，其新片优先推荐”。这比只看评分数据覆盖更多长尾需求——很多用户看完即走，根本不会打分。
6.2 推荐解释：让算法说人话
知识图谱推荐最大的卖点就是可解释性。源码里推荐接口的返回结构里有一个explanation字段，生成方式就是查询用户已看过的电影到推荐电影之间的最短路径：
MATCH path = shortestPath( (u:User {user_id: $uid})-[:RATED]->(m1:Movie) -[*..4]-(m2:Movie {movie_id: $candidate}) ) RETURN path拿到路径后，解析节点和关系，拼成“你打过五星的《盗梦空间》由克里斯托弗·诺兰导演，他导的《星际穿越》和它同属科幻片，所以推荐给你”。这一步不需要额外训练模型，纯粹是路径还原。我在实际做的时候发现，路径长度超过 3 的解释会变得牵强，比如“A 演员和 B 演员合作过，B 演过 C 导演的电影，C 导演导过推荐电影”——这种解释用户看不懂。源码里把-[*..4]限制到了 3，优先保留直接合作和同导演的路径，效果明显好。
6.3 可视化与评估：不要只会截图给老师看
Neo4j Browser 可以直接从MATCH (n) RETURN n得到图谱可视化，但节点太密是看不清的。我建议你在答辩时，特意展示一条推荐解释路径的可视化，而不是全图。操作是选中推荐接口返回的一个explanation，在 Browser 里执行对应的MATCH语句。评估方面，源码没有集成复杂的离线评估，只做了一个简单的“命中率”脚本：把用户评分的数据按时间切分，前 70% 用来生成图谱，后 30% 用来测试推荐结果是否命中真实观看记录。你可以把这个脚本跑出来，得到一个准确率数值，作为毕设数据支撑。这一招做起来很轻，但答辩时比纯截图有力得多。
我从这个项目里最大的收获是：知识图谱推荐的核心不是算法有多先进的模型，而是关系建模是否贴近业务语义。源码把电影领域的本体和关系理得很干净，我后来在自己的工业项目里也沿用了这套结构——只不过把 Movie 换成了物料，把 Person 换成了供应商，把 ACTED_IN 换成了 SUPPLY。从那以后，我每次做推荐系统都会先花一天时间画清楚实体和关系图，再写代码，省掉了后面大半的返工。希望这份拆解能帮你在毕设或工程里少走点弯路。
本文还有配套的精品资源，点击获取
