简介这是一份面向毕业设计及课程设计场景的图联邦学习系统实现代码包适合有一定Python基础、希望快速上手图神经网络与联邦学习项目的学生或开发者。项目聚焦FedGraph涵盖图神经网络、联邦学习、分布式训练、图数据预处理与推荐算法等核心模块可作为课题参考或二次开发基础。压缩包共149个文件以py源代码、pyc编译文件、log运行日志及sh脚本为主另含pt模型权重、cora/citeseer图数据集与说明文档整体大小仅1.56MB便于下载与部署。目前已有144人学习浏览具有一定参考价值。通过研读项目源码与日志读者可理解联邦学习中的模型聚合策略、GNN特征提取方式以及系统整体设计思路同时获得一套可直接运行的实验代码和调参记录对完成图联邦学习方向的毕设或课程设计颇有帮助。1. 图联邦学习系统设计与实现从一张网络图到一个可用系统做毕设拿到“图联邦学习系统设计与实现.zip”这个题目第一反应可能是这不就是把图卷积和联邦平均拼在一起真动手才发现图结构数据在联邦场景下比普通特征矩阵麻烦得多——每个客户端手里的子图不是同分布的节点ID也无法跨端对齐直接套用 FedAvg 收敛很慢。下面从代码包里最核心的几层开始讲把图联邦学习系统拆成“数据本地化、模型局部训练、参数聚合、系统调度”四层说明每层怎么设计、为什么这样设计以及在单机环境如何模拟多客户端跑通实验。如果你准备做类似毕设或想了解 GNN 与联邦学习的工程化落地下面的内容可以当作一份踩坑笔记。2. 图联邦学习系统的分层设计与代码结构2.1 为什么图联邦学习不能直接套用普通联邦框架普通联邦学习假设每个客户端的数据是独立同分布的样本行客户端之间的特征空间一致。图数据完全不同社交网络中的用户节点由边连接边的存在本身就说明节点之间不独立。客户端本地子图只是全局图的一个采样节点度分布、标签分布和子图的连通性在不同客户端之间差异明显。更麻烦的是客户端 A 的节点 1 和客户端 B 的节点 1 并不是同一个人节点没有全局唯一 ID。如果服务端把模型参数汇总后再广播每个客户端的 GNN 都需要重新处理本地的邻接矩阵丢失掉跨客户端的边关系。因此系统设计的第一原则是客户端只维护本地图结构和节点特征服务端只维护一个共享的全局模型参数副本节点表示通过模型权重间接共享不显式交换邻接矩阵或嵌入向量。代码包里的 server.py 和 client.py 就对应这一层职责划分。2.2 代码目录模块划分拿到这样一份 zip 压缩的毕设代码我一般会先看目录树确认“数据处理”和“联邦训练”是否分开。图联邦学习系统的常见做法是把数据预处理独立出来避免把切图、采样逻辑混进训练循环里。一个可用版本的大致结构如下graph_fed/ ├── client.py # 客户端局部训练流程 ├── server.py # 服务端聚合与分发 ├── model.py # GCN 模型定义 ├── data_loader.py # 图数据切分与本地客户端数据构造 ├── config.py # 全局配置超参数集中管理 ├── main.py # 入口支持单机模拟多客户端 └── utils/ ├── aggregator.py # FedAvg/FedProx 聚合算法 ├── sampling.py # 邻居采样与子图采样 └── metrics.py # 准确率、Micro-F1 等评估工具client.py 只做本地模型训练和梯度返回server.py 负责聚合权重和分发model.py 不依赖任何联邦逻辑可以被单独替换成 GAT 或 GraphSAGE。config.py 集中存放所有超参数我在实际跑实验时最推荐这种做法因为图联邦学习的可复现性很大程度上取决于数据划分种子和客户端数量。2.3 模型层GCN 的局部前向传播与全图池化模型设计上GCN 的局部前向传播不会感知到缺失的跨端边因为聚合只在邻接矩阵的相邻节点之间发生。把全局模型下发到客户端后每个客户端用自己的邻接矩阵计算一次两层的 GCN。以下是 model.py 中核心的 GCN 实现省略了激活函数初始化细节import torch import torch.nn as nn import torch.nn.functional as F class GCNLayer(nn.Module): def __init__(self, in_dim, out_dim, dropout0.5): super().__init__() self.weight nn.Parameter(torch.randn(in_dim, out_dim)) # 控制模型权重维度 self.dropout nn.Dropout(dropout) def forward(self, x, adj): # x: 本客户端节点特征 [num_nodes, in_dim] # adj: 归一化邻接矩阵 [num_nodes, num_nodes] support torch.mm(x, self.weight) out torch.spmm(adj, support) # 稀疏矩阵乘法, 避免 dense 造成 OOM return self.dropout(F.relu(out))这里的 adj 是经过归一化的稀疏邻接矩阵。torch.spmm只支持稀疏左矩阵乘稠密右矩阵内存占用比 Dense 版本小一个数量级在客户端子图较大时不会轻易打爆显存。权重由服务端下发的全局模型覆盖每个客户端在局部数据上迭代若干步后把梯度回传服务端再更新全局模型。这就是整个系统最核心的一次通信闭环。2.4 聚合层FedAvg 与 FedProx 的工程实现服务端聚合最简单的实现是 FedAvg也就是按客户端样本数加权平均。但如果客户端本地数据异构严重FedAvg 容易在客户端漂移。工程上的折中做法是 FedProx它在客户端损失函数里加一个近端正则项约束本地模型不要偏离全局模型太远。aggregator.py 里两种实现都保留用配置切换def fed_avg(global_model, client_models, client_sizes): total sum(client_sizes) with torch.no_grad(): for name, para in global_model.named_parameters(): # 刚开始时置零随后加权累加 para.data.zero_() for model, size in zip(client_models, client_sizes): para.data model.state_dict()[name] * (size / total)这段代码的关键是权重初始化为零然后按样本数加权累加而不是直接赋值给第一个客户端模型。如果不做零初始化聚合结果会受到客户端顺序影响导致结果不稳定。FedProx 的实现则是在 client.py 的损失函数上额外加入mu * ||w_local - w_global||^2这个mu是控制本地模型偏离程度的主要参数后面实战部分会给出推荐范围。3. 在本地把图联邦学习系统跑起来最小命令与参数3.1 环境准备与依赖安装图联邦学习系统的运行环境并不复杂常见组合是 Python 3.8 PyTorch Deep Graph LibraryDGL或 PyTorch Geometric。这里假设使用 PyTorch Geometric 作为图学习基础库因为它对稀疏图的算子封装更友好。安装命令如下conda create -n graphfed python3.8 -y conda activate graphfed pip install torch2.0.1 pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.0cu118.html pip install torch-geometric pip install numpy scikit-learn networkx安装torch-scatter和torch-sparse时要用官方预编译 wheel 地址版本必须跟 torch 一 一对应这是图学习环境里最常见的一个坑。如果不指定-f参数pip 可能会尝试从源码编译耗尽内存后报错。装完库之后用下面命令验证是否正常python -c import torch_geometric; print(success)3.2 入口 main.py 的参数表入口脚本main.py提供了argparse参数解析。我在运行这个毕设代码时一般会先看python main.py --help确认参数名再根据自己的机器内存调节客户端数量和批量大小。常见参数定义如下在终端中直接传参即可覆盖 config.py 的默认值。参数默认值作用--datasetcora数据集名称支持 cora/citeseer/pubmed--client_num5参与聚合的客户端数量--local_epoch3每个客户端本地训练的 epoch 数--batch_size00 表示全图梯度下降0 切换成图采样训练--aggregationfedavgfedavg 或 fedprox--mu0.01fedprox 近端项系数仅在 aggregationfedprox 时生效--seed42数据切分种子固定后结果可复现特别说明--seed这个参数。图联邦实验中如果每次运行数据切分结果不同不同客户端上的节点子图就不同模型指标波动会很大。固定种子是让实验可复现的最低要求也是毕设论文里“实验设置”部分必须写明的内容。3.3 数据切分按节点还是按子图数据切分方式直接决定任务的难度。最常见的切分方式是按节点采样也就是把节点随机分成若干份每份客户端只保留属于自己的节点和它们之间的边。这种切分下客户端子图通常是不连通的而且跨客户端的边全部被丢弃信息量损失严重。代码里我一般用networkx来做样本划分保留本地公共边具体如下import networkx as nx import numpy as np def split_graph_by_nodes(graph, client_num, seed42): nodes list(graph.nodes()) rng np.random.RandomState(seed) rng.shuffle(nodes) split np.array_split(nodes, client_num) client_graphs [] for node_set in split: subgraph graph.subgraph(node_set).copy() client_graphs.append(subgraph) return client_graphs这里np.array_split会尽量让每个客户端节点数均匀但每个子图的边数差异可能非常大因为中心节点的度分布是长尾的。所以在对比实验结果时不仅要看客户端数量还要报告每个客户端子图的平均边数。否则你无法判断精度下降是联邦机制导致的还是单纯因为其中某个客户端数据太少。3.4 启动训练与查看日志配置好 dataset、client_num 和 seed 之后直接一条命令启动训练python main.py --dataset cora --client_num 5 --local_epoch 5 --aggregation fedavg --seed 42日志会打印每一轮通信后的全局测试准确率和三个时间戳客户端本地训练耗时、通信耗时、聚合耗时。如果client_num超过 CPU 核数你会看到明显的等待时间这是通信模拟模块故意添加的 sleep 造成的。实际分布式环境中通信网络延迟比本地训练大一到两个数量级所以毕设代码里的模拟通信耗时对理解真实系统有参考价值。训练完成后终端会输出最终准确率和所有验证指标。4. 联邦训练循环里的参数调整与常见坑4.1 本地训练 epoch 与 batch 的配合local_epoch是每次通信轮次中客户端在本地上执行的训练步数。设得过小客户端模型还没来得及收敛就把梯度回传全局模型进步缓慢设得过大客户端模型被迫在自有子图上过拟合聚合后容易发生漂移。我的常用范围是 310Cora 这类小数据集一般 5 就能看到收敛趋势。batch_size 的取值更敏感。全图梯度下降在小数据集上稳定但数据集一换成 PubMed全图计算直接把所有节点的邻居都展开GPU 显存很容易溢满。这时需要切换成邻居采样模式。PyTorch Geometric 的NeighborSampler是常见方案每层采样 1015 个邻居from torch_geometric.loader import NeighborSampler loader NeighborSampler( edge_index, sizes[15, 10], batch_size512, shuffleTrue, num_workers0 )sizes[15, 10]表示第一层采样 15 个邻居第二层采样 10 个邻居。对两层 GCN 来说这个配置可以在保持精度的同时把显存占用控制在 2GB 以下。如果采样数设置过大训练会变慢但精度不一定更高因为采样噪声随着邻居数增加会降低模型对局部结构的敏感性。4.2 聚合策略怎么选FedAvg 还是 FedProx我实际跑实验的经验是在客户端数据分布比较均匀时FedAvg 和 FedProx 的差距不明显但一旦客户端子图度分布差异超过三倍FedProx 的优势就会体现。原因在于 FedProx 的近端项能阻止某一个客户端把全局模型拉向自己的局部最优。mu的调节规律如下mu行为表现适用场景0.001近端约束弱退化接近 FedAvg数据同构度高的实验0.01稳定收敛精度和速度平衡一般图数据默认推荐0.1强约束客户端更新趋缓标签分布严重倾斜时1全局模型主导客户端学习不足不推荐使用我一般会扫描[0.001, 0.01, 0.1]三个数量级每次固定--seed然后取测试集上平均精度最高的值。注意不要单独调mu而不固定local_epoch二者是强耦合的mu调大后如果没有同步增大local_epoch本地模型几乎不更新聚合精度会骤降。4.3 通信量与稀疏化的平衡图联邦学习的通信瓶颈不在模型权重本身而在客户端上报梯度时附带的一些元数据。毕设代码里经常忽略这个点但在系统设计说明里不能漏。常见做法是把梯度中绝对值小于阈值的元素置零然后在传输时只保存非零元素索引和值这就是梯度稀疏化def threshold_compress(grad, ratio0.01): flat grad.flatten() k max(1, int(flat.shape[0] * ratio)) _, topk_idx torch.topk(flat.abs(), k) mask torch.zeros_like(flat, dtypetorch.bool) mask[topk_idx] True return flat[mask], topk_idx, flat.shape这里的ratio0.01表示只保留梯度中绝对值最大的 1%通信量可以压缩到原来的百分之一。代价是模型收敛速度下降需要适当增大通信轮次。如果毕设里对通信次数没有硬性限制我建议把ratio设为 0.050.1既能明显降低模拟通信耗时又不会让精度掉超过一个点。4.4 三个最容易把系统跑飞的点第一个是邻接矩阵未归一化。GCN 里的对角度矩阵如果直接用原始度矩阵的逆乘上去数值在深层传播后会指数级增长训练 loss 直接变成 NaN。第二个是客户端数量小于 2。有些人在 main.py 里把--client_num 1这虽然能跑通但联邦聚合的意义就不存在了比较结果也会很奇怪。第三个是随机种子只在数据切分时固定没有在模型初始化时固定导致多次实验精度波动远大于算法改进带来的增益。正确的做法是在完整训练流程入口处调用set_seed把 torch、numpy 和 Python 的 random 全部设置好def set_seed(seed): import random import numpy as np random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) torch.backends.cudnn.deterministic Truetorch.backends.cudnn.deterministic设置为 True 会让卷积和稀疏矩阵计算按确定算法执行虽然不是所有算子都支持但对 GCN 的矩阵乘来说已经是足够好的可复现保障。5. 用一个小工具验证系统正确性5.1 对比集中式训练基准拿到图联邦系统的代码后我建议第一步不是直接调参而是先做一个“集中式基准对照”。把全部图数据集中在一个客户端上用完全相同的模型结构和超参训练同样轮数记录最优测试准确率。如果联邦版本的精度比集中式低不超过 2%说明系统的通信和聚合没有严重 bug如果差得很多问题大概率出在数据切分上。5.2 检查聚合前后权重变化量更细粒度的验证方式是直接观察服务端聚合前后模型权重的 L2 范数变化。理想情况是每一轮变化量逐渐变小最终持平。用下面代码可以记录with torch.no_grad(): prev_params [p.clone() for p in model.parameters()] # 执行一轮联邦训练和聚合 diff sum((p - q).norm().item() ** 2 for p, q in zip(model.parameters(), prev_params)) print(fround [{rnd}] parameter diff: {diff:.4f})如果 diff 在第二三轮突然增大通常意味着某个客户端数据有问题或本地学习率过大。5.3 可视化图嵌入最后一个技巧是用测试集的节点嵌入做一次 t-SNE 可视化。把服务端最终模型下发到任意客户端输出该客户端测试节点的最后一层 embedding再用 sklearn 的 TSNE 降到二维并画散点图。颜色按标签区分如果标签聚成清晰的簇说明图结构信息确实通过联邦学习迁移到了全局模型中。from sklearn.manifold import TSNE import matplotlib.pyplot as plt def visualize_embeddings(emb, label, name): tsne TSNE(n_components2, perplexity30) z tsne.fit_transform(emb) plt.scatter(z[:, 0], z[:, 1], clabel, cmaptab10, s5) plt.savefig(name)可视化这一步能直接用在毕设报告里作为“全局模型可迁移性”的证据比单纯一张精度表更有说服力。把集中式、FedAvg、FedProx 三种结果放在同一画布上对比就能直观看到聚合策略对节点嵌入分布的影响。把这三张图放进毕设报告时记得在图片标题里标注客户端数量和本地 epoch审阅老师最关心这些控制变量。本文还有配套的精品资源点击获取