手写GCN实战：从电商日志到可上线的图神经网络-编程实验室

简介：本资源是一份面向深度学习初学者与图神经网络实践者的完整GNN代码实现包，聚焦节点嵌入学习与边关系建模，适用于社交网络分析、推荐系统、分子性质预测等图结构数据任务。压缩包共323个文件，主体为322个JSON格式的图数据样本（含节点属性、邻接关系及边权重信息），辅以1个.DS_Store系统文件，整体仅2.17MB，轻量易部署，便于快速加载与调试。已有2678人下载学习，反映出其在入门级GNN工程实践中的高参考价值。资源涵盖GNN全流程：从图数据读取与预处理、多层消息传递机制实现（含邻居聚合与节点特征更新）、到嵌入向量生成与保存，代码结构清晰、模块解耦合理，无冗余依赖，可直接运行复现GCN类基础模型，是理解图卷积、掌握节点表征学习落地细节的优质实操材料。

1. 项目概述：这不是“又一个GNN教程”，而是一份能跑通、能调试、能改写、能上线的实战代码包

图神经网络（GNN）这个词，这两年在技术圈里已经从论文里的冷门术语，变成了工程师简历上高频出现的关键词。但现实很骨感：翻遍全网，90%的所谓“GNN代码”要么是PyTorch Geometric官网抄来的Toy Example——用Cora数据集跑个准确率82%，连节点特征维度都懒得注释；要么是Jupyter Notebook里堆满魔法命令和print语句的“演示脚本”，一迁移到真实业务数据就报错“RuntimeError: expected scalar type Float but found Double”，连张量类型都没对齐。我带过三届校企联合培养的学生，每次让他们基于GNN做推荐系统原型，80%的人卡在第一步：把公司内部的用户-商品交互日志构建成可用的图结构，而不是直接套用现成的cora/citeseer数据集。

这个标题叫“gnn图神经网络（代码完整）”，它不是教你怎么背公式，而是给你一套开箱即用、带完整工程骨架、覆盖典型场景、附带调试日志和错误定位指南的代码实现。它包含三个核心模块：一是基于PyTorch原生实现的GCN层（不依赖任何高级图库），逐行注释张量形状变换与消息传递逻辑；二是可插拔的数据预处理管道，支持CSV边表+节点属性表、邻接矩阵稀疏存储、异构图多类型节点自动编码；三是内置的模型验证闭环——从训练损失曲线、验证集F1-score热力图，到节点嵌入t-SNE可视化，再到单个节点预测结果的可解释性溯源（比如“为什么这个用户被推荐了这件商品？因为其邻居中3个高活跃度用户都点击过”）。它不讲“图卷积神经网络通俗理解”那种比喻式科普，而是直接告诉你：当你拿到一份含10万用户、50万商品、200万交互记录的MySQL表时，该执行哪7条SQL生成边列表，该用哪种归一化方式处理用户停留时长这类偏态特征，该在GCN层后加Dropout还是BatchNorm——这些细节，才是决定你项目能否落地的关键。

适合谁？如果你正在做社交关系挖掘、金融风控中的团伙识别、电商推荐里的跨品类关联、工业设备故障传播路径分析，或者只是想真正搞懂GNN不是“黑盒”，而是可拆解、可干预、可监控的计算流程——这份代码就是为你准备的。它不要求你熟读Kipf那篇奠基论文，但要求你至少会用pandas读CSV、会看PyTorch报错信息、知道什么是CUDA device。接下来的内容，我会带你一层层剥开这个代码包的内核，告诉你每一行为什么这么写，以及当它不工作时，你该盯住哪几个变量。

2. 整体架构设计与方案选型：为什么放弃Geometric，坚持手写GCN层？

2.1 拒绝“黑盒依赖”：从Geometric到纯PyTorch的决策逻辑

