企业官网建设流程全解析

简介：一套融合知识图谱与图神经网络的电影推荐系统完整源码，以知识图谱补充物品关联信息，借助图神经网络建模用户与物品交互，展示了推荐算法的完整工程化路径。该实现作为高分毕业设计成果，代码结构清晰、注释详尽，适合毕业设计、课程综合实践及Python推荐系统学习者参考，也可作为课程设计选题蓝本。资源包共含37个文件，压缩后约14.88MB，其中21个Python脚本覆盖数据预处理、知识图谱构建、KGCN模型层、训练评估与Web交互界面等模块，5个dat文件提供常用实验数据集，另有readme与markdown文档说明部署流程。系统功能模块齐全、界面直观、已通过充分测试，可直接运行，读者可从中掌握从原始数据到模型训练、评估与上线的全流程思路，并学习知识图谱与图神经网络在推荐任务中的配合方式，理解模型调参与性能优化等关键技术。目前已有49人学习下载，具备较高参考价值。

1. 电影推荐系统里，知识图谱和图神经网络到底补了谁的空位

第一次接手电影推荐项目时，我下意识想的也是用户协同过滤：把用户对电影的评分矩阵铺开，找相似用户、算相似电影，逻辑很顺。可等真正上线做评估就发现，新注册用户没有任何行为记录，协同过滤直接失灵；冷门电影又因为交互太少，永远沉在召回名单底部。这个场景里，单纯堆模型已经解决不了问题，必须引入图谱层面的先验信息。

基于 Python 的知识图谱与图神经网络电影推荐系统实现（含完整源码与部署指南），解决的就是这个“行为稀疏”的缺口。它先把电影、演员、导演、类型、用户这些实体以及它们之间的关系写进知识图谱，再将图谱作为图神经网络的输入，让推荐模型在训练时能看到“谁演了哪部片、谁导过什么类型、用户偏好哪种题材”这些语义关联，而不是只看见一张稀疏的评分表。对新手来说，它是一条能在一台开发机上完整跑通的推荐系统落地路径；对已经在做推荐系统的人而言，它提供的是从知识图谱构建到模型部署的全套工程骨架。

2. 知识图谱构建：从本体设计到 Neo4j 的批量装载链路

这部分是整个项目的地基。很多教程把 Neo4j 当数据库用，上来就写 Cypher 灌数据，这其实绕过了最关键的一步：本体建模。本体和语义层没定清楚，后面图神经网络学出来的 Embedding 就是一团噪声。我一般会先花半天把实体、关系、属性画在纸上，再动代码。

2.1 先定本体与语义层，再谈 Neo4j 装载

工业场景下的知识图谱设计，第一步不是建数据库，而是把图谱的语义边界说清楚。我们要解决的是电影推荐，核心实体就是用户和电影，围绕它们展开的辅助实体包括导演、演员、电影类型这四类。

对电影推荐来说，本体通常是这样的结构：

实体表

关系表

这份设计里没有把“评分”做进图谱。原因是我希望图谱保留的是相对稳定的语义信息，而评分属于行为信息，行为信息后续会用于负采样和训练集划分，混在图谱里会让数据泄漏问题变难排查。后面真正训练图神经网络时，再通过“用户-电影”的 LIKE 边把用户节点和图谱里的电影属性连接起来。

属性图模型的好处是，关系可以带方向，一条边就是一个语义事实，Cypher 查询可以直接沿着边做路径分析。这个阶段我最重视的是唯一键设计，缺失唯一键先别急着写装载脚本，否则后面去重会非常痛苦。

2.2 用 py2neo 批量写入 Movie 节点：事务粒度决定装载速度

数据源准备好之后，一般用 py2neo 连接 Neo4j。这里提醒一点，py2neo 对 Neo4j 服务端版本比较敏感，先在虚拟环境里装好依赖，确认能连上 7687 端口再开始灌数据。

装载脚本的常见做法是显式开启事务，并按批次提交。千万不能一条数据一个事务，否则几十万条数据写几个小时都写不完。

