简介面向毕业设计及课程实践提供一套结合知识图谱与图神经网络KGCN的电影推荐系统Python完整源码。系统涵盖数据处理、知识图谱构建、模型训练、Web端推荐展示等环节并附带部署说明适合需要参考完整工程实现或快速上手图神经网络项目的学习者。压缩包共37个文件以21个Python脚本为主涵盖数据加载、模型、工具函数等同时包含5个dat数据集文件、5个zbak备份文件以及readme/md说明文档整体体积14.88MB。当前已有49人学习下载。代码按数据层、模型层、应用层组织注释较详细附有多个辅助脚本与备份文件可帮助理解从kg_loader、data_loader到KGCN layer与model的完整流程也便于在本地复现电影推荐效果并扩展实验。1. 当传统推荐算法解释不了「你为什么会喜欢这部电影」电影推荐的冷启动和可解释性一直是协同过滤的硬伤用户历史行为稀疏时相似度矩阵几乎失效就算推荐命中系统也说不清到底是哪个特征打动了用户。把知识图谱和图神经网络一起搬进来相当于给推荐系统配了一张「行业关系网」和一个能在这张网上自动做信息聚合的「特征提取器」电影、演员、导演、类型、用户历史行为被建成了三元组图结构GNN 沿着关系路径把邻居信息一层层聚合到目标节点上最终输出的向量既保留了内容语义又能融合用户偏好。这篇文章面向的读者是手里有一定 Python 功底、想从单机 demo 走向可部署工程的开发者或者正在做毕设/项目申报、需要一个能讲清原理又能交出完整源码包的团队。全文按「图怎么建 → 模型怎么选 → 系统怎么拼 → 部署怎么稳」的顺序展开每一步都给出参数和踩坑记录。2. 知识图谱构建从 MovieLens 原始表到三元组与邻接矩阵2.1 为什么电影推荐场景最适合用知识图谱传统 ItemCF 算的是「买了 A 的人也买了 B」但电影推荐的核心逻辑是「因为演员、导演、类型、主题曲这些实体关系所以这部电影与另一部相关」。知识图谱把这种关系显式编码为三元组(头实体, 关系, 尾实体)例如(《盗梦空间》, 主演, 莱昂纳多)、(莱昂纳多, 参演, 《荒野猎人》)。推荐系统拿到的不再是扁平的评分矩阵而是一张可以多跳查询的关系网络。好处有两个层面第一冷启动用户只要有 35 条历史行为就能通过「用户—电影—演员—其他电影」的二跳关系找到候选集第二可解释性好图谱路径本身就是推荐理由这在做技术答辩或项目汇报时是天然加分项。常见做法是用 MovieLens 1M 数据集加上 IMDb 的附加演员/导演表来补全实体关系——这样不用自己爬数据也绕开了版权风险。2.2 原始表到三元组实体映射与关系去重MovieLens 1M 解压后有三个核心文件movies.dat电影ID、标题、类型、ratings.dat用户ID、电影ID、评分、时间戳、users.dat用户画像。但movies.dat里没有演员和导演需要预先准备一份 IMDb 或 TheMovieDB 的补充数据常见做法是把movies.dat里的电影标题和年份作为连接键去关联外部 API或者直接用研究圈常用的kg.csv数据集包含约 5 万部电影和 10 万实体关系。下面是构建三元组的核心脚本骨架# build_kg.py import pandas as pd from collections import defaultdict # 1. 加载电影类型字段拆分成 (movie_id, 关系, 实体) 三元组 movies pd.read_csv(ml-1m/movies.dat, headerNone, sep::, names[mid, title, genres], enginepython) # 类型字段用 | 分隔一部电影可能有多个类型 genre_triples [] for row in movies.itertuples(): for genre in row.genres.split(|): genre_triples.append((row.mid, belongs_to, genre)) # 2. 加载外部演员/导演表假设列名固定 casts pd.read_csv(kg_casts.csv, sep,) # 含 mid, actor_name, director_name cast_triples [] for row in casts.itertuples(): cast_triples.append((row.mid, stars_in, row.actor_name)) cast_triples.append((row.mid, directed_by, row.director_name)) # 3. 合并并去重统计实体/关系数 all_triples list(set(genre_triples cast_triples)) entity_set set() for h, r, t in all_triples: entity_set.add(h) entity_set.add(t) print(f三元组总量: {len(all_triples)}) print(f实体总量: {len(entity_set)}) # 导出三元组文件模型读取用 with open(kg_final.txt, w) as f: for h, r, t in all_triples: f.write(f{h}\t{r}\t{t}\n)逻辑说明先把电影的类型字段转成belongs_to关系这是成本最低的三元组来源再从补充表里读演员和导演分别映射成stars_in与directed_by。最后用集合去重避免重复三元组导致后续邻接矩阵出现重边。参数说明ratings.dat的最低评分阈值一般定在 4 分以上只把「真正喜欢」的行为纳入训练users.dat里的职业、年龄字段如果暂时不用就别塞进图谱——实体太多会让邻接矩阵膨胀训练速度大幅下降。2.3 实体与关系编号映射以及邻接矩阵的稀疏存储图神经网络不能直接吃字符串实体名必须先给每个实体分配整数 ID、每种关系分配整数 ID再构建统一的 ID 映射表。这一步疏忽很容易在后续模型加载时报KeyError因为训练集和测试集的映射字典不一致。# build_mapping.py import numpy as np from scipy.sparse import coo_matrix entity2id {} id2entity {} relation2id {} id2relation {} # 读三元组文件生成映射 triples [] with open(kg_final.txt, r) as f: for line in f: h, r, t line.strip().split(\t) triples.append((h, r, t)) if h not in entity2id: entity2id[h] len(entity2id) id2entity[entity2id[h]] h # 尾实体和关系同样的逻辑省略 # 构建稀疏邻接矩阵 rows, cols, vals [], [], [] for h, r, t in triples: h_id entity2id[h] t_id entity2id[t] # 这里做一步关键处理把正向边和反向边都加进去 rows.append(h_id); cols.append(t_id); vals.append(1) rows.append(t_id); cols.append(h_id); vals.append(1) adj coo_matrix((vals, (rows, cols)), shape(len(entity2id), len(entity2id))) # 转成 CSR 格式训练时按行切片取邻居 adj_csr adj.tocsr() np.savez_compressed(kg_adj.npz, dataadj_csr.data, indicesadj_csr.indices, indptradj_csr.indptr, shapeadj_csr.shape)逻辑说明coo_matrix适合构建邻接矩阵因为三元组天然是坐标格式转csr_matrix后取某个实体的一阶邻居就变成adj_csr.indices[adj_csr.indptr[i]:adj_csr.indptr[i1]]这比密集矩阵存储省掉几个数量级的内存。参数说明对于 MovieLens 1M 规模约 1 万部电影、几千演员邻接矩阵如果做成稠密的NxN浮点矩阵内存轻松超过 800MB转稀疏 CSR 后通常只有 1020MB。如果你的环境内存吃紧原因 80% 出在没用稀疏存储。2.4 用户行为子图的构建逻辑知识图谱管的是「内容与内容的关系」用户行为是另一张子图(user_id, 评分过, movie_id)。需要把行为子图和内容子图拼成一张图这样 GNN 在更新某个电影的节点向量时才能同时看到「它的导演是谁」和「哪些用户喜欢它」。计算过程简单说就是把用户节点也塞进实体表用户 ID 偏移到实体数之后再加一条rate关系。最终 GNN 输入由三部分组成实体向量表随机初始化或预训练、邻接矩阵负责邻居聚合、用户-物品交互矩阵负责监督信号。这三部分在后面的模型代码里会一一对应。一个小建议行为子图直接按评分 4 建立正边评分 4 的关系不要进图否则模型会把「不喜欢」和「没看过」混为一谈推荐准确率掉得很快。3. 图神经网络选型从 GCN 到 KGCN为什么不能盲目堆层数3.1 GCN 原理回顾与在推荐任务上的局限图卷积网络的核心操作是「邻居聚合 特征变换」每个节点的表示等于自身特征和邻居特征的加权求和再经过一个可学习的线性变换。单层 GCN 只能看到一阶邻居两层 GCN 能看到二跳关系比如用户 → 电影 → 演员 → 演员参演的其他电影。标准 GCN 在推荐上有两个局限第一它的边权重是简单的 0/1 或度归一化没有区分关系的语义类型——「导演」和「主演」都被当成同一种「相邻」这不符合电影推荐的直觉第二GCN 不分关系类型、不分邻居重要程度导致高度活跃实体比如参演过几百部电影的老戏骨会稀释掉聚合特征。解决前者用 R-GCN 或 KGCN解决后者用注意力机制。3.2 为什么推荐更常用 KGCN关系感知的邻域聚合KGCN 是为「知识图谱推荐」设计的模型它给每种关系分配一个独立的线性变换矩阵并在聚合时引入注意力权重注意力权重 softmax(邻居节点向量 v_i 与目标节点向量 u 的内积)。通俗讲就是模型自己去学「哪些邻居对当前用户更重要」——用户喜欢科幻片那么《星际穿越》的「类型 科幻」这条邻居的注意力权重会被拉高用户是诺兰粉那「导演 诺兰」这条边的权重也会上涨。注意力公式可以写成score σ(u^T · W_r · v_i)其中W_r是关系 r 的变换矩阵σ是激活函数。这个设计比普通 GCN 多做了一步「用户感知」——同一个邻居节点在给不同用户做推荐时聚合权重是不同的。这是 KGCN 能超过 GCN 基线的主要来源。3.3 从零实现 KGCN 聚合层与用户评分预测KGCN 的代码实现并不复杂,核心是采样邻居 加权聚合 输出预测分数。以下给出聚合层和预测层的核心实现# kgcn_model.py import torch import torch.nn as nn import torch.nn.functional as F class KGCNLayer(nn.Module): def __init__(self, in_dim, out_dim, n_relations): super().__init__() # 每种关系一个变换矩阵 self.relation_w nn.Parameter( torch.randn(n_relations, in_dim, out_dim) * 0.1 ) self.self_transform nn.Linear(in_dim, out_dim) def forward(self, entity_emb, neighbor_emb, relation_ids): # entity_emb: 中心节点向量 [batch, in_dim] # neighbor_emb: 采样邻居向量 [batch, n_neighbor, in_dim] # relation_ids: 每条边对应的关系ID [batch, n_neighbor] batch_size, n_neighbor, _ neighbor_emb.shape # 根据关系ID取出对应的变换矩阵 rel_w self.relation_w[relation_ids] # [batch, n_neighbor, in_dim, out_dim] # 邻居向量经过关系变换: [batch, n_neighbor, out_dim] transformed torch.einsum(bni,bnij-bnj, neighbor_emb, rel_w) # 注意力分数用中心节点与变换后邻居向量做内积 attn torch.sum(entity_emb.unsqueeze(1) * transformed, dim-1) attn torch.softmax(attn, dim-1) # [batch, n_neighbor] # 加权聚合邻居 agg torch.sum(attn.unsqueeze(-1) * transformed, dim1) # 残差连接回自身 out F.relu(self.self_transform(entity_emb) agg) return out class KGCN(nn.Module): def __init__(self, n_entities, n_relations, embed_dim, n_layers): super().__init__() self.entity_emb nn.Embedding(n_entities, embed_dim) self.layers nn.ModuleList([ KGCNLayer(embed_dim, embed_dim, n_relations) for _ in range(n_layers) ]) def forward(self, user_emb, movie_emb, neighbor_embs, relation_ids): # 逐层更新电影节点表示 x movie_emb for layer, neigh, rel in zip(self.layers, neighbor_embs, relation_ids): x layer(x, neigh, rel) # 预测分数用户向量与更新后电影向量内积 score torch.sum(user_emb * x, dim-1) return torch.sigmoid(score)逻辑说明neighbor_embs是在每个训练步从邻接矩阵里实时采样的固定数量邻居向量采样数量是超参数n_neighbor常见设为 816。torch.einsum在这里做的是一次小批量内所有邻居的关系变换比循环快很多。注意力内积把中心节点和邻居变换后的向量做相似度打分softmax 后再加权求和。残差连接让模型更深时也不容易梯度消失。参数说明嵌入维度embed_dim推荐 3264 之间维度太高在 1M 数据下容易过拟合n_layers不要超过 3最好直接设为 2。原因在于电影图谱的平均最短路径很短——「诺兰 → 蝙蝠侠 → 科幻类型 → 其他科幻片」只需要两跳就能覆盖大量候选电影。层数再多所有节点向量趋于同质化推荐精度不升反降这是图神经网络里常见的「过平滑」现象。3.4 训练策略BPR 损失与负采样KGCN 的监督信号来自用户的历史行为但评分是一个隐式反馈问题。把「看过并打了 4 分以上」视为正样本用贝叶斯个性化排序 BPR 损失来拉大正样本和负样本的得分差# train.py 核心训练循环片段 def bpr_loss(pos_scores, neg_scores): # 目标是让正样本得分明显高于负样本 return -torch.log(torch.sigmoid(pos_scores - neg_scores)).mean() for epoch in range(n_epochs): for batch in train_loader: # 每个正样本配 5 个随机负样本 pos_scores model(user_emb, pos_movie_emb, pos_neigh, pos_rel) neg_scores model(user_emb, neg_movie_emb, neg_neigh, neg_rel) loss bpr_loss(pos_scores, neg_scores) optimizer.zero_grad() loss.backward() optimizer.step()逻辑说明BPR 不要求预测分数接近真实评分只要求正样本大于负样本。这比 MSE 回归更合理因为用户打 4 分还是 5 分的主观差异很大模型没必要纠结这个数字。每个正样本配 5 个负样本是常用的策略太少则负样本区分度不够太多则训练时间呈线性上升收益递减。参数说明学习率建议从0.001起步使用 Adam 优化器权重衰减设1e-5。batch size 在 1024 到 4096 之间——KGCN 的邻居聚合操作对显存不敏感batch 大一点反而能让 GPU 的矩阵运算更饱满。关键超参数还有一个l2_reg如果发现训练集 loss 持续下降而验证集 Recall5 不涨先把正则系数往上调。4. 把模型组装成系统Flask 服务、推荐接口与前端联动4.1 项目目录结构与源码模块划分拿到完整源码包后先别急着跑把目录结构看一眼。一个能交付的系统至少应该是 Datasets / Models / Services / Controllers / Static 五个模块分离的而不是一个main.py里堆一千行。movie_kg_recsys/ ├── datasets/ │ ├── ml-1m/ # 原始 MovieLens 数据 │ └── preprocess.py # 数据清洗与三元组构建脚本 ├── models/ │ ├── kgcn.py # 图神经网络模型定义 │ ├── train.py # 训练与模型保存 │ └── recommend.py # 加载模型、生成召回结果 ├── services/ │ ├── graph_storage.py # 用 NetworkX SQLite 管理图谱 │ └── recommender.py # 推荐服务封装 ├── controllers/ │ └── api.py # Flask 蓝本RESTful 接口 ├── static/ │ ├── index.html # 页面入口 │ └── app.js # 前端请求与渲染逻辑 ├── weights/ │ └── kgcn_epoch20.pth # 训练好的模型权重 └── requirements.txt这个结构的好处是训练代码和部署代码隔离模型换版本时只需要替换weights/目录下的权重文件API 层不用动。requirements.txt里锁定torch2.0、flask2.3、pandas1.5、networkx3.1这些版本避免部署时因 numpy 版本冲突报np.bool不存在这类低级错误。4.2 提供 RESTful 推荐接口接收用户 ID返回电影列表模型训练完成后推荐服务的工作分两步先从训练好的 KGCN 里取用户 Embedding 和电影 Embedding然后对全量电影做打分排序。打分可以在内存里用矩阵乘法一次算完不需要每次请求都重新跑 GNN。# services/recommender.py import torch from models.kgcn import KGCN class MovieRecommender: def __init__(self, model_path, entity_emb_path, movie_id_map): self.device torch.device(cuda if torch.cuda.is_available() else cpu) self.model KGCN( n_entities100000, n_relations8, embed_dim64, n_layers2 ) self.model.load_state_dict(torch.load(model_path, map_locationself.device)) self.model.eval() # 预先抽好所有电影向量避免重复计算 self.user_emb torch.load(entity_emb_path, map_locationself.device) self.movie_id_map movie_id_map # {imdb_id: 内部实体ID} def recommend(self, user_id, top_k20): # 从 user_emb 里取该用户向量 user_vec self.user_emb[user_id].unsqueeze(0) # [1, dim] # 所有电影向量与用户向量的内积 推荐分 scores torch.mm(user_vec, self.model.entity_emb.weight.T) scores scores.squeeze(0) # 过滤掉用户已经看过的电影可选但强烈建议 top_k_ids torch.topk(scores, top_k).indices.tolist() return [self.movie_id_map[i] for i in top_k_ids]逻辑说明推荐阶段的关键优化是把模型切到eval()模式并且只保留最终的实体嵌入矩阵参与矩阵乘法。torch.mm一次能算出用户对所有电影的打分这在 1 万部电影规模的本地机器上只要几十毫秒。如果用户数量级很大可以提前把用户向量矩阵整体保存请求时做user_emb[user_id]索引内存和速度都会好。参数说明top_k在线上环境设 2050 即可如果接入前端页面轮播图一次返回 20 部足够。过滤已看电影这个逻辑最好写在推荐函数内部而不是前端过滤否则前端拿到列表可能不够 20 个页面就会缺位。4.3 前端页面联动搜索框、电影卡片与「推荐理由」展示前端页面用原生 HTML jQuery 是最省事的方案不需要构建工具链。第一步把训练好的模型权重加载到 Flask 服务里第二步在静态文件里用fetch调用推荐接口第三步把电影信息和推荐路径渲染到卡片上。推荐理由的展示是整套系统的差异点后端在图谱里保存了路径信息比如用户A → 喜欢《盗梦空间》 → 导演诺兰 → 执导《星际穿越》。推荐时把这条路径作为文本放在电影卡片的下方用户能一眼看懂推荐逻辑。这一步的实现方式是召回阶段不仅保留电影 ID还同时从graph_storage里查询「电影 → 关系 → 电影」的连接路径把路径的最后一个实体转成自然语言字符串。前端调用接口的代码简版如下// static/app.js async function loadRecommendations(userId, topK) { const resp await fetch(/api/recommend?user_id${userId}top_k${topK}); const data await resp.json(); const container document.getElementById(movie-grid); container.innerHTML ; data.movies.forEach(item { const card document.createElement(div); card.className movie-card; card.innerHTML h3${item.title}/h3 p${item.genres}/p p classreason推荐理由: ${item.reason_path}/p span classscore${item.pred_score.toFixed(2)}/span ; container.appendChild(card); }); }逻辑说明推荐理由路径item.reason_path是推荐系统可解释性的直接体现也方便在答辩或演示时快速说明模型内部行为。前端fetch 到 JSON后直接渲染卡片不需要刷新页面。用 jQuery 也行但原生 fetch 能少引一个依赖。5. 实战避坑清单图数据、训练和部署中最常见的 5 个翻车点5.1 现象训练到第 3 个 epoch loss 变成 NaN通常原因有两个方向。第一邻接矩阵里有自环或者重复边导致归一化权重分母出现零第二学习率太大关系变换矩阵relation_w初始化不当导致梯度爆炸。解决方法是构建矩阵时显式去掉对角线元素relation_w初始化标准差从 0.1 调到 0.01学习率降到5e-4再试。如果 loss 仍然不稳定检查是否有实体 ID 映射越界——训练集和验证集用了两套映射字典时越界会让 Embedding 查到随机初始化的向量表现就是 loss 异常跳动。5.2 现象MemoryErrorPython 进程直接被杀掉MovieLens 1M 本身很小但如果你导入ratings.dat时用了sep::却忘记指定enginepythonpandas 会在 C 引擎下把整个文件当一列读入内存直接爆掉。另一个常见元凶是构建稠密邻接矩阵时用了np.zeros((n_entities, n_entities))20000 实体 × 20000 × 8 字节就是 3.2GB。解决方法是全部改用scipy.sparse并通过train_test_split把数据切小对测试环境只载入训练子图。5.3 现象模型训练完推荐结果全是热门电影这是隐式反馈训练中典型的流行度偏差。原因在于越流行的电影在训练集里被点击的次数越多BPR loss 在优化时会把「模型倾向」往高频样本上带。解决方式分两步负采样时按流行度降采样热门电影作为负样本的概率调低评估指标不用整体的 Recall而是看Recall5在长尾电影切片上的表现。如果长尾召回率低于整体均值 30% 以上说明模型没有学到内容语义只是在背热度。5.4 现象Flask 接口响应慢每次请求都要等 3 秒最常见的原因是把「加载模型参数 构建用户向量」写进了每个请求的处理函数里。torch.load一次就有几百毫秒加上从磁盘读 Embedding攒到几秒很正常。解决方法是Flask 应用启动时用全局变量缓存模型对象只在__init__阶段载入一次接口内部只做向量索引和矩阵乘法。更稳妥的做法是用gunicorn跑多 worker 时把模型放到共享内存或者每个 worker 启动时加载并常驻。5.5 现象换一台机器跑不起来torch和numpy版本冲突把本地环境的requirements.txt直接pip install -r在干净服务器上往往报各种 C 扩展错误。原因多数是本地装了 GPU 版 torch服务端没有 NVIDIA 驱动pip 解析到不匹配的 CUDA 版本。解决办法是部署机上先执行python -c import torch; print(torch.__version__)确认能正常导入然后按部署机是否支持 CUDA 来决定安装 CPU 版还是 GPU 版模型代码里已经做了torch.device(cuda if torch.cuda.is_available() else cpu)逻辑会自动降级。6. 部署到 Ubuntu 服务器用 Gunicorn 托管 Flask并用 Docker 固定环境6.1 为什么选 Ubuntu 作为部署目标标题里提到的部署指南最常见的目标环境是 Ubuntu 20.04 或 22.04 云服务器。相比于 WindowsLinux 下的 Python 包编译链更干净内存管理更稳而且用systemd守护 Flask 进程后可以做到崩溃自动重启。Ubuntu 的安装路径上没有奇怪的中文用户目录torch模型路径不会出现编码问题。如果你的开发机是 Windows建议把训练好的.pth权重文件通过scp上传到服务器部署环节不要在 Windows 上跑。6.2 安装依赖与启动 Gunicorn 多进程部署过程分三步创建虚拟环境、安装依赖、用 Gunicorn 启动。下面是一套可直接照抄的部署命令# deploy.sh 部署脚本片段 sudo apt update sudo apt install -y python3.10-venv nginx # 1. 虚拟环境与依赖 python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 2. 确认 torch 能正常导入重要先跑这一句 python -c import torch; print(torch.__version__) # 3. 启动服务4 个 worker每个 worker 常驻模型 gunicorn -w 4 -b 127.0.0.1:8000 \ --timeout 120 \ --preload \ wsgi:app逻辑说明--preload让 master 进程先加载模型再 fork 出 4 个 worker这样每个 worker 共享内存里的模型参数避免每个 worker 重复torch.load导致内存翻四倍。--timeout 120是因为冷启动加载模型可能需要几秒默认 30 秒超时会导致 worker 被杀。-b 127.0.0.1:8000绑定内网地址外部请求由 Nginx 转发这样更安全也方便加 HTTPS。参数说明worker 数量不是越多越好推荐2 × CPU核数 1。4 核服务器开 4 个 worker 即可如果每个请求的矩阵乘法压力大实际验证下 CPU 占用率和接口延迟把 worker 数压到 2 反而更稳定。6.3 Nginx 反向代理与域名访问Gunicorn 监听内网端口后用 Nginx 做反向代理把公网流量转到127.0.0.1:8000。Nginx 还能顺带缓存静态资源——前端页面和 JS 文件不必经过 Flask直接由 Nginx 返回。server { listen 80; server_name your_domain.com; # 前端静态文件 location /static/ { alias /home/ubuntu/movie_kg_recsys/static/; expires 7d; } # API 反向代理 location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 120s; } }重启 Nginx 后访问http://your_domain.com就能直接看到前端页面调用/api/recommend接口时请求会被 Nginx 转发给 Gunicorn。proxy_read_timeout 120s很关键如果不加遇到首次请求模型初始化导致的 23 秒延迟时Nginx 会返回 504 网关超时。6.4 用 Docker 固定环境避免反复踩依赖坑如果你嫌多台服务器手动配环境太累最省心的方式是打包成 Docker 镜像。镜像内部固定 Python 3.10 依赖版本宿主机只需要有 NVIDIA 驱动GPU 场景即可。Dockerfile 的关键点FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [gunicorn, -w, 2, -b, 0.0.0.0:8000, --preload, wsgi:app]逻辑说明基础镜像用python:3.10-slim而不是ubuntu镜像体积更小、包管理一致性更好。COPY . .会把整个工程拷进镜像weights/目录里的模型权重也在其中所以--preload在这里不仅省内存还缩短了镜像启动时间。部署完以后做一次端到端验证先curl http://127.0.0.1:8000/api/recommend?user_id1top_k10看 JSON 是否返回再打开前端页面确认电影卡片能正常渲染。如果推荐结果和本地开发机不一致先怀疑数据处理阶段是否有随机种子——训练前给torch.manual_seed(42)和np.random.seed(42)打上这样任何机器上复现结果都是相同的排查问题会快很多。我在实战中养成的习惯是每次改完模型配置先把验证集上 Recall5 的数字记录在代码注释里再上服务器。因为部署环境跑一遍训练很耗时有基线数字打底才能在调参时判断「效果变好了还是玄学波动」。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/27 8:32:39 · 阅读 1.2k 知识图谱与图神经网络驱动电影推荐系统实战
简介面向毕业设计及课程实践提供一套结合知识图谱与图神经网络KGCN的电影推荐系统Python完整源码。系统涵盖数据处理、知识图谱构建、模型训练、Web端推荐展示等环节并附带部署说明适合需要参考完整工程实现或快速上手图神经网络项目的学习者。压缩包共37个文件以21个Python脚本为主涵盖数据加载、模型、工具函数等同时包含5个dat数据集文件、5个zbak备份文件以及readme/md说明文档整体体积14.88MB。当前已有49人学习下载。代码按数据层、模型层、应用层组织注释较详细附有多个辅助脚本与备份文件可帮助理解从kg_loader、data_loader到KGCN layer与model的完整流程也便于在本地复现电影推荐效果并扩展实验。1. 当传统推荐算法解释不了「你为什么会喜欢这部电影」电影推荐的冷启动和可解释性一直是协同过滤的硬伤用户历史行为稀疏时相似度矩阵几乎失效就算推荐命中系统也说不清到底是哪个特征打动了用户。把知识图谱和图神经网络一起搬进来相当于给推荐系统配了一张「行业关系网」和一个能在这张网上自动做信息聚合的「特征提取器」电影、演员、导演、类型、用户历史行为被建成了三元组图结构GNN 沿着关系路径把邻居信息一层层聚合到目标节点上最终输出的向量既保留了内容语义又能融合用户偏好。这篇文章面向的读者是手里有一定 Python 功底、想从单机 demo 走向可部署工程的开发者或者正在做毕设/项目申报、需要一个能讲清原理又能交出完整源码包的团队。全文按「图怎么建 → 模型怎么选 → 系统怎么拼 → 部署怎么稳」的顺序展开每一步都给出参数和踩坑记录。2. 知识图谱构建从 MovieLens 原始表到三元组与邻接矩阵2.1 为什么电影推荐场景最适合用知识图谱传统 ItemCF 算的是「买了 A 的人也买了 B」但电影推荐的核心逻辑是「因为演员、导演、类型、主题曲这些实体关系所以这部电影与另一部相关」。知识图谱把这种关系显式编码为三元组(头实体, 关系, 尾实体)例如(《盗梦空间》, 主演, 莱昂纳多)、(莱昂纳多, 参演, 《荒野猎人》)。推荐系统拿到的不再是扁平的评分矩阵而是一张可以多跳查询的关系网络。好处有两个层面第一冷启动用户只要有 35 条历史行为就能通过「用户—电影—演员—其他电影」的二跳关系找到候选集第二可解释性好图谱路径本身就是推荐理由这在做技术答辩或项目汇报时是天然加分项。常见做法是用 MovieLens 1M 数据集加上 IMDb 的附加演员/导演表来补全实体关系——这样不用自己爬数据也绕开了版权风险。2.2 原始表到三元组实体映射与关系去重MovieLens 1M 解压后有三个核心文件movies.dat电影ID、标题、类型、ratings.dat用户ID、电影ID、评分、时间戳、users.dat用户画像。但movies.dat里没有演员和导演需要预先准备一份 IMDb 或 TheMovieDB 的补充数据常见做法是把movies.dat里的电影标题和年份作为连接键去关联外部 API或者直接用研究圈常用的kg.csv数据集包含约 5 万部电影和 10 万实体关系。下面是构建三元组的核心脚本骨架# build_kg.py import pandas as pd from collections import defaultdict # 1. 加载电影类型字段拆分成 (movie_id, 关系, 实体) 三元组 movies pd.read_csv(ml-1m/movies.dat, headerNone, sep::, names[mid, title, genres], enginepython) # 类型字段用 | 分隔一部电影可能有多个类型 genre_triples [] for row in movies.itertuples(): for genre in row.genres.split(|): genre_triples.append((row.mid, belongs_to, genre)) # 2. 加载外部演员/导演表假设列名固定 casts pd.read_csv(kg_casts.csv, sep,) # 含 mid, actor_name, director_name cast_triples [] for row in casts.itertuples(): cast_triples.append((row.mid, stars_in, row.actor_name)) cast_triples.append((row.mid, directed_by, row.director_name)) # 3. 合并并去重统计实体/关系数 all_triples list(set(genre_triples cast_triples)) entity_set set() for h, r, t in all_triples: entity_set.add(h) entity_set.add(t) print(f三元组总量: {len(all_triples)}) print(f实体总量: {len(entity_set)}) # 导出三元组文件模型读取用 with open(kg_final.txt, w) as f: for h, r, t in all_triples: f.write(f{h}\t{r}\t{t}\n)逻辑说明先把电影的类型字段转成belongs_to关系这是成本最低的三元组来源再从补充表里读演员和导演分别映射成stars_in与directed_by。最后用集合去重避免重复三元组导致后续邻接矩阵出现重边。参数说明ratings.dat的最低评分阈值一般定在 4 分以上只把「真正喜欢」的行为纳入训练users.dat里的职业、年龄字段如果暂时不用就别塞进图谱——实体太多会让邻接矩阵膨胀训练速度大幅下降。2.3 实体与关系编号映射以及邻接矩阵的稀疏存储图神经网络不能直接吃字符串实体名必须先给每个实体分配整数 ID、每种关系分配整数 ID再构建统一的 ID 映射表。这一步疏忽很容易在后续模型加载时报KeyError因为训练集和测试集的映射字典不一致。# build_mapping.py import numpy as np from scipy.sparse import coo_matrix entity2id {} id2entity {} relation2id {} id2relation {} # 读三元组文件生成映射 triples [] with open(kg_final.txt, r) as f: for line in f: h, r, t line.strip().split(\t) triples.append((h, r, t)) if h not in entity2id: entity2id[h] len(entity2id) id2entity[entity2id[h]] h # 尾实体和关系同样的逻辑省略 # 构建稀疏邻接矩阵 rows, cols, vals [], [], [] for h, r, t in triples: h_id entity2id[h] t_id entity2id[t] # 这里做一步关键处理把正向边和反向边都加进去 rows.append(h_id); cols.append(t_id); vals.append(1) rows.append(t_id); cols.append(h_id); vals.append(1) adj coo_matrix((vals, (rows, cols)), shape(len(entity2id), len(entity2id))) # 转成 CSR 格式训练时按行切片取邻居 adj_csr adj.tocsr() np.savez_compressed(kg_adj.npz, dataadj_csr.data, indicesadj_csr.indices, indptradj_csr.indptr, shapeadj_csr.shape)逻辑说明coo_matrix适合构建邻接矩阵因为三元组天然是坐标格式转csr_matrix后取某个实体的一阶邻居就变成adj_csr.indices[adj_csr.indptr[i]:adj_csr.indptr[i1]]这比密集矩阵存储省掉几个数量级的内存。参数说明对于 MovieLens 1M 规模约 1 万部电影、几千演员邻接矩阵如果做成稠密的NxN浮点矩阵内存轻松超过 800MB转稀疏 CSR 后通常只有 1020MB。如果你的环境内存吃紧原因 80% 出在没用稀疏存储。2.4 用户行为子图的构建逻辑知识图谱管的是「内容与内容的关系」用户行为是另一张子图(user_id, 评分过, movie_id)。需要把行为子图和内容子图拼成一张图这样 GNN 在更新某个电影的节点向量时才能同时看到「它的导演是谁」和「哪些用户喜欢它」。计算过程简单说就是把用户节点也塞进实体表用户 ID 偏移到实体数之后再加一条rate关系。最终 GNN 输入由三部分组成实体向量表随机初始化或预训练、邻接矩阵负责邻居聚合、用户-物品交互矩阵负责监督信号。这三部分在后面的模型代码里会一一对应。一个小建议行为子图直接按评分 4 建立正边评分 4 的关系不要进图否则模型会把「不喜欢」和「没看过」混为一谈推荐准确率掉得很快。3. 图神经网络选型从 GCN 到 KGCN为什么不能盲目堆层数3.1 GCN 原理回顾与在推荐任务上的局限图卷积网络的核心操作是「邻居聚合 特征变换」每个节点的表示等于自身特征和邻居特征的加权求和再经过一个可学习的线性变换。单层 GCN 只能看到一阶邻居两层 GCN 能看到二跳关系比如用户 → 电影 → 演员 → 演员参演的其他电影。标准 GCN 在推荐上有两个局限第一它的边权重是简单的 0/1 或度归一化没有区分关系的语义类型——「导演」和「主演」都被当成同一种「相邻」这不符合电影推荐的直觉第二GCN 不分关系类型、不分邻居重要程度导致高度活跃实体比如参演过几百部电影的老戏骨会稀释掉聚合特征。解决前者用 R-GCN 或 KGCN解决后者用注意力机制。3.2 为什么推荐更常用 KGCN关系感知的邻域聚合KGCN 是为「知识图谱推荐」设计的模型它给每种关系分配一个独立的线性变换矩阵并在聚合时引入注意力权重注意力权重 softmax(邻居节点向量 v_i 与目标节点向量 u 的内积)。通俗讲就是模型自己去学「哪些邻居对当前用户更重要」——用户喜欢科幻片那么《星际穿越》的「类型 科幻」这条邻居的注意力权重会被拉高用户是诺兰粉那「导演 诺兰」这条边的权重也会上涨。注意力公式可以写成score σ(u^T · W_r · v_i)其中W_r是关系 r 的变换矩阵σ是激活函数。这个设计比普通 GCN 多做了一步「用户感知」——同一个邻居节点在给不同用户做推荐时聚合权重是不同的。这是 KGCN 能超过 GCN 基线的主要来源。3.3 从零实现 KGCN 聚合层与用户评分预测KGCN 的代码实现并不复杂,核心是采样邻居 加权聚合 输出预测分数。以下给出聚合层和预测层的核心实现# kgcn_model.py import torch import torch.nn as nn import torch.nn.functional as F class KGCNLayer(nn.Module): def __init__(self, in_dim, out_dim, n_relations): super().__init__() # 每种关系一个变换矩阵 self.relation_w nn.Parameter( torch.randn(n_relations, in_dim, out_dim) * 0.1 ) self.self_transform nn.Linear(in_dim, out_dim) def forward(self, entity_emb, neighbor_emb, relation_ids): # entity_emb: 中心节点向量 [batch, in_dim] # neighbor_emb: 采样邻居向量 [batch, n_neighbor, in_dim] # relation_ids: 每条边对应的关系ID [batch, n_neighbor] batch_size, n_neighbor, _ neighbor_emb.shape # 根据关系ID取出对应的变换矩阵 rel_w self.relation_w[relation_ids] # [batch, n_neighbor, in_dim, out_dim] # 邻居向量经过关系变换: [batch, n_neighbor, out_dim] transformed torch.einsum(bni,bnij-bnj, neighbor_emb, rel_w) # 注意力分数用中心节点与变换后邻居向量做内积 attn torch.sum(entity_emb.unsqueeze(1) * transformed, dim-1) attn torch.softmax(attn, dim-1) # [batch, n_neighbor] # 加权聚合邻居 agg torch.sum(attn.unsqueeze(-1) * transformed, dim1) # 残差连接回自身 out F.relu(self.self_transform(entity_emb) agg) return out class KGCN(nn.Module): def __init__(self, n_entities, n_relations, embed_dim, n_layers): super().__init__() self.entity_emb nn.Embedding(n_entities, embed_dim) self.layers nn.ModuleList([ KGCNLayer(embed_dim, embed_dim, n_relations) for _ in range(n_layers) ]) def forward(self, user_emb, movie_emb, neighbor_embs, relation_ids): # 逐层更新电影节点表示 x movie_emb for layer, neigh, rel in zip(self.layers, neighbor_embs, relation_ids): x layer(x, neigh, rel) # 预测分数用户向量与更新后电影向量内积 score torch.sum(user_emb * x, dim-1) return torch.sigmoid(score)逻辑说明neighbor_embs是在每个训练步从邻接矩阵里实时采样的固定数量邻居向量采样数量是超参数n_neighbor常见设为 816。torch.einsum在这里做的是一次小批量内所有邻居的关系变换比循环快很多。注意力内积把中心节点和邻居变换后的向量做相似度打分softmax 后再加权求和。残差连接让模型更深时也不容易梯度消失。参数说明嵌入维度embed_dim推荐 3264 之间维度太高在 1M 数据下容易过拟合n_layers不要超过 3最好直接设为 2。原因在于电影图谱的平均最短路径很短——「诺兰 → 蝙蝠侠 → 科幻类型 → 其他科幻片」只需要两跳就能覆盖大量候选电影。层数再多所有节点向量趋于同质化推荐精度不升反降这是图神经网络里常见的「过平滑」现象。3.4 训练策略BPR 损失与负采样KGCN 的监督信号来自用户的历史行为但评分是一个隐式反馈问题。把「看过并打了 4 分以上」视为正样本用贝叶斯个性化排序 BPR 损失来拉大正样本和负样本的得分差# train.py 核心训练循环片段 def bpr_loss(pos_scores, neg_scores): # 目标是让正样本得分明显高于负样本 return -torch.log(torch.sigmoid(pos_scores - neg_scores)).mean() for epoch in range(n_epochs): for batch in train_loader: # 每个正样本配 5 个随机负样本 pos_scores model(user_emb, pos_movie_emb, pos_neigh, pos_rel) neg_scores model(user_emb, neg_movie_emb, neg_neigh, neg_rel) loss bpr_loss(pos_scores, neg_scores) optimizer.zero_grad() loss.backward() optimizer.step()逻辑说明BPR 不要求预测分数接近真实评分只要求正样本大于负样本。这比 MSE 回归更合理因为用户打 4 分还是 5 分的主观差异很大模型没必要纠结这个数字。每个正样本配 5 个负样本是常用的策略太少则负样本区分度不够太多则训练时间呈线性上升收益递减。参数说明学习率建议从0.001起步使用 Adam 优化器权重衰减设1e-5。batch size 在 1024 到 4096 之间——KGCN 的邻居聚合操作对显存不敏感batch 大一点反而能让 GPU 的矩阵运算更饱满。关键超参数还有一个l2_reg如果发现训练集 loss 持续下降而验证集 Recall5 不涨先把正则系数往上调。4. 把模型组装成系统Flask 服务、推荐接口与前端联动4.1 项目目录结构与源码模块划分拿到完整源码包后先别急着跑把目录结构看一眼。一个能交付的系统至少应该是 Datasets / Models / Services / Controllers / Static 五个模块分离的而不是一个main.py里堆一千行。movie_kg_recsys/ ├── datasets/ │ ├── ml-1m/ # 原始 MovieLens 数据 │ └── preprocess.py # 数据清洗与三元组构建脚本 ├── models/ │ ├── kgcn.py # 图神经网络模型定义 │ ├── train.py # 训练与模型保存 │ └── recommend.py # 加载模型、生成召回结果 ├── services/ │ ├── graph_storage.py # 用 NetworkX SQLite 管理图谱 │ └── recommender.py # 推荐服务封装 ├── controllers/ │ └── api.py # Flask 蓝本RESTful 接口 ├── static/ │ ├── index.html # 页面入口 │ └── app.js # 前端请求与渲染逻辑 ├── weights/ │ └── kgcn_epoch20.pth # 训练好的模型权重 └── requirements.txt这个结构的好处是训练代码和部署代码隔离模型换版本时只需要替换weights/目录下的权重文件API 层不用动。requirements.txt里锁定torch2.0、flask2.3、pandas1.5、networkx3.1这些版本避免部署时因 numpy 版本冲突报np.bool不存在这类低级错误。4.2 提供 RESTful 推荐接口接收用户 ID返回电影列表模型训练完成后推荐服务的工作分两步先从训练好的 KGCN 里取用户 Embedding 和电影 Embedding然后对全量电影做打分排序。打分可以在内存里用矩阵乘法一次算完不需要每次请求都重新跑 GNN。# services/recommender.py import torch from models.kgcn import KGCN class MovieRecommender: def __init__(self, model_path, entity_emb_path, movie_id_map): self.device torch.device(cuda if torch.cuda.is_available() else cpu) self.model KGCN( n_entities100000, n_relations8, embed_dim64, n_layers2 ) self.model.load_state_dict(torch.load(model_path, map_locationself.device)) self.model.eval() # 预先抽好所有电影向量避免重复计算 self.user_emb torch.load(entity_emb_path, map_locationself.device) self.movie_id_map movie_id_map # {imdb_id: 内部实体ID} def recommend(self, user_id, top_k20): # 从 user_emb 里取该用户向量 user_vec self.user_emb[user_id].unsqueeze(0) # [1, dim] # 所有电影向量与用户向量的内积 推荐分 scores torch.mm(user_vec, self.model.entity_emb.weight.T) scores scores.squeeze(0) # 过滤掉用户已经看过的电影可选但强烈建议 top_k_ids torch.topk(scores, top_k).indices.tolist() return [self.movie_id_map[i] for i in top_k_ids]逻辑说明推荐阶段的关键优化是把模型切到eval()模式并且只保留最终的实体嵌入矩阵参与矩阵乘法。torch.mm一次能算出用户对所有电影的打分这在 1 万部电影规模的本地机器上只要几十毫秒。如果用户数量级很大可以提前把用户向量矩阵整体保存请求时做user_emb[user_id]索引内存和速度都会好。参数说明top_k在线上环境设 2050 即可如果接入前端页面轮播图一次返回 20 部足够。过滤已看电影这个逻辑最好写在推荐函数内部而不是前端过滤否则前端拿到列表可能不够 20 个页面就会缺位。4.3 前端页面联动搜索框、电影卡片与「推荐理由」展示前端页面用原生 HTML jQuery 是最省事的方案不需要构建工具链。第一步把训练好的模型权重加载到 Flask 服务里第二步在静态文件里用fetch调用推荐接口第三步把电影信息和推荐路径渲染到卡片上。推荐理由的展示是整套系统的差异点后端在图谱里保存了路径信息比如用户A → 喜欢《盗梦空间》 → 导演诺兰 → 执导《星际穿越》。推荐时把这条路径作为文本放在电影卡片的下方用户能一眼看懂推荐逻辑。这一步的实现方式是召回阶段不仅保留电影 ID还同时从graph_storage里查询「电影 → 关系 → 电影」的连接路径把路径的最后一个实体转成自然语言字符串。前端调用接口的代码简版如下// static/app.js async function loadRecommendations(userId, topK) { const resp await fetch(/api/recommend?user_id${userId}top_k${topK}); const data await resp.json(); const container document.getElementById(movie-grid); container.innerHTML ; data.movies.forEach(item { const card document.createElement(div); card.className movie-card; card.innerHTML h3${item.title}/h3 p${item.genres}/p p classreason推荐理由: ${item.reason_path}/p span classscore${item.pred_score.toFixed(2)}/span ; container.appendChild(card); }); }逻辑说明推荐理由路径item.reason_path是推荐系统可解释性的直接体现也方便在答辩或演示时快速说明模型内部行为。前端fetch 到 JSON后直接渲染卡片不需要刷新页面。用 jQuery 也行但原生 fetch 能少引一个依赖。5. 实战避坑清单图数据、训练和部署中最常见的 5 个翻车点5.1 现象训练到第 3 个 epoch loss 变成 NaN通常原因有两个方向。第一邻接矩阵里有自环或者重复边导致归一化权重分母出现零第二学习率太大关系变换矩阵relation_w初始化不当导致梯度爆炸。解决方法是构建矩阵时显式去掉对角线元素relation_w初始化标准差从 0.1 调到 0.01学习率降到5e-4再试。如果 loss 仍然不稳定检查是否有实体 ID 映射越界——训练集和验证集用了两套映射字典时越界会让 Embedding 查到随机初始化的向量表现就是 loss 异常跳动。5.2 现象MemoryErrorPython 进程直接被杀掉MovieLens 1M 本身很小但如果你导入ratings.dat时用了sep::却忘记指定enginepythonpandas 会在 C 引擎下把整个文件当一列读入内存直接爆掉。另一个常见元凶是构建稠密邻接矩阵时用了np.zeros((n_entities, n_entities))20000 实体 × 20000 × 8 字节就是 3.2GB。解决方法是全部改用scipy.sparse并通过train_test_split把数据切小对测试环境只载入训练子图。5.3 现象模型训练完推荐结果全是热门电影这是隐式反馈训练中典型的流行度偏差。原因在于越流行的电影在训练集里被点击的次数越多BPR loss 在优化时会把「模型倾向」往高频样本上带。解决方式分两步负采样时按流行度降采样热门电影作为负样本的概率调低评估指标不用整体的 Recall而是看Recall5在长尾电影切片上的表现。如果长尾召回率低于整体均值 30% 以上说明模型没有学到内容语义只是在背热度。5.4 现象Flask 接口响应慢每次请求都要等 3 秒最常见的原因是把「加载模型参数 构建用户向量」写进了每个请求的处理函数里。torch.load一次就有几百毫秒加上从磁盘读 Embedding攒到几秒很正常。解决方法是Flask 应用启动时用全局变量缓存模型对象只在__init__阶段载入一次接口内部只做向量索引和矩阵乘法。更稳妥的做法是用gunicorn跑多 worker 时把模型放到共享内存或者每个 worker 启动时加载并常驻。5.5 现象换一台机器跑不起来torch和numpy版本冲突把本地环境的requirements.txt直接pip install -r在干净服务器上往往报各种 C 扩展错误。原因多数是本地装了 GPU 版 torch服务端没有 NVIDIA 驱动pip 解析到不匹配的 CUDA 版本。解决办法是部署机上先执行python -c import torch; print(torch.__version__)确认能正常导入然后按部署机是否支持 CUDA 来决定安装 CPU 版还是 GPU 版模型代码里已经做了torch.device(cuda if torch.cuda.is_available() else cpu)逻辑会自动降级。6. 部署到 Ubuntu 服务器用 Gunicorn 托管 Flask并用 Docker 固定环境6.1 为什么选 Ubuntu 作为部署目标标题里提到的部署指南最常见的目标环境是 Ubuntu 20.04 或 22.04 云服务器。相比于 WindowsLinux 下的 Python 包编译链更干净内存管理更稳而且用systemd守护 Flask 进程后可以做到崩溃自动重启。Ubuntu 的安装路径上没有奇怪的中文用户目录torch模型路径不会出现编码问题。如果你的开发机是 Windows建议把训练好的.pth权重文件通过scp上传到服务器部署环节不要在 Windows 上跑。6.2 安装依赖与启动 Gunicorn 多进程部署过程分三步创建虚拟环境、安装依赖、用 Gunicorn 启动。下面是一套可直接照抄的部署命令# deploy.sh 部署脚本片段 sudo apt update sudo apt install -y python3.10-venv nginx # 1. 虚拟环境与依赖 python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 2. 确认 torch 能正常导入重要先跑这一句 python -c import torch; print(torch.__version__) # 3. 启动服务4 个 worker每个 worker 常驻模型 gunicorn -w 4 -b 127.0.0.1:8000 \ --timeout 120 \ --preload \ wsgi:app逻辑说明--preload让 master 进程先加载模型再 fork 出 4 个 worker这样每个 worker 共享内存里的模型参数避免每个 worker 重复torch.load导致内存翻四倍。--timeout 120是因为冷启动加载模型可能需要几秒默认 30 秒超时会导致 worker 被杀。-b 127.0.0.1:8000绑定内网地址外部请求由 Nginx 转发这样更安全也方便加 HTTPS。参数说明worker 数量不是越多越好推荐2 × CPU核数 1。4 核服务器开 4 个 worker 即可如果每个请求的矩阵乘法压力大实际验证下 CPU 占用率和接口延迟把 worker 数压到 2 反而更稳定。6.3 Nginx 反向代理与域名访问Gunicorn 监听内网端口后用 Nginx 做反向代理把公网流量转到127.0.0.1:8000。Nginx 还能顺带缓存静态资源——前端页面和 JS 文件不必经过 Flask直接由 Nginx 返回。server { listen 80; server_name your_domain.com; # 前端静态文件 location /static/ { alias /home/ubuntu/movie_kg_recsys/static/; expires 7d; } # API 反向代理 location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_read_timeout 120s; } }重启 Nginx 后访问http://your_domain.com就能直接看到前端页面调用/api/recommend接口时请求会被 Nginx 转发给 Gunicorn。proxy_read_timeout 120s很关键如果不加遇到首次请求模型初始化导致的 23 秒延迟时Nginx 会返回 504 网关超时。6.4 用 Docker 固定环境避免反复踩依赖坑如果你嫌多台服务器手动配环境太累最省心的方式是打包成 Docker 镜像。镜像内部固定 Python 3.10 依赖版本宿主机只需要有 NVIDIA 驱动GPU 场景即可。Dockerfile 的关键点FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [gunicorn, -w, 2, -b, 0.0.0.0:8000, --preload, wsgi:app]逻辑说明基础镜像用python:3.10-slim而不是ubuntu镜像体积更小、包管理一致性更好。COPY . .会把整个工程拷进镜像weights/目录里的模型权重也在其中所以--preload在这里不仅省内存还缩短了镜像启动时间。部署完以后做一次端到端验证先curl http://127.0.0.1:8000/api/recommend?user_id1top_k10看 JSON 是否返回再打开前端页面确认电影卡片能正常渲染。如果推荐结果和本地开发机不一致先怀疑数据处理阶段是否有随机种子——训练前给torch.manual_seed(42)和np.random.seed(42)打上这样任何机器上复现结果都是相同的排查问题会快很多。我在实战中养成的习惯是每次改完模型配置先把验证集上 Recall5 的数字记录在代码注释里再上服务器。因为部署环境跑一遍训练很耗时有基线数字打底才能在调参时判断「效果变好了还是玄学波动」。希望帮到你。本文还有配套的精品资源点击获取