市面上绝大多数GNN教程默认使用PyTorch Geometric（PyG），这确实省事——GCNConv(in_channels, out_channels)一行搞定。但我在给某银行做反洗钱图谱项目时踩过坑：他们的生产环境GPU驱动版本锁定在418.67，而PyG 2.3.0要求CUDA 11.3以上，强行降级PyG会导致torch_scatter编译失败，整个pipeline卡死两周。最后我们砍掉PyG，用原生PyTorch重写了GCN层，只用了不到200行代码，却获得了三个关键收益：第一，完全规避第三方C++扩展的兼容性问题；第二，所有张量操作可被torch.autograd.set_detect_anomaly(True)全程追踪，一旦梯度爆炸，能精准定位到A @ X @ W这一步的数值溢出；第三，便于插入业务逻辑——比如在消息聚合阶段，对金融交易边按金额加权，而不是简单平均。

所以本代码包的核心设计原则是：所有GNN层均基于torch.nn.Module手写，不引入任何图计算专用库。以最基础的GCN为例，它的数学表达是：

$$ H^{(l+1)} = \sigma(\hat{A} H^{(l)} W^{(l)}) $$

其中$\hat{A} = \tilde{D}^{-\frac{1}{2}} \tilde{A} \tilde{D}^{-\frac{1}{2}}$是归一化的邻接矩阵，$\tilde{A} = A + I$是自环增强的邻接矩阵，$\tilde{D}$是对角度矩阵。很多教程直接调用torch_sparse或torch_scatter做稀疏矩阵乘法，但实际业务中，你的图可能只有10万节点，邻接矩阵用torch.sparse_coo_tensor存储反而比稠密矩阵慢——因为GPU对稀疏张量的访存模式不友好。我们的方案是：小图（<5万节点）用稠密矩阵乘法，大图（>5万节点）用torch.spmm稀疏乘法，并提供自动切换开关。代码里你会看到这样的判断逻辑：

if self.use_sparse and adj_matrix.is_sparse: # 稠密X稀疏：先转置X再spmm，避免内存爆炸 out = torch.spmm(adj_matrix, x.t()).t() else: # 稠密X稠密：标准矩阵乘 out = torch.mm(adj_matrix, x)

这个细节决定了你的模型在2080Ti上训练10万节点图时，显存占用从12GB降到7GB，速度提升1.8倍。

2.2 数据流设计：为什么采用“图构建-特征工程-模型训练”三段式流水线？

GNN的失败，80%源于数据预处理。我见过太多团队把精力全花在调参上，却忽略了一个致命问题：输入图的质量，直接决定GNN的上限。比如电商场景，如果只用“用户-点击-商品”构建二部图，漏掉了“用户-搜索-关键词”、“商品-属于-品类”这些高阶关系，GNN学出来的嵌入必然割裂。因此，本代码包强制采用模块化数据流：

GraphBuilder模块：接收原始CSV（如user_id,item_id,click_time,click_duration），输出标准化图对象。它不假设数据格式——支持三种输入模式：① 边列表（edges.csv）+ 节点属性表（nodes.csv）；② 邻接矩阵NPY文件；③ Neo4j图数据库直连（通过py2neo）。关键创新在于“动态自环添加”：不是简单给每个节点加自环，而是根据业务语义——例如在风控图中，对“高风险用户”节点添加权重为2.0的自环，强化其自身特征传播。
FeatureProcessor模块：解决GNN最头疼的异构特征融合。比如用户节点有年龄（数值）、地域（类别）、最近3次购买金额（时序）；商品节点有价格（数值）、类目（树状层级）、评论情感分（文本embedding）。本模块提供：① 数值特征分位数归一化（避免极值干扰）；② 类别特征用Target Encoding替代One-Hot（防止高基数特征维度爆炸）；③ 时序特征用滑动窗口LSTM压缩为固定长度向量。所有处理步骤可配置、可复现、可导出为ONNX。
Trainer模块：超越model.train()的简单封装。它内置“早停-学习率重置-梯度裁剪”三重保险：当验证损失连续3轮不下降，不仅触发早停，还会将学习率回调到初始值的0.5倍，再续训5轮——这招在finetune阶段让AUC提升了0.012。更重要的是，它记录每轮训练中各层梯度的L2范数，生成热力图，帮你一眼看出是底层GCN层梯度消失，还是顶层分类头过拟合。

这套设计不是炫技，而是来自血泪教训：去年帮一家物流平台优化运单路由，他们最初的GNN模型在测试集上F1=0.63，我们没动模型结构，只重构了FeatureProcessor——把司机GPS轨迹用DBSCAN聚类后作为“区域偏好”特征注入节点，F1直接跳到0.79。数据，永远比模型重要。

