PFLlib
37 methods
我們為那些新的聯合學習的人創建了一個對初學者友好的算法庫和基準平台。加入我們，通過為該項目貢獻您的算法，數據集和指標來擴展FL社區。
？ Pfllib現在擁有其官方網站和域名：https：//www.pfllib.com/ !!!
？排行榜是直播的！我們的方法（FEDCP，GPFL和Feddbe）導致了道路。值得注意的是，Feddbe在不同的數據異質性水平上表現出色。
？我們將在下一個版本中將許可證更改為Apache-2.0。
已經添加了四個新數據集，其中兩個解決了實際情況：（1）來自來自不同醫院的淋巴結切片中乳腺癌轉移的腫瘤組織斑塊，以及（2）不同相機陷阱捕獲的野生動物照片。其他兩個數據集側重於標籤鍊式場景：來自19 Covid-19的醫院的胸部X射線圖像，以及用於胃腸道疾病檢測的醫院的內窺鏡圖像。這些數據集也與我們的htfllib兼容
圖1：FedAvg的示例。您可以使用generate_DATA.py創建一個方案，並使用main.py ， clientNAME.py和serverNAME.py運行算法。對於新算法，您只需要在clientNAME.py和serverNAME.py中添加新功能。
如果您發現我們的存儲庫有用，請引用相應的論文：
@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}
}
37傳統的FL（TFL）和個性化FL（PFL）算法，3個方案和24個數據集。
一些實驗結果在其論文和此處都是可用的。
請參閱本指南以了解如何使用它。
基準平台可以使用CIFAR100上的4層CNN模擬場景，其中一個NVIDIA GEFORCE RTX 3090 GPU卡只有5.08GB GPU內存成本。
我們提供隱私評估和系統的研究建議。
現在，您可以通過設置args.num_new_clients in ./system/main.py來培訓一些客戶，並評估新客戶的性能。請注意，並非所有TFL/PFL算法都支持此功能。
Pfllib主要關注數據（統計）異質性。有關算法和基準平台，該平台既可以解決數據和模型異質性，請參閱我們擴展的項目異質聯合學習（HTFLLIB） 。
當我們努力滿足各種用戶需求時，該項目的頻繁更新可能會改變默認設置和場景創建代碼，從而影響實驗結果。
出現錯誤時，封閉的問題可能會對您有所幫助。
提交拉動請求時，請在評論框中提供足夠的說明和示例。
數據異質性現象的起源是用戶的特徵，他們生成非IID（不是獨立且分佈相同）和不平衡數據的特徵。在FL情況下存在數據異質性，已經提出了無數方法來破解這種硬堅果。相比之下，個性化的FL（PFL）可以利用統計上異質的數據來學習每個用戶的個性化模型。
傳統的FL（TFL）
基本TFL
FedAvg - 從分散數據AISTATS 2017中對深層網絡的溝通效率學習
基於更新校正的TFL
腳手架- 腳手架：聯邦學習ICML 2020的隨機控制平均
基於正則化的TFL
FEDPROX-在異質網絡中聯合優化MLSYS 2020
Feddyn-基於動態正則化ICLR 2021的聯合學習
基於型號的TFL
月亮- 模型對抗性聯合學習CVPR 2021
聯邦快遞- 通過logits校準ICML 2022的聯合學習與標籤分佈偏斜
基於知識依據的TFL
FedGen-無數據知識蒸餾，用於異質聯邦學習ICML 2021
FEDNTD - 通過聯邦學習神經2022中的非實際蒸餾保護全球知識
個性化的FL（PFL）
基於元學習的PFL
Per-Fedavg - 具有理論保證的個性化聯合學習：一種模型不合時宜的元學習方法神經2020
基於正則化的PFL
PFEDME - 莫羅信封神經2020的個性化聯合學習
同上- 同上：通過個性化ICML 2021
基於個性化聚集的PFL
APFL - 自適應個性化聯合學習2020
FedFomo - 一階模型優化ICLR 2021的個性化聯合學習
FedAmp - 非IID數據的個性化跨核心聯合學習AAAI 2021
FEDPHP - FEDPHP：通過繼承的私人模型ECML PKDD 2021的聯合個性化
蘋果- 適應適應：學習個性化的跨核心聯合學習ijcai 2022
FEDALA - FEDALA：個性化聯邦學習AAAI 2023的自適應本地聚合
基於模型分解的PFL
FEDPER - 與個性化層的聯合學習2019
LG-FEDAVG - 在本地思考，全球行動：與本地和全球代表的聯邦學習2020
FEDREP - 為個性化聯合學習ICML 2021的共享表示形式
Fedrod-關於圖像分類ICLR 2022的橋接通用和個性化聯合學習
FedBabu - FedBabu：邁向聯合圖像分類ICLR 2022的增強表示形式
FedGC-聯合學習以梯度校正AAAI 2022
FEDCP - FedCP：通過有條件政策KDD 2023分開特徵信息，以供個性化聯合學習
GPFL - GPFL：同時學習個性化聯合學習ICCV 2023的通用和個性化功能信息
FEDGH - FEDGH：具有廣義全球標頭ACM MM 2023的異質聯邦學習
Feddbe - 消除代表空間中聯邦學習的領域偏見神經2023
FedCac-大膽但謹慎：通過謹慎的積極協作ICCV 2023釋放個性化聯合學習的潛力
PFL-DA - 通過域適應的個性化聯合學習，並使用分佈式3D打印Technometrics 2023
其他PFL
FEDMTL（不是摩卡咖啡） - 聯邦多任務學習神經2017
FEDBN - FEDBN：通過本地批發歸一化ICLR 2021對非IID特徵的聯合學習
基於知識依據的PFL（更多在HTFLLIB中）
Feddistill（FD） - 溝通效率的機上機器學習：非IID私人數據2018下的聯合蒸餾和增強
FML - 聯邦共同學習2020
FEDKD - 通過知識蒸餾自然傳播的溝通效率的聯合學習2022
FEDPROTO - FEDPROTO：非均質客戶的聯合原型學習AAAI 2022
FEDPCL（帶有預訓練的模型） - 預先訓練模型的聯合學習：一種對比學習方法神經2022
FEDPAC - 具有功能一致性和分類器協作ICLR 2023的個性化聯合學習
我們支持各種數據集的三種類型的方案，並將通用數據集拆分代碼移動到./dataset/utils以便於擴展。如果您需要另一個數據集，只需編寫另一個代碼以下載它，然後使用utils。
對於標籤偏斜方案，我們介紹了16個著名數據集：
數據集可以很容易地分為IID和非IID版本。在非IID方案中，我們區分兩種類型的分佈：
病理非IID ：在這種情況下，每個客戶端僅包含標籤的一個子集，例如，即使整個數據集包含所有10個標籤，MNIST數據集的10個標籤中只有2個標籤中只有2個。這導致跨客戶的數據分佈高度偏斜。
實際非IID ：在這裡，我們使用Dirichlet分佈對數據分佈進行建模，從而導致更現實，更不平衡的失衡。有關此的更多詳細信息，請參閱本文。
此外，我們提供了一個balance選項，其中數據金額均勻分配到所有客戶端。
對於特徵偏移方案，我們在域適應中使用了3個廣泛使用的數據集：
對於實際情況，我們介紹了5個自然分離的數據集：
有關物聯網中數據集和FL算法的更多詳細信息，請參閱FL-IOT。
cd ./dataset
# python generate_MNIST.py iid - - # for iid and unbalanced scenario
# python generate_MNIST.py iid balance - # for iid and balanced scenario
# python generate_MNIST.py noniid - pat # for pathological noniid and unbalanced scenario
python generate_MNIST.py noniid - dir # for practical noniid and unbalanced scenario
# python generate_MNIST.py noniid - exdir # for Extended Dirichlet strategy 運行python generate_MNIST.py noniid - dir的命令行輸出
Number of classes: 10
Client 0 Size of data: 2630 Labels: [0 1 4 5 7 8 9]
Samples of labels: [(0, 140), (1, 890), (4, 1), (5, 319), (7, 29), (8, 1067), (9, 184)]
--------------------------------------------------
Client 1 Size of data: 499 Labels: [0 2 5 6 8 9]
Samples of labels: [(0, 5), (2, 27), (5, 19), (6, 335), (8, 6), (9, 107)]
--------------------------------------------------
Client 2 Size of data: 1630 Labels: [0 3 6 9]
Samples of labels: [(0, 3), (3, 143), (6, 1461), (9, 23)]
-------------------------------------------------- Client 3 Size of data: 2541 Labels: [0 4 7 8]
Samples of labels: [(0, 155), (4, 1), (7, 2381), (8, 4)]
--------------------------------------------------
Client 4 Size of data: 1917 Labels: [0 1 3 5 6 8 9]
Samples of labels: [(0, 71), (1, 13), (3, 207), (5, 1129), (6, 6), (8, 40), (9, 451)]
--------------------------------------------------
Client 5 Size of data: 6189 Labels: [1 3 4 8 9]
Samples of labels: [(1, 38), (3, 1), (4, 39), (8, 25), (9, 6086)]
--------------------------------------------------
Client 6 Size of data: 1256 Labels: [1 2 3 6 8 9]
Samples of labels: [(1, 873), (2, 176), (3, 46), (6, 42), (8, 13), (9, 106)]
--------------------------------------------------
Client 7 Size of data: 1269 Labels: [1 2 3 5 7 8]
Samples of labels: [(1, 21), (2, 5), (3, 11), (5, 787), (7, 4), (8, 441)]
--------------------------------------------------
Client 8 Size of data: 3600 Labels: [0 1]
Samples of labels: [(0, 1), (1, 3599)]
--------------------------------------------------
Client 9 Size of data: 4006 Labels: [0 1 2 4 6]
Samples of labels: [(0, 633), (1, 1997), (2, 89), (4, 519), (6, 768)]
--------------------------------------------------
Client 10 Size of data: 3116 Labels: [0 1 2 3 4 5]
Samples of labels: [(0, 920), (1, 2), (2, 1450), (3, 513), (4, 134), (5, 97)]
--------------------------------------------------
Client 11 Size of data: 3772 Labels: [2 3 5]
Samples of labels: [(2, 159), (3, 3055), (5, 558)]
--------------------------------------------------
Client 12 Size of data: 3613 Labels: [0 1 2 5]
Samples of labels: [(0, 8), (1, 180), (2, 3277), (5, 148)]
--------------------------------------------------
Client 13 Size of data: 2134 Labels: [1 2 4 5 7]
Samples of labels: [(1, 237), (2, 343), (4, 6), (5, 453), (7, 1095)]
--------------------------------------------------
Client 14 Size of data: 5730 Labels: [5 7]
Samples of labels: [(5, 2719), (7, 3011)]
--------------------------------------------------
Client 15 Size of data: 5448 Labels: [0 3 5 6 7 8]
Samples of labels: [(0, 31), (3, 1785), (5, 16), (6, 4), (7, 756), (8, 2856)]
--------------------------------------------------
Client 16 Size of data: 3628 Labels: [0]
Samples of labels: [(0, 3628)]
--------------------------------------------------
Client 17 Size of data: 5653 Labels: [1 2 3 4 5 7 8]
Samples of labels: [(1, 26), (2, 1463), (3, 1379), (4, 335), (5, 60), (7, 17), (8, 2373)]
--------------------------------------------------
Client 18 Size of data: 5266 Labels: [0 5 6]
Samples of labels: [(0, 998), (5, 8), (6, 4260)]
--------------------------------------------------
Client 19 Size of data: 6103 Labels: [0 1 2 3 4 9]
Samples of labels: [(0, 310), (1, 1), (2, 1), (3, 1), (4, 5789), (9, 1)]
--------------------------------------------------
Total number of samples: 70000
The number of train samples: [1972, 374, 1222, 1905, 1437, 4641, 942, 951, 2700, 3004, 2337, 2829, 2709, 1600, 4297, 4086, 2721, 4239, 3949, 4577]
The number of test samples: [658, 125, 408, 636, 480, 1548, 314, 318, 900, 1002, 779, 943, 904, 534, 1433, 1362, 907, 1414, 1317, 1526]
Saving to disk.
Finish generating dataset.
對於MNIST和時尚狂熱者
對於CIFAR10，CIFAR100和TININ-IMAGENET
對於ag_news和sogou_news
對於AmazonReview
對於全能
對於Har和Pamap
安裝CUDA。
安裝Conda最新並激活Conda。
有關其他配置，請參閱prepare.sh腳本。
conda env create -f env_cuda_latest.yaml # Downgrade torch via pip if needed to match the CUDA version 使用git下載此項目到適當的位置。
git clone https://github.com/TsingZ0/PFLlib.git創建適當的環境（請參閱環境）。
構建評估方案（請參閱數據集和方案（更新））。
運行評估：
cd ./system
python main.py -data MNIST -m CNN -algo FedAvg -gr 2000 -did 0 # using the MNIST dataset, the FedAvg algorithm, and the 4-layer CNN model注意：最好在使用新機器上使用任何算法之前調整算法特定的超參數。
該庫旨在通過新算法和數據集易於擴展。這是您可以添加它們的方法：
新數據集：要添加一個新數據集，只需在./dataset中創建一個generate_DATA.py文件，然後編寫下載代碼並使用utils，如./dataset/generate_MNIST.py （您可以將其視為模板）中所示）：
# `generate_DATA.py`
import necessary pkgs
from utils import necessary processing funcs
def generate_dataset (...):
# download dataset as usual
# pre-process dataset as usual
X , y , statistic = separate_data (( dataset_content , dataset_label ), ...)
train_data , test_data = split_data ( X , y )
save_file ( config_path , train_path , test_path , train_data , test_data , statistic , ...)
# call the generate_dataset func新算法：要添加新算法，擴展了基於./system/flcore/servers/serverbase.py and ./system/flcore/clients/clientbase.py中定義的基類服務器和客戶端。
# serverNAME.py
import necessary pkgs
from flcore . clients . clientNAME import clientNAME
from flcore . servers . serverbase import Server
class NAME ( Server ):
def __init__ ( self , args , times ):
super (). __init__ ( args , times )
# select slow clients
self . set_slow_clients ()
self . set_clients ( clientAVG )
def train ( self ):
# server scheduling code of your algorithm # clientNAME.py
import necessary pkgs
from flcore . clients . clientbase import Client
class clientNAME ( Client ):
def __init__ ( self , args , id , train_samples , test_samples , ** kwargs ):
super (). __init__ ( args , id , train_samples , test_samples , ** kwargs )
# add specific initialization
def train ( self ):
# client training code of your algorithm新模型：要添加新模型，只需將其包含在./system/flcore/trainmodel/models.py中。
新優化器：如果您需要新的優化器進行培訓，請將其添加到./system/flcore/optimizers/fedoptimizer.py中。
新的基準平台或庫：我們的框架很靈活，允許用戶為特定應用程序（例如FL-IOT和HTFLLIB）構建自定義平台或庫。
您可以使用以下隱私評估方法來評估PFLLIB中TFL/PFL算法的隱私功能。請參閱./system/flcore/servers/serveravg.py 。請注意，這些評估中的大多數通常在原始論文中不考慮。我們鼓勵您添加更多攻擊和指標以進行隱私評估。
為了在實際條件下模擬聯合學習（FL），例如客戶輟學，較慢的培訓器，緩慢的發送者和網絡TTL（live） ，您可以調整以下參數：
-cdr ：客戶的輟學率。根據此速度，在每個培訓回合中隨機放棄客戶。-tsr和-ssr ：分別較慢的培訓器和慢速發送方速率。這些參數定義了將以緩慢的培訓器或緩慢發件人的行為行為的客戶比例。一旦將客戶端選為“慢培訓師”或“慢速發送者”，它將始終如一地訓練/發送速度較慢。-tth ：毫秒中網絡TTL的閾值。多虧了@stonesjtu，該庫還可以為模型記錄GPU內存使用量。
如果您對上述算法的實驗結果感興趣（例如準確性） ，則可以在我們接受的FL論文中找到結果，該論文也利用了此庫。這些論文包括：
請注意，儘管這些結果基於此庫，但重現確切的結果可能具有挑戰性，因為某些設置可能會因社區反饋而改變。例如，在較早的版本中，我們將shuffle=False in clientbase.py中。
這是您的參考文檔：
@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}
}
