FL-bench

对联邦学习方法进行基准测试。

实现你的卓越创意。

享受联邦学习的乐趣。

FL-bench欢迎各种能够改进这个项目的PR。

FL-bench 的简单介绍

方法 🧬

• FedAvg -- 基于分散数据的深度网络通信高效学习 (AISTATS'17)
• FedAvgM -- 测量非同质数据分布对联邦视觉分类的影响 (ArXiv'19)
• FedProx -- 异构网络中的联邦优化 (MLSys'20)
• SCAFFOLD -- SCAFFOLD：联邦学习的随机控制平均 (ICML'20)
• MOON -- 模型对比联邦学习 (CVPR'21)
• FedDyn -- 基于动态正则化的联邦学习 (ICLR'21)
• FedLC -- 通过逻辑校准解决标签分布偏斜的联邦学习 (ICML'22)
• FedGen -- 异构联邦学习的无数据知识蒸馏 (ICML'21)
• CCVR -- 不惧异质性：非独立同分布数据联邦学习的分类器校准 (NeurIPS'21)
• FedOpt -- 自适应联邦优化 (ICLR'21)
• 弹性聚合 -- 联邦优化的弹性聚合 (CVPR'23)
• FedFed -- FedFed：对抗联邦学习中数据异质性的特征蒸馏 (NeurIPS'23)

• pFedSim (我的工作⭐) -- pFedSim：基于相似性的模型聚合实现个性化联邦学习 (ArXiv'23)
• 仅本地 -- 仅本地训练（无通信）。
• FedMD -- FedMD：通过模型蒸馏实现异构联邦学习 (NeurIPS'19)
• APFL -- 自适应个性化联邦学习 (ArXiv'20)
• LG-FedAvg -- 思考本地，行动全球：具有本地和全局表示的联邦学习 (ArXiv'20)
• FedBN -- FedBN：通过本地批量归一化实现非独立同分布特征的联邦学习 (ICLR'21)
• FedPer -- 具有个性化层的联邦学习 (AISTATS'20)
• FedRep -- 利用共享表示实现个性化联邦学习 (ICML'21)
• Per-FedAvg -- 具有理论保证的个性化联邦学习：模型无关元学习方法 (NeurIPS'20)
• pFedMe -- 基于Moreau包络的个性化联邦学习 (NeurIPS'20)
• Ditto -- Ditto：通过个性化实现公平和鲁棒的联邦学习 (ICML'21)
• pFedHN -- 使用超网络的个性化联邦学习 (ICML'21)
• pFedLA -- 个性化联邦学习的分层模型聚合 (CVPR'22)
• CFL -- 聚类联邦学习：隐私约束下的模型无关分布式多任务优化 (ArXiv'19)
• FedFomo -- 基于一阶模型优化的个性化联邦学习 (ICLR'21)
• FedBabu -- FedBabu：增强联邦图像分类的表示 (ICLR'22)
• FedAP -- 使用自适应批量归一化的医疗保健个性化联邦学习 (IEEE'22)
• kNN-Per -- 通过本地记忆实现个性化联邦学习 (ICML'22)
• MetaFed -- MetaFed：联邦间的联邦学习与循环知识蒸馏用于个性化医疗保健 (IJCAI'22)
• FedRoD -- 桥接通用和个性化联邦学习用于图像分类 (ICLR'22)
• FedProto -- FedProto：异构客户端间的联邦原型学习 (AAAI'22)
• FedPAC -- 通过特征对齐和分类器协作实现个性化联邦学习 (ICLR'23)
• PeFLL -- PeFLL：通过学习来学习实现个性化联邦学习 (ICLR'24)
• FLUTE -- 欠参数化情况下的联邦表示学习 (ICML'24)

• FedSR -- FedSR：一种简单有效的联邦学习领域泛化方法 (NeurIPS'22)
• ADCOL -- 非独立同分布特征上的对抗性协作学习 (ICML'23)
• FedIIR -- 通过隐式不变关系实现联邦学习的分布外泛化 (ICML'23)

环境准备 🧩

PyPI 🐍

pip install -r .environment/requirements.txt

Poetry 🎶

对于中国大陆用户

poetry install --no-root -C .environment

对于其他用户

cd .environment && sed -i "10,14d" pyproject.toml && poetry lock --no-update && poetry install --no-root

Docker 🐳

对于中国大陆用户

docker pull registry.cn-hangzhou.aliyuncs.com/karhoutam/fl-bench:master

对于其他用户

docker pull ghcr.io/karhoutam/fl-bench:master

构建容器的示例

docker run -it --name fl-bench -v path/to/FL-bench:/root/FL-bench --privileged --gpus all ghcr.io/karhoutam/fl-bench:master

快速运行 🏃‍♂️

所有方法类都继承自FedAvgServer和FedAvgClient。如果你想了解整个工作流程和变量设置的详细信息，请查看src/server/fedavg.py和src/client/fedavg.py。

步骤1. 生成联邦学习数据集

根据Dir(0.1)将MNIST数据集划分给100个客户端

python generate_data.py -d mnist -a 0.1 -cn 100

关于生成联邦数据集的方法，请查看data/README.md获取完整详情。

步骤2. 运行实验

python main.py [--config-path, --config-name] [method=<方法名> args...]

• method: 算法名称，例如method=fedavg。❗ 方法名应与src/server中的.py文件名相同。
• --config-path: 配置文件所在目录的相对路径。默认为config。
• --config-name: .yaml配置文件的名称（不包含.yaml扩展名）。默认为defaults，指向config/defaults.yaml。

例如，使用所有默认设置运行FedAvg：

python main.py method=fedavg

默认值在config/defaults.yaml和src/utils/constants.py中设置。

如何自定义联邦学习方法参数 🤖

• 通过修改配置文件
• 通过在命令行中显式设置，例如python main.py --config-name my_cfg.yaml method=fedprox fedprox.mu=0.01。
• 通过修改src/utils/constants.py/DEFAULT_COMMON_ARGS或方法的get_hyperparams()中的默认值

⚠ 对于相同的联邦学习方法参数，参数设置的优先级为命令行 > 配置文件 > 默认值。

例如，fedprox.mu的默认值为1，

# src/server/fedprox.py
class FedProxServer(FedAvgServer):

    @staticmethod
    def get_hyperparams(args_list=None) -> Namespace:
        parser = ArgumentParser()
        parser.add_argument("--mu", type=float, default=1.0)
        return parser.parse_args(args_list)

而你的.yaml配置文件有

# config/your_config.yaml
...
fedprox:
  mu: 0.01

python main.py method=fedprox                                  # fedprox.mu = 1
python main.py --config-name your_config method=fedprox        # fedprox.mu = 0.01

监控 📈

FL-bench支持visdom和tensorboard。

激活

👀 注意： 你需要自行启动visdom / tensorboard服务器。

# your_config.yaml
common:
  ...
  visible: tensorboard # 选项：[null, visdom, tensorboard]

启动visdom / tensorboard服务器

visdom

1. 在终端运行python -m visdom.server。
2. 在浏览器中查看localhost:8097。

tensorboard

1. 在终端运行tensorboard --logdir=<your_log_dir>。
2. 在浏览器中查看localhost:6006。

通过Ray进行并行训练 🚀

这个功能可以大大提高你的训练效率。同时，这个功能对用户友好且易于使用！！！

激活（你唯一需要做的）

# your_config.yaml
mode: parallel
parallel:
  num_workers: 2 # 任何大于1的正整数
  ...
...

手动创建Ray集群（可选）

每次以并行模式运行实验时，都会隐式创建一个Ray集群。 或者你可以通过下面显示的命令手动创建它，以避免每次运行实验时创建和销毁集群。

ray start --head [选项]

👀 注意： 要连接到现有的Ray集群，你需要在配置文件中保持num_cpus: null和num_gpus: null。

# your_config_file.yaml
# 连接到本地现有的Ray集群。
mode: parallel
parallel:
  ...
  num_gpus: null
  num_cpus: null
...

通用参数 🔧

所有通用参数都有默认值。查看src/utils/constants.py中的DEFAULT_COMMON_ARGS以获取通用参数的完整详情。

⚠ 通用参数不能通过命令行设置。

你也可以编写自己的.yaml配置文件。我在config中为你提供了一个模板，并建议你也将配置文件保存在那里。

一个例子：python main.py fedavg config/template.yaml [cli_method_args...]

关于特定联邦学习方法参数的默认值，请查看相应的FL-bench/src/server/<method>.py以获取完整详情。

并行训练参数 👯‍♂️

模型 🤖

这个基准支持许多常见的和集成在Torchvision中的模型（查看这里获取所有模型）：

• ResNet系列
• EfficientNet系列
• DenseNet系列
• MobileNet系列
• LeNet5
• ...

🤗 你可以通过填写src/utils/models.py中的CustomModel类来定义自己的自定义模型，并通过在.yaml配置文件中定义model: custom来使用它。

数据集和分区策略 🎨

常规图像数据集

• MNIST (1 x 28 x 28, 10类)

• CIFAR-10/100 (3 x 32 x 32, 10/100类)

• EMNIST (1 x 28 x 28, 62类)

• FashionMNIST (1 x 28 x 28, 10类)

• 合成数据集

• FEMNIST (1 x 28 x 28, 62类)

• CelebA (3 x 218 x 178, 2类)

• SVHN (3 x 32 x 32, 10类)

• USPS（1 x 16 x 16，10类）

• Tiny-ImageNet-200（3 x 64 x 64，200类）

• CINIC-10（3 x 32 x 32，10类）

领域泛化图像数据集

• DomainNet（3 x ? x ?，345类）
  • 请查看data/README.md获取完整的处理指南 🧾。

医学图像数据集

• COVID-19（3 x 244 x 224，4类）

• Organ-S/A/CMNIST（1 x 28 x 28，11类）

自定义技巧 💡

实现联邦学习方法

服务器端类中的package()用于组装服务器需要发送给客户端的所有参数。类似地，客户端类中的package()用于客户端需要发送回服务器的参数。在你的重写实现中，应始终包含super().package()。

• 考虑从FedAvgServer和FedAvgClient继承你的方法类，以最大程度地利用FL-bench的工作流程。

• 你也可以从高级方法继承你的方法类，例如FedBN、FedProx等。这将继承所有函数、变量和超参数设置。如果这样做，你需要谨慎设计你的方法，以避免潜在的超参数和工作流程冲突。

class YourServer(FedBNServer):
  ...

class YourClient(FedBNClient):
  ...

• 要自定义服务器端处理，考虑重写package()和aggregate()。

• 要自定义客户端训练，考虑重写fit()、set_parameters()和package()。

你可以在FedAvgClient和FedAvgServer中找到所有细节，它们是FL-bench中所有实现的基础。

集成数据集

• 从data/utils/datasets.py中的BaseDataset继承你自己的数据集类，并将你的类添加到字典DATASETS中。

自定义模型

• 我提供了src/utils/models.py中的CustomModel类，你只需定义你的模型架构即可。
• 如果你想在FL-bench的工作流程中使用你的自定义模型，必须定义base和classifier。（提示：你可以将其中一个定义为torch.nn.Identity()以绕过它。）

引用 🧐

@software{Tan_FL-bench,
  author = {Tan, Jiahao and Wang, Xinpeng},
  license = {MIT},
  title = {{FL-bench: A federated learning benchmark for solving image classification tasks}},
  url = {https://github.com/KarhouTam/FL-bench}
}

@misc{tan2023pfedsim,
  title={pFedSim: Similarity-Aware Model Aggregation Towards Personalized Federated Learning}, 
  author={Jiahao Tan and Yipeng Zhou and Gang Liu and Jessie Hui Wang and Shui Yu},
  year={2023},
  eprint={2305.15706},
  archivePrefix={arXiv},
  primaryClass={cs.LG}
}