# kg/load_movies.py from py2neo import Graph, Node graph = Graph("bolt://localhost:7687", auth=("neo4j", "your_password")) # 建唯一约束，不然后续 merge 会产生重复节点 graph.run("CREATE CONSTRAINT movie_uniq IF NOT EXISTS " "FOR (m:Movie) REQUIRE m.id IS UNIQUE") graph.run("CREATE CONSTRAINT director_uniq IF NOT EXISTS " "FOR (d:Director) REQUIRE d.name IS UNIQUE") graph.run("CREATE CONSTRAINT actor_uniq IF NOT EXISTS " "FOR (a:Actor) REQUIRE a.id IS UNIQUE") def load_movie_nodes(rows, batch_size=2000): tx = graph.begin() for i, row in enumerate(rows): node = Node("Movie", id=int(row["movie_id"]), title=row["title"], release_year=int(row["year"])) tx.merge(node, "Movie", "id") if i % batch_size == 0 and i > 0: tx.commit() tx = graph.begin() tx.commit()

这段代码里有两个参数值得细说。batch_size 控制在 2000 到 5000 比较合适，太小事务次数多，太大事务占用的堆内存会撑爆 Neo4j。merge函数只传了一个唯一键 "id"，意思是按 Movie 节点的 id 属性决定是否重复，这是保证不产生重复节点的关键。

有人会问为什么不用create而用merge，在 Loading 阶段可以直接 create，因为数据源是干净的。但我建议保留 merge，原因很简单，后面反复重跑装载脚本时，merge 天然具备幂等性。

2.3 装载关系：先建好两端节点，再批量 merge 边

节点装载完成后，再装载关系。关系的装载要用到两端节点，这里最容易翻车的是“边先于节点存在”的写法。加载关系前，必须确保 Movie、Director、Actor、Genre 节点都已经入库。

我习惯先把有关系的实体从 CSV 里读出来，对每条关系先查两端节点，再 merge 关系。查询端点这件事如果逐条用 Cypher 做，速度会很慢，但我这里为了可读性先写成逐条查询，生产环境可以改成批量传入 id 列表。

# kg/load_relations.py from py2neo import Graph, Relationship graph = Graph("bolt://localhost:7687", auth=("neo4j", "your_password")) def link_movie_to_director(movie_id, director_name, batch_size=2000): tx = graph.begin() for i, (mid, dname) in enumerate(zip(movie_id, director_name)): movie = tx.run( "MATCH (m:Movie {id:$id}) RETURN m", id=mid).evaluate() director = tx.run( "MATCH (d:Director {name:$name}) RETURN d", name=dname).evaluate() if movie and director: tx.merge(Relationship(movie, "DIRECTED_BY", director)) if i % batch_size == 0 and i > 0: tx.commit() tx = graph.begin() tx.commit()

这里注意tx.run返回的是游标，evaluate()会取第一列第一个值。查询尽量用参数化写法$id、$name，不要拼字符串，否则特殊字符会把 Cypher 弄坏。如果发现某条关系两端有一个端点查不到，print 出来看一眼，一般是数据源里导演姓名字段和导演表对不上，这类脏数据要在清洗阶段处理，而不是在图谱层做兼容。

2.4 用 Cypher 快速校验图谱装载质量

关系装完，先跑几条查询验证图谱不是空架子。我通常在 Neo4j Browser 里执行下面几条，看返回结果是否合理：

MATCH (m:Movie)-[:DIRECTED_BY]->(d:Director) RETURN m.title, d.name LIMIT 5; MATCH (m:Movie) RETURN count(m) AS movie_count; MATCH (m:Movie)-[:HAS_GENRE]->(g:Genre) RETURN g.name, count(*) AS cnt ORDER BY cnt DESC LIMIT 10;

第一条看最基本的边能不能查到；第二条确认节点总量；第三条看类型分布是否均衡。如果第三条查出来电影类型高度集中，说明类型映射脚本里 probably 把字段对应错了。

装图阶段的验收标准不是“数据都进去了”，而是：每个 Movie 节点至少有一条 HAS_GENRE 边，至少有一条 DIRECTED_BY 或 ACTED_BY 边。如果存在孤立电影节点，后面做图神经网络聚合时，这些节点就只能靠自身特征学习，邻居聚合效果会大打折扣。

2.5 数据清洗里的两个脏点：年份字段与同名导演

