PFLlib: 个性化联邦学习算法库
图1: FedAvg 示例。你可以使用 generate_DATA.py
创建场景,并使用 main.py
, clientNAME.py
和 serverNAME.py
运行算法。
我们创建了一个用户友好的算法库和评估平台,适合那些联邦学习新手。通过贡献您的算法、数据集和指标,加入我们扩展联邦学习社区的行列吧。
-
一些实验结果可以在这里查看。
-
渴望了解如何使用它请参考本指南。
-
此库可以使用 4 层 CNN 在 Cifar100 上模拟场景,支持 500 个客户端,在 一张 NVIDIA GeForce RTX 3090 显卡上运行,消耗仅5.08GB GPU 内存。
-
PFLlib 主要集中在数据(统计)异质性。对于解决数据和模型异质性的算法和评估平台,请参考我们的扩展项目**异构联邦学习 (HtFL)**。
-
因为我们努力满足不同用户需求,项目的频繁更新可能会更改默认设置和场景创建代码,从而影响实验结果。
-
已关闭的问题可能对您有很大帮助。
-
在提交拉取请求时,请在评论框中提供足够的说明和示例。
统计异质性现象的起源是用户个性化,他们生成非独立同分布(non-IID)且不平衡的数据。在联邦学习场景中存在统计异质性的情况下,已经提出了大量方法来解决这个难题。相反,个性化联邦学习(pFL)可以利用统计异质数据来为每个用户学习个性化模型。
感谢@Stonesjtu,此库还可以记录模型的GPU 内存使用情况。根据FedCG,我们还引入了**从梯度中深度泄漏(DLG)攻击和峰值信噪比(PSNR)**度量来评估 tFL/pFL 算法的隐私保护能力(详情请参考 ./system/flcore/servers/serveravg.py
)。现在我们可以通过在 ./system/main.py
中设置 args.num_new_clients
,在一些客户端上训练并在其他新客户端上评估性能。请注意,并非所有 tFL/pFL 算法都支持此功能。
引用
@article{zhang2023pfllib,
title={PFLlib: Personalized Federated Learning Algorithm Library},
author={Zhang, Jianqing and Liu, Yang and Hua, Yang and Wang, Hao and Song, Tao and Xue, Zhengui and Ma, Ruhui and Cao, Jian},
journal={arXiv preprint arXiv:2312.04992},
year={2023}
}
带有代码的算法(更新中)
传统联邦学习 (tFL)
-
FedAvg — 从去中心化数据中高效的深度网络学习 AISTATS 2017
基于更新校正的 tFL
-
SCAFFOLD - SCAFFOLD: 联邦学习的随机控制平均 ICML 2020
基于正则化的 tFL
-
FedProx — 异构网络中的联邦优化 MLsys 2020
-
FedDyn — 基于动态正则化的联邦学习 ICLR 2021
基于模型分割的 tFL
-
MOON — 模型对比联邦学习 CVPR 2021
基于知识蒸馏的 tFL
-
FedGen — 异构联邦学习的数据无关知识蒸馏 ICML 2021
-
FedNTD — 联邦学习中通过非真实蒸馏保留全局知识 NeurIPS 2022
个性化联邦学习 (pFL)
-
FedMTL (不包括 MOCHA) — 联邦多任务学习 NeurIPS 2017
-
FedBN — FedBN: 通过本地批规范化的非IID特征联邦学习 ICLR 2021
基于元学习的 pFL
-
Per-FedAvg — 具有理论保证的个性化联邦学习:一种模型无关的元学习方法 NeurIPS 2020
基于正则化的 pFL
-
pFedMe — 带有 Moreau 信封的个性化联邦学习 NeurIPS 2020
-
Ditto — Ditto: 通过个性化的公平和稳健的联邦学习 ICML 2021
基于个性化聚合的 pFL
-
APFL — 自适应个性化联邦学习 2020
-
FedFomo — 通过一阶模型优化的个性化联邦学习 ICLR 2021
-
FedAMP — 在非IID数据上的个性化跨筒联邦学习 AAAI 2021
-
FedPHP — FedPHP: 具有继承私人模型的联邦个性化 ECML PKDD 2021
-
APPLE — 适应适应:为跨筒联邦学习学习个性化 IJCAI 2022
-
FedALA — FedALA: 个性化联邦学习的自适应本地聚合 AAAI 2023
基于模型分割的 pFL
-
FedPer — Federated Learning with Personalization Layers 2019
-
LG-FedAvg — Think Locally, Act Globally: Federated Learning with Local and Global Representations 2020
-
FedRep — Exploiting Shared Representations for Personalized Federated Learning ICML 2021
-
FedRoD — On Bridging Generic and Personalized Federated Learning for Image Classification ICLR 2022
-
FedBABU — Fedbabu: Towards enhanced representation for federated image classification ICLR 2022
-
FedGC — Federated Learning for Face Recognition with Gradient Correction AAAI 2022
-
FedCP — FedCP: Separating Feature Information for Personalized Federated Learning via Conditional Policy KDD 2023
-
GPFL — GPFL: Simultaneously Learning Generic and Personalized Feature Information for Personalized Federated Learning ICCV 2023
-
FedGH — FedGH: Heterogeneous Federated Learning with Generalized Global Header ACM MM 2023
-
FedDBE — Eliminating Domain Bias for Federated Learning in Representation Space NeurIPS 2023
-
FedCAC — Bold but Cautious: Unlocking the Potential of Personalized Federated Learning through Cautiously Aggressive Collaboration ICCV 2023
-
PFL-DA — Personalized Federated Learning via Domain Adaptation with an Application to Distributed 3D Printing Technometrics 2023
基于知识蒸馏的个性化联邦学习
-
FedDistill (FD) — Communication-Efficient On-Device Machine Learning: Federated Distillation and Augmentation under Non-IID Private Data 2018
-
FML — Federated Mutual Learning 2020
-
FedKD — Communication-efficient federated learning via knowledge distillation Nature Communications 2022
-
FedProto — FedProto: Federated Prototype Learning across Heterogeneous Clients AAAI 2022
-
FedPCL (w/o pre-trained models) — Federated learning from pre-trained models: A contrastive learning approach NeurIPS 2022
-
FedPAC — Personalized Federated Learning with Feature Alignment and Classifier Collaboration ICLR 2023
数据集和场景(更新中)
对于 标签偏差 场景,我们介绍 14 个著名的数据集:MNIST, EMNIST, Fashion-MNIST, Cifar10, Cifar100, AG News, Sogou News, Tiny-ImageNet, Country211, Flowers102, GTSRB, Shakespeare, 和 Stanford Cars。它们可以很容易地分成 IID 和 non-IID 版本。由于生成数据集(如拆分)的一些代码对所有数据集都是相同的,我们将这些代码移动到 ./dataset/utils/dataset_utils.py
中。在 non-IID 场景下,存在 2 种情况。第一种是 病态 non-IID 场景,第二种是 实际 non-IID 场景。在 病态 non-IID 场景中,例如,每个客户端上的数据仅包含特定数量的标签(可能只有 2 个标签),尽管所有客户端上的数据包含 10 个标签,比如 MNIST 数据集。在 实际 non-IID 场景中,使用狄利克雷分布(请参阅这篇论文 了解详情)。在 iid 场景中,我们可以输入 balance
,其中数据是均匀分布的。
对于 特征偏移 场景,我们使用 3 个广泛用于领域适应的数据集:Amazon Review(从此网站抓取原始数据)、Digit5(从此网站抓取原始数据)、和 DomainNet。
对于 现实世界(或物联网) 场景,我们还介绍了 3 个自然分离的数据集:Omniglot(20 个客户端,50 个标签)、HAR(人体活动识别)(30 个客户端,6 个标签)、PAMAP2(9 个客户端,12 个标签)。有关数据集和物联网中的 FL 算法的详细信息,请参阅我的 FL-IoT 仓库。
如果您需要另一个数据集,只需编写另一个代码进行下载,然后使用 utils。
MNIST 的示例
- MNIST
cd ./dataset # python generate_MNIST.py iid - - # 用于 iid 和不平衡场景 # python generate_MNIST.py iid balance - # 用于 iid 和平衡场景 # python generate_MNIST.py noniid - pat # 用于病态 noniid 和不平衡场景 python generate_MNIST.py noniid - dir # 用于实际 noniid 和不平衡场景 # python generate_MNIST.py noniid - exdir # 用于扩展狄利克雷策略
python generate_MNIST.py noniid - dir
的输出
标签数量: 10
客户端 0 数据大小: 2630 标签: [0 1 4 5 7 8 9]
标签样本: [(0, 140), (1, 890), (4, 1), (5, 319), (7, 29), (8, 1067), (9, 184)]
--------------------------------------------------
客户端 1 数据大小: 499 标签: [0 2 5 6 8 9]
标签样本: [(0, 5), (2, 27), (5, 19), (6, 335), (8, 6), (9, 107)]
--------------------------------------------------
客户端 2 数据大小: 1630 标签: [0 3 6 9]
标签样本: [(0, 3), (3, 143), (6, 1461), (9, 23)]
--------------------------------------------------
显示更多
客户端 3 数据大小: 2541 标签: [0 4 7 8] 标签样本: [(0, 155), (4, 1), (7, 2381), (8, 4)] -------------------------------------------------- 客户端 4 数据大小: 1917 标签: [0 1 3 5 6 8 9] 标签样本: [(0, 71), (1, 13), (3, 207), (5, 1129), (6, 6), (8, 40), (9, 451)] -------------------------------------------------- 客户端 5 数据大小: 6189 标签: [1 3 4 8 9] 标签样本: [(1, 38), (3, 1), (4, 39), (8, 25), (9, 6086)] -------------------------------------------------- 客户端 6 数据大小: 1256 标签: [1 2 3 6 8 9] 标签样本: [(1, 873), (2, 176), (3, 46), (6, 42), (8, 13), (9, 106)] -------------------------------------------------- 客户端 7 数据大小: 1269 标签: [1 2 3 5 7 8] 标签样本: [(1, 21), (2, 5), (3, 11), (5, 787), (7, 4), (8, 441)] -------------------------------------------------- 客户端 8 数据大小: 3600 标签: [0 1] 标签样本: [(0, 1), (1, 3599)] -------------------------------------------------- 客户端 9 数据大小: 4006 标签: [0 1 2 4 6] 标签样本: [(0, 633), (1, 1997), (2, 89), (4, 519), (6, 768)] -------------------------------------------------- 客户端 10 数据大小: 3116 标签: [0 1 2 3 4 5] 标签样本: [(0, 920), (1, 2), (2, 1450), (3, 513), (4, 134), (5, 97)] -------------------------------------------------- 客户端 11 数据大小: 3772 标签: [2 3 5] 标签样本: [(2, 159), (3, 3055), (5, 558)] -------------------------------------------------- 客户端 12 数据大小: 3613 标签: [0 1 2 5] 标签样本: [(0, 8), (1, 180), (2, 3277), (5, 148)] -------------------------------------------------- 客户端 13 数据大小: 2134 标签: [1 2 4 5 7] 标签样本: [(1, 237), (2, 343), (4, 6), (5, 453), (7, 1095)] -------------------------------------------------- 客户端 14 数据大小: 5730 标签: [5 7] 标签样本: [(5, 2719), (7, 3011)] -------------------------------------------------- 客户端 15 数据大小: 5448 标签: [0 3 5 6 7 8] 标签样本: [(0, 31), (3, 1785), (5, 16), (6, 4), (7, 756), (8, 2856)] -------------------------------------------------- 客户端 16 数据大小: 3628 标签: [0] 标签样本: [(0, 3628)] -------------------------------------------------- 客户端 17 数据大小: 5653 标签: [1 2 3 4 5 7 8] 标签样本: [(1, 26), (2, 1463), (3, 1379), (4, 335), (5, 60), (7, 17), (8, 2373)] -------------------------------------------------- 客户端 18 数据大小: 5266 标签: [0 5 6] 标签样本: [(0, 998), (5, 8), (6, 4260)] -------------------------------------------------- 客户端 19 数据大小: 6103 标签: [0 1 2 3 4 9] 标签样本: [(0, 310), (1, 1), (2, 1), (3, 1), (4, 5789), (9, 1)] -------------------------------------------------- 样本总数: 70000 训练样本数量: [1972, 374, 1222, 1905, 1437, 4641, 942, 951, 2700, 3004, 2337, 2829, 2709, 1600, 4297, 4086, 2721, 4239, 3949, 4577] 测试样本数量: [658, 125, 408, 636, 480, 1548, 314, 318, 900, 1002, 779, 943, 904, 534, 1433, 1362, 907, 1414, 1317, 1526]保存到磁盘。
完成数据集生成。
模型
-
用于 MNIST 和 Fashion-MNIST
- Mclr_Logistic(1*28*28)
- LeNet()
- DNN(1*28*28, 100) # 非凸
-
用于 Cifar10, Cifar100 和 Tiny-ImageNet
- Mclr_Logistic(3*32*32)
- FedAvgCNN()
- DNN(3*32*32, 100) # 非凸
- ResNet18, AlexNet, MobileNet, GoogleNet, 等等
-
用于 AG_News 和 Sogou_News
- LSTM()
- fastText() 在 Bag of Tricks for Efficient Text Classification
- TextCNN() 在 Convolutional Neural Networks for Sentence Classification
- TransformerModel() 在 Attention is all you need
-
用于 AmazonReview
-
用于 Omniglot
- FedAvgCNN()
-
用于 HAR 和 PAMAP
环境
安装 CUDA。
安装 conda 并激活 conda。
conda env create -f env_cuda_latest.yaml # 你可能需要使用 pip 降级 torch 以匹配 CUDA 版本
如何开始模拟(FedAvg 示例)
-
创建适当的环境(参见 环境)。
-
git clone https://github.com/TsingZ0/PFLlib.git
-
构建评估场景(参见 数据集和场景(更新中))。
-
运行评估:
cd ./system python main.py -data MNIST -m cnn -algo FedAvg -gr 2000 -did 0 # 使用 MNIST 数据集,FedAvg 算法和 4 层 CNN 模型
注意:最好在新机器上使用任何算法之前调整特定算法的超参数。
实际情况
如果您需要在实际情况下模拟 FL,包括 客户端掉线、慢训练者、慢发送者 和 网络 TTL,您可以设置以下参数来实现它。
-cdr
: 总客户端的掉线率。选择的客户端将在每个训练轮次中随机掉线。-tsr
和-ssr
: 所有客户端中慢训练者和慢发送者的比例。例如,一旦一个客户端被选为"慢训练者"/"慢发送者",它将始终比原始客户端训练/发送更慢。-tth
: 网络 TTL(毫秒)的阈值。
易于扩展
添加新算法和数据集到这个库很容易。
-
要将 新数据集 添加到此库,您需要编写下载代码和使用类似于
./dataset/generate_MNIST.py
的工具(您也可以将其视为模板)。 -
要添加 新算法,您可以利用在
./system/flcore/servers/serverbase.py
和./system/flcore/clients/clientbase.py
中编写的 Server 类和 Client 类。 -
要添加 新模型 ,只需将其添加到
./system/flcore/trainmodel/models.py
。 -
如果您在训练时有 新优化器,请将其添加到
./system/flcore/optimizers/fedoptimizer.py
实验结果
如果您对上述算法的**实验结果(例如准确性)**感兴趣,您可以在我们接受的联邦学习论文(即FedALA,FedCP,GPFL,和DBE)中找到一些结果,这些论文也使用了这个库。请注意,由于社区的需求,本开发项目可能无法重现这些论文中的结果,因为一些基本设置可能会发生变化。例如,我们以前在clientbase.py中设置了shuffle=False
@inproceedings{zhang2023fedala,
title={Fedala: Adaptive local aggregation for personalized federated learning},
author={Zhang, Jianqing and Hua, Yang and Wang, Hao and Song, Tao and Xue, Zhengui and Ma, Ruhui and Guan, Haibing},
booktitle={Proceedings of the AAAI Conference on Artificial Intelligence},
volume={37},
number={9},
pages={11237--11244},
year={2023}
}
@inproceedings{Zhang2023fedcp,
author = {Zhang, Jianqing and Hua, Yang and Wang, Hao and Song, Tao and Xue, Zhengui and Ma, Ruhui and Guan, Haibing},
title = {FedCP: Separating Feature Information for Personalized Federated Learning via Conditional Policy},
year = {2023},
booktitle = {Proceedings of the 29th ACM SIGKDD Conference on Knowledge Discovery and Data Mining}
}
@inproceedings{zhang2023gpfl,
title={GPFL: Simultaneously Learning Global and Personalized Feature Information for Personalized Federated Learning},
author={Zhang, Jianqing and Hua, Yang and Wang, Hao and Song, Tao and Xue, Zhengui and Ma, Ruhui and Cao, Jian and Guan, Haibing},
booktitle={Proceedings of the IEEE/CVF International Conference on Computer Vision},
pages={5041--5051},
year={2023}
}
@inproceedings{zhang2023eliminating,
title={Eliminating Domain Bias for Federated Learning in Representation Space},
author={Jianqing Zhang and Yang Hua and Jian Cao and Hao Wang and Tao Song and Zhengui XUE and Ruhui Ma and Haibing Guan},
booktitle={Thirty-seventh Conference on Neural Information Processing Systems},
year={2023},
url={https://openreview.net/forum?id=nO5i1XdUS0}
}