2.3 工程化考量：为什么必须包含模型导出与服务化接口？

写完代码跑通只是起点，上线才是终点。很多GNN项目死在部署环节：PyG模型无法用Triton推理，ONNX导出时报错“Unsupported op: torch_sparse.SparseTensor”。本代码包从第一天就考虑生产环境：

模型导出：提供export_to_onnx()方法，严格限定算子集——只用torch.mm,torch.relu,torch.dropout等Triton/TF支持的原生算子，禁用torch_scatter等扩展。导出时自动插入torch.jit.scripttrace，确保动态shape支持（如batch_size=1~128可变）。
服务化接口：附带Flask轻量API，支持两种调用模式：① 批量推理：上传CSV边表，返回所有节点嵌入；② 单点查询：GET /predict?node_id=U12345，返回该节点的top-5相似节点及相似度。接口内置缓存层——对高频查询节点（如头部商品），用LRU Cache缓存嵌入结果，QPS从800提升至3200。
监控埋点：在forward()函数中注入torch.cuda.memory_allocated()和time.time()，每100步记录显存峰值与单步耗时，生成Prometheus指标，接入公司统一监控平台。当某次上线后GPU显存异常增长，我们5分钟内定位到是新增的Attention-based聚合层未做mask，导致全连接计算。

这些不是“锦上添花”，而是GNN从实验室走向产线的必经之路。没有它们，你的代码再漂亮，也只是Jupyter里的玩具。

3. 核心代码解析与实操要点：手写GCN层的12个关键细节

3.1 GCN层实现：从数学公式到PyTorch张量的精确映射

让我们聚焦最核心的GCNLayer类。它只有137行，但每一行都经过生产环境验证。先看初始化部分：

def __init__(self, in_features: int, out_features: int, dropout: float = 0.0, activation: str = 'relu', add_self_loops: bool = True, normalize: bool = True): super().__init__() self.in_features = in_features self.out_features = out_features self.dropout = dropout self.activation = activation self.add_self_loops = add_self_loops self.normalize = normalize # 权重矩阵：注意！不是nn.Linear，因为GCN需要手动控制bias self.weight = nn.Parameter(torch.FloatTensor(in_features, out_features)) self.bias = nn.Parameter(torch.FloatTensor(out_features)) # 初始化：Xavier均匀分布，而非正态——更适合ReLU激活 nn.init.xavier_uniform_(self.weight.data, gain=nn.init.calculate_gain('relu')) nn.init.zeros_(self.bias.data)

这里藏着第一个关键细节：为什么用xavier_uniform_而不是kaiming_normal_？因为GCN的前向传播本质是线性变换+非线性激活，而xavier针对Sigmoid/Tanh设计，kaiming针对ReLU。但实测发现，在深层GCN（>4层）中，kaiming导致底层梯度方差衰减更快。我们做了对比实验：在Pubmed数据集上，3层GCN用kaiming初始准确率85.2%，用xavier为86.7%；但到了5层，kaiming掉到79.1%，xavier仍保持83.4%。原因在于GCN的消息传递机制放大了初始化偏差——xavier的增益计算更贴合图结构的频域特性。

第二个细节是forward方法的张量形状管理。这是新手最容易崩溃的地方：

def forward(self, x: torch.Tensor, adj: torch.Tensor) -> torch.Tensor: # Step 1: Dropout输入特征（不是权重！） if self.dropout > 0: x = F.dropout(x, p=self.dropout, training=self.training) # Step 2: 计算 A_hat * X * W # 注意adj形状：[N, N]，x形状：[N, in_features] # 矩阵乘法顺序：先adj @ x，再 @ weight，避免(N*N*in_features)内存爆炸 support = torch.mm(adj, x) # [N, in_features] output = torch.mm(support, self.weight) # [N, out_features] # Step 3: 加bias output = output + self.bias # Step 4: 激活函数 if self.activation == 'relu': output = F.relu(output) elif self.activation == 'tanh': output = torch.tanh(output) return output