电影数据来自开放接口时，最常见的坑有两个。第一是 release_year 字段经常混入“暂无”、“未知”、“2009年”这类脏值，清洗脚本里要做正则提取数字。第二是同名导演，不同年代的两位“王晶”会被合并成同一个 Director 节点。遇到这种情况，我会在 Director 实体里加一个 birth_year 属性做区分，关系表里的导演字段也带上年份，避免语义层被同名实体污染。

3. 图神经网络选型与训练：GraphSAGE 模型在电影推荐里的落地

图谱装好了，下一步是把图结构喂给图神经网络。这里不选 GCN，选 GraphSAGE，原因后面详细讲。整个训练链路包括：把 Neo4j 数据导出成 PyTorch Geometric 需要的格式，定义模型，做负采样，训练并评估。

3.1 为什么选 GraphSAGE 而不是 GCN：冷启动能力是关键

图卷积网络 GCN 在做节点分类时很强，但它属于直推式学习，训练时必须知道全图结构，新节点进来后要重新训练才能拿 Embedding。GraphSAGE 的核心是归纳式学习，它学到的不是某个节点的固定表示，而是一组“邻居聚合函数”，训练完成后，新用户节点可以直接套用这套聚合逻辑得到表示。

这个差异对推荐系统是决定性的。推荐场景里每天都有新用户进图，你不能每次来一个用户就全图重训。GraphSAGE 用邻居采样加聚合的方式，支持把新节点拼接进图后直接推理，这是它更适合推荐系统的原因。具体对比看下表：

3.2 把图谱关系转成 PyTorch Geometric 的 edge_index

PyTorch Geometric 对同质图支持最方便。这里先把所有实体映射成同一组节点，节点类型差异通过特征拼接来体现。图结构用两个张量表示：edge_index 是 2 行 N 列的整数张量，第一行是边的起点，第二行是边的终点。

导出脚本的核心是维护一个全局 ID 映射表，把 Neo4j 里不同类型的节点统一映射到 0 到 N-1 的整数区间。

# model/build_graph.py import torch def build_graph(user_like, movie_genre, movie_director, movie_actor): # 全局节点 id 映射，key 是 (类型, 业务id) global_id = {} def gid(entity_type, entity_key): key = (entity_type, entity_key) if key not in global_id: global_id[key] = len(global_id) return global_id[key] edge_src, edge_dst = [], [] # 用户喜欢电影 for user_id, movie_id in user_like: edge_src.append(gid("User", user_id)) edge_dst.append(gid("Movie", movie_id)) # 电影归属类型 for movie_id, genre_name in movie_genre: edge_src.append(gid("Movie", movie_id)) edge_dst.append(gid("Genre", genre_name)) # 导演关系 for movie_id, director_name in movie_director: edge_src.append(gid("Movie", movie_id)) edge_dst.append(gid("Director", director_name)) # 演员关系 for movie_id, actor_id in movie_actor: edge_src.append(gid("Movie", movie_id)) edge_dst.append(gid("Actor", actor_id)) edge_index = torch.tensor([edge_src, edge_dst], dtype=torch.long) node_id_map = global_id return edge_index, node_id_map

这里有个细节要注意：edge_index 的语义要说明白。我代码里只写了单向边，但 PyG 模型内部通常要求无向图才能双向聚合，所以在训练脚本里记得做对称化处理，把 edge_index 转成双向：

edge_index = torch.cat([edge_index, edge_index.flip(0)], dim=1)

flip(0)是把矩阵沿第一维翻转，这样原来 u->m 的边会补上 m->u 的反向边。

3.3 节点特征矩阵的构造方式

图神经网络的输入除了结构，还要有节点特征。现实中很多项目把所有节点特征全部随机初始化，这其实是浪费了知识图谱的价值。常见做法是分类型拼接特征：

• User 节点：年龄归一化后的标量，性别 one-hot，职业 one-hot；
• Movie 节点：release_year 归一化后的标量，标题的词向量均值；
• Genre、Director、Actor 节点：由于没有额外属性，使用随机的可学习 Embedding。

代码骨架大概是这样：

