FL-bench

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

实现你的卓越创意。

享受联邦学习的乐趣。

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

</h4>

<a href=https://zhuanlan.zhihu.com/p/703576051>FL-bench 的简单介绍</a>

方法 🧬

<summary>传统联邦学习方法</summary>

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)

<summary>个性化联邦学习方法</summary>

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)

<summary>联邦学习领域泛化方法</summary>

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`

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

`tensorboard`

在终端运行tensorboard --logdir=<your_log_dir>。
在浏览器中查看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以获取完整详情。

参数	类型	描述
`--config-path`	`str`	配置文件所在目录。默认为`config`，表示`./config`。
`--config-name`	`str`	配置文件的名称（不包含`.yaml`扩展名）。默认为`defaults`，指向`config/defaults.yaml`。
`dataset`	`str`	实验运行的数据集名称。
`model`	`str`	实验使用的模型骨架。
`seed`	`int`	运行实验的随机种子。
`join_ratio`	`float`	（每轮参与的客户端数）/（总客户端数）的比率。
`global_epoch`	`int`	全局轮次，也称为通信轮次。
`local_epoch`	`int`	客户端本地训练的轮次。
`finetune_epoch`	`int`	客户端在测试前微调模型的轮次。
`buffers`	`str`	如何处理每个客户端模型的参数缓冲区（在`model.buffers()`中）。选项：[`local`, `global`, `drop`]。`local`（默认）：客户端的缓冲区是隔离的；`global`：缓冲区将像其他模型参数一样被聚合；`drop`：客户端在训练完成后会丢弃它们的缓冲区。
`test_interval`	`int`	对客户端执行测试的间隔轮次。
`eval_test`	`bool`	在本地训练前后对加入的客户端的测试集进行评估，设为`true`。
`eval_val`	`bool`	在本地训练前后对加入的客户端的验证集进行评估，设为`true`。
`eval_train`	`bool`	在本地训练前后对加入的客户端的训练集进行评估，设为`true`。
`optimizer`	`dict`	客户端优化器。参数要求与`torch.optim`中的优化器相同。
`lr_scheduler`	`dict`	客户端学习率调度器。参数要求与`torch.optim.lr_scheduler`中的调度器相同。
`verbose_gap`	`int`	在终端显示客户端训练性能的间隔轮次。
`batch_size`	`int`	客户端本地训练的数据批次大小。
`use_cuda`	`bool`	`true`表示张量在GPU上。
`visible`	`bool`	选项：[`null`, `visdom`, `tensorboard`]
`straggler_ratio`	`float`	落后者的比例（设置在`[0, 1]`范围内）。落后者不会像正常客户端那样执行完整轮次的本地训练。他们的本地轮次将随机从`[straggler_min_local_epoch, local_epoch)`范围内选择。
`straggler_min_local_epoch`	`int`	落后者的最小本地轮次值。
`external_model_params_file`	`str`	模型参数`.pt`文件相对于FL-bench根目录的路径。⚠ 此功能仅在`unique_model=False`时启用，这由每个联邦学习方法预定义。
`save_log`	`bool`	设为`true`以保存算法运行日志到`out/<method>/<start_time>`。
`save_model`	`bool`	设为`true`以保存输出模型参数到`out/<method>/<start_time>.pt`。
`save_fig`	`bool`	设为`true`以将Visdom上显示的准确率曲线保存为`.pdf`文件，保存在`out/<method>/<start_time>`。
`save_metrics`	`bool`	设为`true`以将指标统计保存为`.csv`文件，保存在`out/<method>/<start_time>`。
`delete_useless_run`	`bool`	设为`true`以在用户按下`Ctrl + C`后删除输出文件，表示该运行是可删除的。

并行训练参数 👯‍♂️

参数	类型	描述
`num_workers`	`int`	并行工作进程的数量。需要设置为大于`1`的整数。
`ray_cluster_addr`	`str`	选定Ray集群的IP地址。默认为`null`，这意味着如果没有现有的Ray集群，`ray`将在每次运行实验时建立一个新集群，并在结束时销毁它。更多详情可以在官方文档中找到。
`num_cpus`和`num_gpus`	`int`	你为Ray集群分配的计算资源数量。默认全部为`null`。

模型 🤖

这个基准支持许多常见的和集成在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}
}