重点看support = torch.mm(adj, x)这一行。很多教程写成x @ weight再adj @ result，这在小图上没问题，但当N=10万时，x @ weight产生[10w, 64]张量，adj @ result需要10w*10w*64浮点运算，显存直接爆掉。我们的顺序是adj @ x（[10w, 10w] @ [10w, 64]→[10w, 64]），再@ weight（[10w, 64] @ [64, 32]→[10w, 32]），计算量减少99.9%。这就是为什么我们强调“理解张量形状”比“背公式”重要。

第三个细节是自环添加的业务适配。add_self_loops参数不只是布尔值：

if self.add_self_loops: # 基础版：对角线+1 adj = adj + torch.eye(adj.size(0), device=adj.device) # 进阶版：按节点度加权自环（防孤立节点失真） if hasattr(self, 'degree_weight') and self.degree_weight: deg = torch.diag(adj.sum(dim=1)) # 度矩阵 adj = adj + 0.1 * deg # 自环权重=0.1*度数

在社交网络分析中，高粉丝数的KOL节点，自环权重设为0.5，让其自身特征在聚合中占比更高；而在分子图预测中，原子节点自环权重设为0，强调邻居化学键影响。这种灵活性，是黑盒库做不到的。

3.2 图构建模块：如何把MySQL表变成可训练的邻接矩阵？

真实业务中，图数据从不长成cora.content那样规整。以电商推荐为例，原始数据在MySQL有三张表：

user_behavior: user_id, item_id, behavior_type('click','cart','buy'), timestamp
item_info: item_id, price, category_id, brand_id
user_profile: user_id, age, city_level, gender

构建图的第一步，从来不是写模型，而是写SQL。本代码包的GraphBuilder.from_mysql()方法，会自动生成以下SQL：

-- 步骤1：提取核心边（用户-商品交互） CREATE TABLE edges AS SELECT DISTINCT user_id, item_id, CASE WHEN behavior_type='buy' THEN 3.0 WHEN behavior_type='cart' THEN 2.0 ELSE 1.0 END as edge_weight FROM user_behavior WHERE timestamp >= '2023-01-01'; -- 步骤2：生成节点ID映射（避免字符串ID导致embedding维度爆炸） CREATE TABLE node_mapping AS SELECT ROW_NUMBER() OVER(ORDER BY id) as node_id, id, type FROM ( SELECT DISTINCT user_id as id, 'user' as type FROM edges UNION ALL SELECT DISTINCT item_id as id, 'item' as type FROM edges ) t; -- 步骤3：构建邻接矩阵（稀疏存储） SELECT a.node_id as src, b.node_id as dst, e.edge_weight as weight FROM edges e JOIN node_mapping a ON e.user_id = a.id AND a.type='user' JOIN node_mapping b ON e.item_id = b.id AND b.type='item';

关键点在于边权重的业务定义。不是简单设为1，而是按行为强度赋权：购买=3.0，加购=2.0，点击=1.0。这使得GNN在聚合时，自然学到“购买关系比点击关系更重要”的先验知识。我们在某母婴电商项目中，仅调整权重策略，召回率就提升了11.3%。

第二步是邻接矩阵的存储优化。scipy.sparse.csr_matrix是标准选择，但要注意dtype：

# 错误：用float64存储权重——显存翻倍，无精度收益 adj_csr = csr_matrix((weights, (src_idx, dst_idx)), shape=(N, N), dtype=np.float64) # 正确：用float32，且对称图存储上三角 adj_csr = csr_matrix((weights, (src_idx, dst_idx)), shape=(N, N), dtype=np.float32) # 若为无向图，强制对称化 adj_csr = adj_csr + adj_csr.T.multiply(adj_csr.T > adj_csr) - adj_csr.multiply(adj_csr.T > adj_csr)

float32足够满足GNN精度需求，float64徒增显存压力。而对称化操作避免了无向图中重复存储，节省50%内存。

第三步是节点特征矩阵的拼接。user_profile和item_info表需对齐到同一索引空间：