def build_feature_matrix(node_id_map, num_nodes, feat_dim=128): x = torch.zeros(num_nodes, feat_dim) for (ent_type, ent_key), idx in node_id_map.items(): if ent_type == "User": x[idx] = torch.tensor(user_feature(ent_key), dtype=torch.float) elif ent_type == "Movie": x[idx] = torch.tensor(movie_feature(ent_key), dtype=torch.float) else: # 无法构造统计量时，用截断正态分布初始化 x[idx] = torch.randn(feat_dim) * 0.1 return x

为什么随机初始化不能全部设成 0？因为节点维度为 0 会导致 GraphSAGE 聚合时信息全部被平均掉，模型退化成只学全局均值，学不出节点差异。至于嵌入维度，默认 128 训练成本较低，没必要一上来就挑战知识图谱 1024 维那种大维度方案，先在小维度把流程跑通。

3.4 用 SAGEConv 搭建两层聚合模型

模型结构可以压到很简：两层 SAGEConv，中间加一个 Dropout。SAGEConv 的 forward 行为是：对每个节点，采样邻居并做聚合，把聚合结果和目标节点自身的特征拼接，再过一层线性层。

# model/sage_rec.py import torch import torch.nn.functional as F from torch_geometric.nn import SAGEConv class SageMovieRec(torch.nn.Module): def __init__(self, in_dim, hidden_dim, out_dim=128): super().__init__() self.conv1 = SAGEConv(in_dim, hidden_dim, aggr="mean") self.conv2 = SAGEConv(hidden_dim, out_dim, aggr="mean") self.dropout = torch.nn.Dropout(0.2) def forward(self, x, edge_index): x = self.conv1(x, edge_index) x = F.relu(x) x = self.dropout(x) x = self.conv2(x, edge_index) return x

aggr="mean"是聚合方式里最稳的。mean 聚合不容易受单个极端邻居影响，推荐场景下邻居的度分布差异很大，max 聚合可能被热门电影的主导邻居覆盖，sum 聚合可能给高度节点过大能量。第一层面向原始特征，第二层把聚合特征继续扩散。两层叠加后，每个节点理论上能感知两跳以内的语义信息，比如“我和某电影直接相关，该电影的类型、导演也间接参与了我的表示”。

3.5 训练循环：负采样与损失函数

训练的核心是给每个正样本配一批负样本。正样本是用户有过正向行为的电影，负样本从该用户没有行为记录的集合里随机抽取。负采样比例一般 1 比 4 到 1 比 8，我常用 1:4。

def train_epoch(model, data, pos_pairs, neg_pairs, optimizer): model.train() emb = model(data.x, data.edge_index) pos_user = torch.tensor([u for u, _ in pos_pairs]) pos_item = torch.tensor([i for _, i in pos_pairs]) pos_score = (emb[pos_user] * emb[pos_item]).sum(dim=1) neg_user = torch.tensor([u for u, _ in neg_pairs]) neg_item = torch.tensor([i for _, i in neg_pairs]) neg_score = (emb[neg_user] * emb[neg_item]).sum(dim=1) logits = torch.cat([pos_score, neg_score]) labels = torch.cat([torch.ones_like(pos_score), torch.zeros_like(neg_score)]) return torch.nn.functional.binary_cross_entropy_with_logits( logits, labels)

这里要解释一个重要的设计：为什么打分用内积而不是模型直接输出一个分数图。内积操作把用户和电影分别嵌入到同一个向量空间，得到的 Embedding 可以从模型中抽出，作为后续部署和召回的数据底座。直接用一个 MLP 打分，训练时更自由，但推理时拿不到能复用的 Embedding，对推荐服务来说不划算。

训练时还有一个重要习惯：固定随机种子，否则复现不了论文数字。PyTorch 要设置四个地方的种子：

import random import numpy as np random.seed(42) np.random.seed(42) torch.manual_seed(42) if torch.cuda.is_available(): torch.cuda.manual_seed_all(42)

这个步骤不算玄学，它是后续调参时判断“改动有效”的前提。种子不一致，模型每跑一遍都在变，你无法判断指标变好是参数起作用还是随机性波动。

4. 含源码与部署指南：FastAPI 服务、Docker 与图数据库的联排部署

训练完只是开始，真正让推荐系统跑起来，得把模型变成接口。这一章讲部署，按含完整源码与部署指南的思路，我会把目录结构、嵌入导出、API 封装、容器编排都过一遍。

