Flower 联邦学习差分隐私与安全聚合实战基于 MNIST 的 fl-dp-sa 示例源码级解析【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本文以 Flower 仓库中的fl-dp-sa示例examples/fl-dp-sa/README.md为核心系统讲解如何在联邦学习训练流程中同时引入中央差分隐私Central Differential PrivacyCentral DP客户端侧固定裁剪与安全聚合Secure AggregationSecAgg覆盖项目获取、依赖安装、模拟/部署两种运行模式以及从客户端裁剪模组到服务端噪声注入的完整实现链路。读完本文你将能够复现一个面向 MNIST 的隐私保护联邦学习应用并能理解 Flower 中 DP 包装策略、fixedclipping_mod与SecAggPlusWorkflow的协作原理与关键参数含义。示例概述在 FedAvg 之上叠加 DP 与 SecAggfl-dp-sa在结构上与quickstart-pytorch示例一脉相承核心差异在于它在标准 FedAvg 训练流程之外额外集成了两层隐私保护机制中央差分隐私客户端侧固定裁剪客户端在把模型更新上传前按服务端下发的固定裁剪范数clipping_norm对更新做裁剪服务端聚合后再向聚合结果注入按noise_multiplier校准的高斯噪声从而在数学上提供差分隐私保证。安全聚合SecAgg客户端之间通过密钥分享secret sharing机制对更新进行加密封装服务端只能聚合加总后的结果无法窥探单个客户端的更新内容从而在通信链路之上进一步切断服务端对个体更新的直接可见性。示例设计目标是小轮次演示服务端默认只运行 3 轮ServerConfig(num_rounds3)因此非常适合用于验证 DP 与 SecAgg 的完整工作链路而非追求最终模型精度。获取并搭建项目安装 Flower 并拉取应用骨架首先安装 Flower 框架本体pip install flwr然后通过 Flower CLI 的flwr new从 Flower Hub 拉取应用模板flwr new flwrlabs/fl-dp-sa命令会在当前目录下创建一个名为fl-dp-sa的新目录其骨架结构如下fl-dp-sa ├── fl_dp_sa │ ├── client_app.py # 定义 ClientApp含 DP 裁剪与 SecAgg 客户端模组 │ ├── server_app.py # 定义 ServerApp含 DP 包装策略与 SecAgg 工作流 │ └── task.py # 定义模型、训练逻辑与数据加载 ├── pyproject.toml # 项目元数据依赖与运行配置 └── README.md这一骨架与仓库内 examples/fl-dp-sa 目录结构完全一致。其中 pyproject.toml 同时承担了依赖声明与Flower 应用配置双重职责。安装依赖与本地包在全新 Python 环境中以可编辑模式安装项目会同时安装pyproject.toml中声明的依赖以及fl_dp_sa包本身pip install -e .从 pyproject.toml 可以看到本项目声明的关键依赖依赖版本要求用途flwr[simulation]1.36.0Flower 框架本体及仿真引擎扩展flwr-datasets[vision]0.6.1联邦数据集划分IID 分区与 MNIST 加载torch2.10.0模型定义与训练torchvision0.25.0图像变换ToTensor、Normalize同时pyproject.toml 中通过[tool.flwr.app.components]声明了应用入口serverapp fl_dp_sa.server_app:app、clientapp fl_dp_sa.client_app:app并通过[tool.flwr.app.config]给出了全部 DP 与 SecAgg 参数的默认值这部分将在下文详解。运行联邦训练仿真模式与部署模式Flower 允许同一份代码在不做任何修改的情况下以**仿真Simulation与部署Deployment**两种模式运行。对初次接触 Flower 的开发者推荐使用仿真模式因为它需要手动启动的组件更少——默认情况下flwr run即使用仿真引擎。仿真模式100 个虚拟 SuperNode示例面向100 个虚拟 SuperNode设计而仿真运行时默认只分配 10 个节点因此需要先调整仿真配置flwr federation simulation-config --num-supernodes100该命令会改写本地SuperLink连接的仿真运行时配置执行前需确保你的默认SuperLink连接点已就绪通常通过flwr提供的本地启动方式准备。随后即可启动一轮完整训练。运行时可临时覆盖pyproject.toml中定义的ClientApp/ServerApp参数例如将噪声乘子调整为 0.1、裁剪范数调整为 5flwr run . --run-config noise-multiplier0.1 clipping-norm5 --stream--stream会将运行日志实时流式输出到终端方便观察每轮裁剪与噪声注入的日志信息详见下文源码解析。部署模式真实多机联邦若要在真实的多节点环境中运行每个 SuperNode 对应一台物理/虚拟设备则使用 Flower 的部署引擎Deployment Engine方式启动。流程与仿真模式的主要差异在于需要分别手动启动SuperLink、SuperNode与执行flwr run的进程具体启动编排可参考仓库内框架文档framework/docs 目录下的运行指南。在跨公网或不可信网络环境时可进一步叠加 TLS 加密通信与 SuperNode 身份认证这些均属部署引擎下的增强选项不影响本示例的代码结构。源码级解析DP 与 SecAgg 如何协同工作fl-dp-sa的隐私机制由三个文件共同实现下面逐一拆解其职责与实现证据。客户端裁剪模组与 SecAgg 模组client_app.py 中定义了一个标准NumPyClientfit从服务端下发参数开始本地训练 1 轮epochs1返回新权重、样本数与训练指标evaluate在本地测试集上计算损失与准确率。核心的隐私相关配置位于ClientApp的mods列表中app ClientApp( client_fnclient_fn, mods[ secaggplus_mod, fixedclipping_mod, ], )两个内建模组的分工如下fixedclipping_mod实现客户端侧固定裁剪。其实现位于 framework/py/flwr/client/mod/centraldp_mods.py仅对MessageType.TRAIN消息生效先从FitIns配置中读取服务端下发的clipping_norm键名常量KEY_CLIPPING_NORM clipping_norm定义于 framework/py/flwr/supercore/differential_privacy.py若缺失则抛出KeyError提示必须与服务端DifferentialPrivacyClientSideFixedClipping包装策略配合使用随后在调用内层应用拿到FitRes后以server_to_client_params为基准计算模型更新并执行裁剪。其源码注释明确指出使用多个模组时要注意顺序fixedclipping_mod通常应作为最后一个对参数做处理的模组这正是本示例把secaggplus_mod放在其前面的原因。secaggplus_mod为客户端更新执行 SecAgg 协议所需的密钥分享与加密封装是服务端SecAggPlusWorkflow的客户端对端。服务端DP 包装策略 SecAgg 工作流server_app.py 组装了完整的隐私保护服务端逻辑用get_weights(Net())初始化全局模型参数通过ndarrays_to_parameters转为 FlowerParameters格式作为 FedAvg 的initial_parameters。依据运行配置num-sampled-clients计算每轮参与客户端数min_fit_clients int(num_sampled_clients * fraction_fit)其中fraction_fit 0.2即每轮采样 20 个客户端时实际要求至少 4 个客户端参与拟合。以DifferentialPrivacyClientSideFixedClipping包装 FedAvg 策略传入noise_multiplier与clipping_norm均从run_config读取。用LegacyContext包装上下文设定ServerConfig(num_rounds3)。将DefaultWorkflow的fit_workflow替换为SecAggPlusWorkflow传入num_shares分享总份数与reconstruction_threshold重构阈值。上述 DP 包装策略的实现位于 framework/py/flwr/server/strategy/dp_fixed_clipping.py其关键机制值得展开参数校验构造时强制要求noise_multiplier 0、clipping_norm 0、num_sampled_clients 0非法值直接抛出ValueError。裁剪范数下发configure_fit在调用内部策略生成FitIns后向每个fit_ins.config注入{clipping_norm: self.clipping_norm}这正是客户端fixedclipping_mod能取到裁剪值的数据通路。服务端加噪aggregate_fit在内部策略聚合完成后调用add_gaussian_noise_to_params对聚合参数注入高斯噪声并输出噪声标准差日志若实际返回参数的客户端数与num_sampled_clients不一致会输出CLIENTS_DISCREPANCY_WARNING警告——提示这会影响 DP 保证可能导致隐私泄露或噪声校准失当见 framework/py/flwr/supercore/differential_privacy.py。另外框架还提供了服务端裁剪变体DifferentialPrivacyServerSideFixedClippingframework/py/flwr/server/strategy/dp_fixed_clipping.py其裁剪发生在服务端而非客户端本示例选择的是客户端裁剪方案因此客户端必须挂载fixedclipping_mod。隐私机制的数学内核DP 与裁剪的底层数值计算集中在 framework/py/flwr/supercore/differential_privacy.py三处核心函数决定了隐私预算的物理含义get_normL36-L40将各层参数展平后计算整体 L2 范数作为裁剪依据。clip_inputs_inplaceL50-L58采用论文《Deep Learning with Differential Privacy》arXiv:1607.00133中的 FlatClip 方法缩放因子为min(1, clipping_norm / input_norm)——当更新范数超过裁剪阈值时按比例整体缩小否则保持原样。compute_stdvL61-L68高斯噪声标准差计算公式为stdv (noise_multiplier * clipping_norm) / num_sampled_clients。可以看到参与客户端越多噪声越小而noise_multiplier与clipping_norm越大噪声越强。这也解释了为何示例中num_sampled_clients必须与仿真节点数、采样配置保持一致——它直接参与噪声校准。compute_clip_model_updateL71-L81则定义了客户端更新的裁剪语义先计算model_update param1 - param2本地训练后参数减去服务端下发参数对更新执行裁剪后再以param2 裁剪后更新的方式写回param1。整个过程在客户端fixedclipping_mod与服务端aggregate_fit中都以该函数为基础。配置参数速查一份可运行的隐私预算清单所有默认参数集中在 pyproject.toml分两组[tool.flwr.app.config] # 差分隐私DP参数 noise-multiplier 0.2 # 高斯机制噪声乘子 clipping-norm 10 # 客户端更新裁剪范数L2 num-sampled-clients 20 # 每轮采样客户端数参与噪声校准 # SecAgg 协议参数 num-shares 7 # 密钥分享总份数 reconstruction-threshold 4 # 重构秘密所需的最少份额数各参数的含义与调优建议参数默认值作用与建议noise-multiplier0.2高斯噪声乘子直接缩放注入聚合结果的噪声强度。框架文档建议追求较强隐私保证时取1.0 及以上值越大隐私越强但模型精度损失越大。演示场景默认 0.2。clipping-norm10客户端更新的 L2 范数裁剪阈值。过小会过度抑制更新导致收敛慢过大会削弱裁剪带来的隐私保护。num-sampled-clients20每轮参与训练的客户端数同时参与噪声标准差计算见compute_stdv公式需与仿真节点规模及采样配置匹配。num-shares7SecAgg 中把每个客户端秘密拆分的份额总数需结合参与客户端数设置通常保证num-shares 参与客户端数。reconstruction-threshold4从份额重构秘密所需的最少份数门限值4 num-shares。即使部分客户端掉线或退出只要凑齐阈值份额即可完成聚合体现容错性。这些参数均可在运行时通过flwr run . --run-config ...覆盖例如前文演示的noise-multiplier0.1 clipping-norm5无需改动代码即可做隐私-精度权衡实验。数据与模型MNIST IID 分区的加载方式task.py 定义了与隐私机制无耦合的常规训练组件便于独立理解模型经典的 2 层卷积 CNNconv1(1→6)→ 池化 →conv2(6→16)→ 3 层全连接120→84→10输入为 28×28 单通道 MNIST 灰度图。数据加载借助flwr-datasets的FederatedDataset与IidPartitioner将ylecun/mnist数据集按 IID 方式划分为num_partitions个分区对应 100 个虚拟客户端每个分区内部再以train_test_split(test_size0.2, seed42)拆出 80% 训练、20% 测试图像经ToTensor与Normalize((0.5,), (0.5,))归一化训练批大小为 32。训练使用 Adam 优化器与交叉熵损失本地训练epochs轮后返回训练集/验证集上的 loss 与 accuracyget_weights/set_weights完成 PyTorchstate_dict与 Flower 参数列表NumPy 数组之间的互转。客户端client_fn通过context.node_config[partition-id]与context.node_config[num-partitions]为每个 SuperNode 分配唯一数据分区服务端通过weighted_average按样本数加权聚合各客户端的训练/验证指标得到全局train_loss、train_accuracy、val_loss、val_accuracy等上报指标。端到端数据流小结综合以上源码一轮带隐私保护的联邦训练完整数据流如下服务端DifferentialPrivacyClientSideFixedClipping.configure_fit在 FedAvg 生成的每个FitIns中注入clipping_norm客户端侧模组按注册顺序执行secaggplus_mod先对更新做 SecAgg 密钥分享封装fixedclipping_mod最后以服务端下发的裁剪范数对本地更新做 L2 裁剪服务端SecAggPlusWorkflow收集各客户端的份额在达到reconstruction-threshold门槛后安全重构聚合结果全程不可见单个客户端更新聚合完成后DP 包装策略按stdv noise_multiplier * clipping_norm / num_sampled_clients向全局参数注入高斯噪声再进入下一轮。由此裁剪限制单客户端影响力 噪声模糊个体贡献 SecAgg 隐藏个体更新三层机制共同构成该示例的隐私保护闭环。若希望进一步调整轮数、参与规模或对比服务端裁剪方案可直接修改 server_app.py 中的ServerConfig与策略包装参数或参考框架内DifferentialPrivacyServerSideFixedClipping与自适应裁剪模组adaptiveclipping_mod见 framework/py/flwr/client/mod/centraldp_mods.py继续扩展。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考