# 获取节点映射字典 node2id = pd.read_sql("SELECT node_id, id, type FROM node_mapping", conn) user_map = node2id[node2id['type']=='user'].set_index('id')['node_id'].to_dict() item_map = node2id[node2id['type']=='item'].set_index('id')['node_id'].to_dict() # 构建用户特征矩阵（按node_id排序） user_feat = pd.read_sql("SELECT * FROM user_profile", conn) user_feat['node_id'] = user_feat['user_id'].map(user_map) user_feat = user_feat.sort_values('node_id').drop(['user_id', 'node_id'], axis=1) # 特征工程：年龄分箱，城市等级one-hot user_feat['age_bin'] = pd.cut(user_feat['age'], bins=[0,18,25,35,50,100], labels=False).fillna(-1) user_feat = pd.get_dummies(user_feat, columns=['city_level'], prefix='city') # 最终特征矩阵：[N_user, feat_dim] X_user = torch.tensor(user_feat.values, dtype=torch.float32)

这里体现了一个硬经验：永远不要在特征工程中用LabelEncoder对高基数类别编码。city_level只有5个值，可以用one-hot；但若brand_id有10万种，必须用Target Encoding或Embedding Layer。本代码包的FeatureProcessor会自动检测基数，>1000则切到Target Encoding。

3.3 训练循环：为什么验证集F1-score比准确率更有意义？

GNN常用于节点分类，但多数教程只打印accuracy，这在长尾分布下极具误导性。比如风控场景，正常用户占99.5%，欺诈用户仅0.5%，模型全判正常也能有99.5%准确率，毫无价值。本代码包的Trainer强制使用sklearn.metrics.f1_score(y_true, y_pred, average='macro')，并提供详细报告：

def evaluate(self, model, data_loader, device): model.eval() y_true, y_pred, y_prob = [], [], [] with torch.no_grad(): for batch in data_loader: x, adj, y = batch x, adj, y = x.to(device), adj.to(device), y.to(device) out = model(x, adj) pred = out.argmax(dim=1) prob = torch.softmax(out, dim=1) y_true.extend(y.cpu().numpy()) y_pred.extend(pred.cpu().numpy()) y_prob.extend(prob.cpu().numpy()) # 宏平均F1（每类独立计算F1再平均），对不平衡数据鲁棒 f1_macro = f1_score(y_true, y_pred, average='macro') # 分类报告：显示每类precision/recall/f1 report = classification_report(y_true, y_pred, target_names=['normal', 'fraud', 'suspicious']) # 混淆矩阵热力图 cm = confusion_matrix(y_true, y_pred) plt.figure(figsize=(6,4)) sns.heatmap(cm, annot=True, fmt='d', cmap='Blues') plt.title(f'Confusion Matrix (F1-macro={f1_macro:.4f})') return f1_macro, report, cm

更关键的是，我们实现了节点级可解释性。当模型预测某用户为“欺诈”时，能追溯到是哪些邻居节点的特征起了决定性作用：

# 使用Grad-CAM思想，计算邻居贡献度 def explain_prediction(self, model, x, adj, target_node): model.eval() x.requires_grad_(True) out = model(x, adj) loss = out[target_node].max() # 对目标节点输出求最大值 loss.backward() # 梯度加权邻接矩阵：adj[i,j] * grad_x[j] 衡量j对i的影响 grad_x = x.grad.abs() neighbor_influence = torch.mm(adj, grad_x) # [N, feat_dim] # 取top-5影响最大的邻居 influence_scores = neighbor_influence.sum(dim=1) # [N] top_k = torch.topk(influence_scores, k=5) return top_k.indices.numpy(), top_k.values.numpy()

在银行反诈项目中，这功能帮业务方确认：模型判定某商户欺诈，是因为其3个下游分销商近期有密集小额提现行为——这与规则引擎结论一致，极大增强了模型可信度。

4. 实操全流程：从零开始跑通电商推荐GNN

4.1 环境准备与依赖安装：避开CUDA版本陷阱

别急着写代码，先搞定环境。本代码包严格测试过CUDA 10.2/11.1/11.3三个版本，但有个隐藏雷区：PyTorch 1.10+与CUDA 10.2不兼容。如果你的服务器CUDA是10.2（常见于老集群），必须用PyTorch 1.9.1：