4.1 源码目录结构：一开始就把边界划清楚

项目源码我习惯按四个模块划分：图谱构建、模型训练、API 服务、部署配置。这样拆的好处是，训练脚本和线上接口互不污染，后面换模型版本也不会动到图谱代码。

movie-rec-kg/ ├── data/ # 原始 csv 数据与清洗中间文件 ├── kg/ │ ├── load_movies.py # 电影节点装载 │ └── load_relations.py # 关系装载 ├── model/ │ ├── build_graph.py # 图谱转 PyG 数据 │ ├── sage_rec.py # 模型定义 │ └── train.py # 训练与评估 ├── api/ │ ├── main.py # FastAPI 服务 │ └── recommend.py # 推荐逻辑 ├── deploy/ │ ├── docker-compose.yml # 一键拉起环境 │ └── Dockerfile ├── requirements.txt └── README.md

requirements.txt 里要锁住 torch、torch_geometric、py2neo、neo4j-driver、fastapi、uvicorn 的版本区间。如果你是从 python 入门教程一路看完再动手的，建议先建一个干净的环境，装好 py2neo 和 pytorch 再往后走，不要一次全装。Windows 用户在配置 vscode python 环境时，注意 torch_geometric 的轮子依赖，装不上时手动下载对应的 whl 文件，这种细节能在部署阶段省大量折腾时间。

4.2 训练后的嵌入导出：部署时不要实时跑模型

部署阶段最大的坑是每个请求都跑一次全图推理。全图节点可能几十万个，一次 forward 要几十秒，API 完全不可用。我的常见做法是，训练结束后用模型对全图做一次推理，把每个节点的 Embedding 固化到磁盘，API 启动时直接加载。

# model/export_embeddings.py import torch @torch.no_grad() def dump_embeddings(model, data, id_map, save_path="outputs/embeddings.pt"): model.eval() all_emb = model(data.x, data.edge_index).cpu() torch.save({ "id_map": id_map, # 将 (实体类型, 业务id) 映射到节点下标 "embeddings": all_emb }, save_path) print(f"embeddings saved to {save_path}, shape={all_emb.shape}")

导出文件里同时保存 id_map，这样 API 侧不需要再连 Neo4j 就能把业务 ID 转成嵌入下标。

4.3 FastAPI 封装推荐接口

推荐接口的核心逻辑是：拿到用户 ID，查出它的嵌入向量，然后与所有电影嵌入做内积，返回得分最高的 Top-K 电影。整个计算在内存矩阵里完成，速度非常快。

# api/main.py from fastapi import FastAPI from pydantic import BaseModel import torch app = FastAPI() model_data = torch.load("outputs/embeddings.pt") id_map = model_data["id_map"] embeddings = model_data["embeddings"] item_ids = [eid for (etype, eid) in id_map.keys() if etype == "Movie"] item_indices = [idx for (etype, _), idx in id_map.items() if etype == "Movie"] item_emb = embeddings[item_indices] class RecommendRequest(BaseModel): user_id: int top_k: int = 10 @app.post("/api/v1/recommend") def recommend(req: RecommendRequest): user_idx = id_map.get("User", req.user_id) if user_idx is None: return {"items": fallback_hot_movies(req.top_k)} user_emb = embeddings[user_idx] scores = (item_emb * user_emb.unsqueeze(0)).sum(dim=1) top_indices = scores.topk(req.top_k).indices.tolist() return {"items": [item_ids[i] for i in top_indices]}

注意user_idx is None的分支，这就是冷启动兜底：图谱里没有的新用户，返回热门电影。这块逻辑不能省，新用户必然存在，没有兜底策略接口会直接报错。fallback_hot_movies可以查 Neo4j，也可以直接用训练集里出现频次最高的电影。

4.4 Docker Compose 同时拉起图数据库和 API

部署线上环境时，把 Neo4j 和 API 放同一个 compose 网络里最省心。这样 API 可以不依赖外网访问图数据库，直接走容器网络。

# deploy/docker-compose.yml version: "3" services: neo4j: image: neo4j:5 environment: - NEO4J_AUTH=neo4j/change_me - NEO4J_server_memory_heap_max__size=2G - NEO4J_server_memory_pagecache_size=1G ports: - "7474:7474" - "7687:7687" volumes: - neo4j_data:/data api: build: ./api environment: - EMBEDDING_PATH=/app/outputs/embeddings.pt ports: - "8000:8000" depends_on: - neo4j volumes: neo4j_data:

API 容器需要在 Dockerfile 里先COPY outputs/embeddings.pt，再把uvicorn main:app --host 0.0.0.0 --port 8000作为启动命令。容器内存要留够，PyTorch 模型加载嵌入矩阵时占用不小，默认 512M 很容易 OOM，我一般会设置 mem_limit 到 2G。

4.5 图谱可视化与管理端扩展

如果团队内部需要看图谱效果，不用自己写可视化组件，直接找现成的知识图谱前端插件接入 Neo4j 的数据接口，浏览器里展示实体关系图。这样做既不用维护复杂的图绘制逻辑，又能在演示时快速让别人理解系统结构。推荐服务本身不依赖可视化组件，它是独立的模块，这部分只服务于运营排查。

5. 避坑手记：装图、训练与部署阶段的 5 处典型翻车排查

前面几章把正向流程讲完整了，但真正动手时，80% 的时间会耗在问题排查上。这一章直接写我踩过的坑，每条按现象、原因、解决三步记录，希望能给你省点找 Bug 的时间。

5.1 Neo4j 大量写入时堆内存溢出

现象：向 Neo4j 装载几十万条关系时，控制台报OutOfMemoryError，容器直接重启或者进程卡死。

原因：Neo4j 服务端默认堆内存只有几百 MB，大批量事务写入时，事务状态和节点缓存在堆里爆炸。同时装载脚本里如果每条数据手动提交一次，每个事务都要在堆上重建状态，内存压力更大。

解决：两件事一起做。第一，调整 Docker 环境变量，把 Neo4j 堆内存和页缓存分开设：

environment: - NEO4J_server_memory_heap_max__size=2G - NEO4J_server_memory_pagecache_size=1G

注意环境变量里的双下划线，heap_max__size对应配置项server.memory.heap.max.size，这是 Neo4j 4.4 之后的配置格式。第二，装载脚本一定要按批提交，单批 1000 到 5000 条，每批提交一次事务。这两个动作做完，装载吞吐量能从每秒几百条提升到几千条。

5.2 MERGE 产生重复节点，图谱里出现两个相同导演

现象：图数据库中查询某个导演，返回两条同名节点，两边的电影也分成两堆。

原因：merge 的唯一匹配属性没设置对。py2neo 的merge(node, "Director", "name")要求 Director 节点必须有 name 属性的唯一索引，如果缺索引，merge 退化成 create，每次写入都生成新节点。

解决：装载前先给唯一键建约束，上面的代码里已经写了这步。已经产生重复节点的库不要手工逐条删，推荐用 Cypher 聚合后重建：

MATCH (d:Director) WITH d.name AS name, collect(d) AS nodes WHERE size(nodes) > 1 FOREACH (x IN tail(nodes) | DETACH DELETE x);

执行前先确认被删除节点上没有必须保留的关系。

5.3 GNN 训练时 Loss 震荡不下降

现象：训练前几个 epoch 的 loss 在 0.7 到 0.8 之间反复横跳，没有明显下降趋势，有时一个 epoch 涨一点，下个 epoch 又跌回来。

原因：最常见的是学习率过大，模型参数在最优点附近震荡；其次是负采样没有固定种子，每个 epoch 的负样本集合完全随机，损失本身波动大；还有一类原因是没有做 Embedding 初始化，随机初始化方差太大会让邻域聚合结果不稳定。

解决：先调学习率。我通常从 1e-3 降到 3e-4 试一轮。同时在模型里加梯度裁剪，防止单个 batch 的极端负样本把参数冲偏：

optimizer.zero_grad() loss.backward() torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=5.0) optimizer.step()

加上种子固定后，loss 曲线仍不降，再检查数据加载顺序是否打乱了。数据按时间排序时，模型容易学到时间维度上的偏置，一个 epoch 内先看到老用户后看到新用户，训练不稳定。

5.4 训练指标很高，线上推荐效果却明显受损：数据泄漏

现象：离线评估 AUC 和 Recall 都很好，到线上做小流量验证时点击率反而不如热门推荐。