# CUDA 10.2 环境 pip install torch==1.9.1+cu102 torchvision==0.10.1+cu102 -f https://download.pytorch.org/whl/torch_stable.html # CUDA 11.1 环境 pip install torch==1.10.0+cu111 torchvision==0.11.1+cu111 -f https://download.pytorch.org/whl/torch_stable.html # CUDA 11.3 环境（推荐） pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 -f https://download.pytorch.org/whl/torch_stable.html

为什么强调这个？因为torch.mm在不同CUDA版本下，对半精度（float16）的支持有差异。我们在某客户现场，用CUDA 10.2跑float16训练，torch.mm偶尔返回NaN，换成CUDA 11.3后问题消失。本代码包默认用float32，但如果你想开启混合精度训练（AMP），请务必匹配CUDA版本。

依赖清单精简到极致，只保留必需项：

# requirements.txt torch>=1.9.0 numpy>=1.21.0 pandas>=1.3.0 scikit-learn>=1.0.0 matplotlib>=3.5.0 seaborn>=0.11.0

绝对不装torch-scatter、torch-sparse、pytorch_geometric。这些库的编译错误，是GNN新手放弃的最主要原因。我们的手写实现，已通过pytest覆盖所有边界条件：空图、全连接图、单节点图、自环缺失图。

4.2 数据准备：用真实电商日志生成训练样本

假设你有一份脱敏的电商日志user_behavior.csv（100万行），包含字段：user_id,item_id,behavior,timestamp。执行以下步骤：

步骤1：生成图结构

from gnn_builder import GraphBuilder # 初始化构建器，指定节点类型 builder = GraphBuilder( node_types=['user', 'item'], edge_weight_strategy='behavior_score' # 按行为类型赋权 ) # 从CSV构建图 graph_data = builder.from_csv( edges_path='user_behavior.csv', node_attrs={'user': 'user_profile.csv', 'item': 'item_info.csv'}, time_filter=('2023-01-01', '2023-06-30') # 只取半年数据 ) # 保存为标准格式 graph_data.save('data/ecommerce_graph.npz')

graph_data是一个命名元组，包含：

adj_matrix:scipy.sparse.csr_matrix，形状[N, N]
node_features:torch.Tensor，形状[N, feat_dim]
node_labels:torch.Tensor，形状[N]（用户节点标为0/1，商品节点标为品类ID）
train_mask,val_mask,test_mask:torch.BoolTensor，指示哪些节点参与训练

步骤2：特征工程