原因：数据泄漏。最常见的是负采样没有按用户划分：用户 A 的负样本电影可能出现在用户 B 的验证集里。更隐蔽的一种是，训练图里包含了验证用户的边，模型在训练时见过要预测的那条边，评估当然虚高。

解决：切分数据时，先把用户按 ID 划分成训练用户和验证用户，再分别取他们的行为边构造训练图和验证图。验证用户的边完全不进入训练图。这个思路也叫按用户切分，而不是按时间切分。推荐场景里，按用户切分更贴近冷启动诉求。

5.5 Docker 容器内模型加载失败：torch 与 torch_geometric 版本不匹配

现象：本地跑得好好的，一进 Docker 容器，import torch_geometric就报 undefined symbol 或者缺少某个依赖，服务半天起不来。

原因：本地开发环境是 Python 3.10，容器里却用 3.8 的基础镜像，torch_geometric 编译的轮子对 PyTorch 版本非常敏感，一个不对就炸。Docker 里 rebuild 缓存也会把旧版本依赖留在层里。

解决：requirements.txt 里对关键依赖做约束：

torch>=2.0,<2.3 torch-geometric>=2.4

Dockerfile 尽量直接基于python:3.11-slim，选择与本地解释器一致的基础镜像。构建时先升级 pip，再装 torch、torch-geometric，并把torch_geometric的版本输出到构建日志里，出问题能立刻看出差异。

6. 调参顺序与评估习惯：让这套系统跑出可对比数字

系统能跑了，怎么把效果做上去？我建议先立一个对比基准，再按固定顺序调参，最后用有限几组指标判断每次改动的好坏。

先跑一个最简单的热门榜作为基线，再跑协同过滤的 ItemCF，最后才跑知识图谱与图神经网络方案。这样做的好处是每个阶段都能回答“这笔投入值不值”。如果没有对比基线的数字，调参调得再精细，也无法向团队证明图谱和 GNN 带来的增量。

6.1 超参数调整顺序

我的调参习惯按这个顺序执行，每次只动一个变量：

先调学习率，因为它影响所有后续实验。学习率能找到有效区间，再动 Embedding 维度。维度从 64 开始，效果饱和后就别再往上加，不是维度越大越好，维度大到 1024 维之后训练时长翻倍，收益却微乎其微。负采样比例放在第三位，它对排序类指标的影响比维度更直接。最后才微调 Dropout 和训练轮数。

6.2 评估指标的计算

推荐系统主评估指标用 Recall@K 和 HitRate@K。HitRate 衡量用户真实看过的电影是否出现在 Top-K 里，Recall 则关注召回比。小样本点击行为下，HitRate 更稳定。

def hit_rate_at_k(pred_movie_ids, real_movie_ids, k=10): pred_set = set(pred_movie_ids[:k]) real_set = set(real_movie_ids) return 1.0 if pred_set & real_set else 0.0 def recall_at_k(pred_movie_ids, real_movie_ids, k=10): pred_set = set(pred_movie_ids[:k]) real_set = set(real_movie_ids) return len(pred_set & real_set) / max(len(real_set), 1)

计算多个用户后取均值，还要报告方差。只有均值没有方差，很难判断模型是整体变好还是个别用户拉高的。我的习惯是每次实验跑三遍随机种子，取中间值作为结果，避免单次随机波动被误判成模型收益。

6.3 一个值得养成的部署习惯

训练完成导出嵌入后，建议把嵌入文件打上版本号，比如embeddings_20241012.pt，并记录对应模型的超参数和评估指标。线上 API 可以同时加载两个版本嵌入做对比，方便随时回滚。这个习惯救过我一次：新模型离线表现更好，线上效果却下滑，最后查出是训练数据时间窗口写错，因为没有删除旧版嵌入，整个服务在五分钟内恢复到上一版，没有造成大面积影响。

这也是整个项目里最值得你重视的工程习惯：保留每个实验版本的可复现入口。模型结构、超参数、数据版本、嵌入文件，一条线串起来，任何“上一版效果更好”的反馈都能快速定位，而不是靠玄学猜。希望我的这些笔记能帮你绕过已经踩过的坑，顺利把这套知识图谱与图神经网络推荐系统跑起来。

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