from feature_processor import FeatureProcessor processor = FeatureProcessor( numeric_cols=['age', 'price', 'avg_rating'], categorical_cols=['city_level', 'category_id', 'brand_id'], sequence_cols=['recent_clicks'] # 时序特征列 ) # 处理节点特征 X_processed = processor.fit_transform(graph_data.node_features) # 输出形状：[N, 128] —— 经过PCA降维和归一化

FeatureProcessor会自动：

对price做分位数缩放（QuantileTransformer），避免万元商品主导梯度
对category_id用Target Encoding：计算每个品类的平均转化率，替换原始ID
对recent_clicks（字符串如"1023,4567,8910"）做Embedding：先用Word2Vec训练点击序列，再取平均

步骤3：定义模型与训练

from models import GCN from trainer import Trainer # 初始化模型：2层GCN，隐层64维 model = GCN( num_features=X_processed.shape[1], hidden_dim=64, num_classes=2, # 用户是否高价值 dropout=0.5, num_layers=2 ) # 训练器配置 trainer = Trainer( model=model, lr=0.01, weight_decay=5e-4, patience=50, # 早停轮数 device='cuda' if torch.cuda.is_available() else 'cpu' ) # 开始训练 history = trainer.train( X=X_processed, adj=graph_data.adj_matrix, y=graph_data.node_labels, train_mask=graph_data.train_mask, val_mask=graph_data.val_mask, epochs=500 ) # 保存最佳模型 torch.save(trainer.best_model.state_dict(), 'models/gcn_ecommerce.pth')

训练过程会实时输出：

Epoch 1/500 | Train Loss: 0.682 | Val F1: 0.421 Epoch 2/500 | Train Loss: 0.651 | Val F1: 0.438 ... Epoch 187/500 | Train Loss: 0.213 | Val F1: 0.726 <- Best! Epoch 188/500 | Train Loss: 0.211 | Val F1: 0.724 Early stopping at epoch 187

步骤4：评估与可视化

# 加载最佳模型 model.load_state_dict(torch.load('models/gcn_ecommerce.pth')) # 在测试集上评估 f1, report, cm = trainer.evaluate( model, X_processed, graph_data.adj_matrix, graph_data.test_mask, graph_data.node_labels ) print(report) # precision recall f1-score support # 0 0.82 0.85 0.83 4210 # 1 0.71 0.67 0.69 790 # accuracy 0.80 5000 # macro avg 0.76 0.76 0.76 5000 # 可视化节点嵌入 from visualization import plot_embeddings plot_embeddings(model, X_processed, graph_data.adj_matrix, graph_data.node_labels, 'tsne_ecommerce.png')

t-SNE图会清晰显示：高价值用户（标签1）聚集在左上角，普通用户（标签0）分散在右下——证明GNN成功学到了区分性特征。

4.3 模型服务化：用Flask部署为REST API

训练完模型，下一步是上线。本代码包提供开箱即用的API服务：

# 启动服务 python api_server.py --model_path models/gcn_ecommerce.pth \ --graph_path data/ecommerce_graph.npz \ --device cuda

API端点：

POST /batch_predict：上传CSV边表，返回所有节点嵌入
GET /predict?node_id=U12345：返回该用户的top-10相似用户
GET /explain?node_id=U12345&target_class=1：返回影响预测的关键邻居

请求示例：

curl -X GET "http://localhost:5000/predict?node_id=U12345" \ -H "Content-Type: application/json"

响应：

{ "node_id": "U12345", "prediction": 1, "confidence": 0.87, "similar_users": [ {"user_id": "U67890", "similarity": 0.92}, {"user_id": "U24680", "similarity": 0.89} ], "explanation": { "top_neighbors": ["U67890", "U24680", "U13579"], "reason": "These users have high purchase frequency and similar category preferences." } }

服务内置健康检查：

/health返回{"status": "healthy", "gpu_memory": "3.2GB/16GB"}
/metrics返回Prometheus格式指标，如gnn_inference_latency_seconds{quantile="0.95"} 0.042

这意味着你可以把它无缝接入Kubernetes，用HPA（Horizontal Pod Autoscaler）根据gnn_inference_qps指标自动扩缩容。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “RuntimeError: Expected object of scalar type Float but got Double” —— 张量类型战争

这是GNN新手第一大敌。根本原因：PyTorch默认torch.tensor()创建float64（Double），但nn.Linear权重是float32（Float），相乘时报错。

正确做法：全局统一dtype。

# 在main.py开头设置 torch.set_default_dtype(torch.float32) # 或者显式指定 x = torch.tensor(data, dtype=torch.float32) adj = torch.tensor(adj_dense, dtype=torch.float32)

进阶技巧：用torch.autocast自动管理混合精度，但需确保所有输入都是float32：

with torch.autocast(device_type='cuda', dtype=torch.float16): out = model(x, adj) # x和adj必须是float32，autocast内部转float16

5.2 “CUDA out of memory” —— 显存不够的5种解法

当图太大（N>50万）时，显存爆炸是常态。我们总结出5种有效解法，按优先级排序：

减小batch_size：GNN通常用全图训练（batch_size=1），但可改用Neighbor Sampling。本代码包的DataLoader支持：
```
from torch_geometric.loader import NeighborLoader # 注意：这里用PyG的loader，但模型仍是手写GCN loader = NeighborLoader( data, num_neighbors=[10, 10], batch_size=1024 )
```
每次只采样目标节点的2跳邻居，显存降低70%。

启用梯度检查点（Gradient Checkpointing）：

from torch.utils.checkpoint import checkpoint def custom_forward(x, adj): return self.gcn_layer1(x, adj) out = checkpoint(custom_forward, x, adj) # 用时间换空间

用torch.sparse替代稠密矩阵：对稀疏图（边数/节点数 < 0.1），torch.sparse.mm比torch.mm快3倍，显存少80%。
FP16训练：torch.cuda.amp自动混合精度，但需修改Trainer：
```
scaler = torch
```