联邦学习方法基准测试。

实现您的精彩想法。

与联邦学习一起玩得开心。

FL-bench 欢迎一切能让该项目变得更好的 Pull Request。

FL-bench 的简单介绍

方法 🧬

传统联邦学习方法

• FedAvg -- 来自去中心化数据的高效通信深度学习 (AISTATS'17)
• FedAvgM -- 衡量非独立同分布数据对联邦视觉分类的影响 (ArXiv'19)
• FedProx -- 异构网络中的联邦优化 (MLSys'20)
• SCAFFOLD -- SCAFFOLD：用于联邦学习的随机控制平均法 (ICML'20)
• MOON -- 基于模型对比的联邦学习 (CVPR'21)
• FedDyn -- 基于动态正则化的联邦学习 (ICLR'21)
• FedLC -- 通过 logits 校准处理标签分布偏斜的联邦学习 (ICML'22)
• FedGen -- 无数据知识蒸馏，适用于异构联邦学习 (ICML'21)
• CCVR -- 不怕异构性：针对非独立同分布数据的联邦学习分类器校准 (NeurIPS'21)
• FedOpt -- 自适应联邦优化 (ICLR'21)
• FedADMM -- FedADMM：一种鲁棒的联邦深度学习框架，可适应系统异构性 (ICDE'22)
• 弹性聚合 -- 用于联邦优化的弹性聚合 (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 -- 使用莫雷包络的个性化联邦学习 (NeurIPS'20)
• FedEM -- 混合分布下的联邦多任务学习 (NIPS'21)
• 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)
• FedALA -- FedALA: 个性化联邦学习中的自适应本地聚合 (AAAI'23)
• PeFLL -- PeFLL: 通过“学会学习”实现个性化联邦学习 (ICLR'24)
• FLUTE -- 欠参数化情形下的联邦表示学习 (ICML'24)
• FedAS -- FedAS: 弥合个性化联邦学习中的不一致性 (CVPR'24)
• pFedFDA -- pFedFDA: 通过特征分布自适应实现个性化联邦学习 (NeurIPS 2024)
• Floco -- 基于连接模式的联邦学习 (NeurIPS'24)
• FedAH -- FedAH: 个性化联邦学习的聚合头部 (ArXiv'24)

联邦学习领域泛化方法

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

差分隐私联邦学习方法

• DP-FedAvg -- 学习差分隐私的循环语言模型 (ICLR 2018)

环境准备 🧩

PyPI 🐍

pip install -r .env/requirements.txt

轻松运行 🏃‍♂️

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

第一步：生成联邦学习数据集

按照 Dir(0.1) 分配方式为 100 个客户端划分 MNIST 数据集

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

有关联邦数据集生成方法的详细信息，请参阅 data/README.md。

第二步：运行实验

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

• method: 算法名称，例如 method=fedavg。

[!注意] method 应与 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。
• 修改 config/defaults.yaml 中的默认值，或在 src/server/<method>.py 的 get_hyperparams() 函数中进行修改。

[!NOTE] 对于同一个 FL 方法参数，参数设置的优先级是 命令行 > 配置文件 > 默认值。

例如，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
python main.py --config-name your_config method=fedprox fedprox.mu=0.001 # fedprox.mu = 0.001

监控 📈

FL-bench 支持 visdom 和 tensorboard。

激活

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

[!NOTE] 你需要自行启动 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 集群。

[!TIP] 你可以通过以下命令手动创建集群，以避免每次运行实验时都创建和销毁集群：

ray start --head [OPTIONS]

[!NOTE] 为了连接到现有的 Ray 集群，你需要在配置文件中保持 num_cpus: null 和 num_gpus: null。

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

参数 🔧

FL-bench 强烈推荐通过配置文件来定制你的 FL 方法和实验设置。

FL-bench 提供了一个默认配置文件 config/defaults.yaml，其中包含了所有必需的参数及相应的注释。

所有通用参数都有其默认值。请查看 config/defaults.yaml 或 src/utils/constants.py 中的 DEFAULTS 来了解所有参数的默认值。

[!NOTE] 如果你的自定义配置文件中没有包含所有必需的参数，FL-bench 会用从 DEFAULTS 加载的默认值来填补缺失的参数。

关于特定 FL 方法参数的默认值，请查看对应的 src/server/<method>.py 文件以获取详细信息。

[!TIP] FL-bench 也支持通过命令行参数进行快速更改。以下是一些示例：

# 使用 config/defaults.yaml，但将方法改为 FedProx，并将其 mu 设置为 0.1。
python main.py method=fedprox fedprox.mu=0.1

# 将学习率改为 0.1。
python main.py optimizer.lr=0.1

# 将批量大小改为 128。
python main.py common.batch_size=128

模型 🤖

该基准测试支持大量常见且集成在 Torchvision 中的模型（所有模型请参见 src/utils/models.py）：

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

[!TIP] 你可以通过填充 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 类)

自定义提示 💡

实现 FL 方法

服务器端类中的 package() 方法用于组装服务器需要发送给客户端的所有参数。同样，客户端端类中的 package() 方法用于封装客户端需要返回给服务器的参数。在重写实现时，务必保留 super().package()。

• 建议让你的方法类继承自 FedAvgServer 和 FedAvgClient，以便最大限度地利用 FL-bench 的工作流程。

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

class YourServer(FedBNServer):
  ...

class YourClient(FedBNClient):
  ...

• 若要自定义服务器端流程，可以考虑重写 package() 和 aggregate_client_updates() 方法。

• 若要自定义客户端训练过程，可以考虑重写 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 = {GPL-3.0},
  title = {{FL-bench: 用于解决图像分类任务的联邦学习基准}},
  url = {https://github.com/KarhouTam/FL-bench}
}

@misc{tan2023pfedsim,
  title={pFedSim：面向个性化联邦学习的相似性感知模型聚合}, 
  author={Jiahao Tan 和 Yipeng Zhou 和 Gang Liu 和 Jessie Hui Wang 和 Shui Yu},
  year={2023},
  eprint={2305.15706},
  archivePrefix={arXiv},
  primaryClass={cs.LG}
}

FL-bench 快速上手指南

FL-bench 是一个用于基准测试联邦学习（Federated Learning, FL）方法的开源框架，支持传统 FL、个性化 FL、域泛化及差分隐私等多种算法。

环境准备

系统要求

• 操作系统: Linux / macOS / Windows
• Python: 建议 Python 3.8+
• 依赖管理: pip

前置依赖

本项目主要依赖 PyTorch 生态及相关科学计算库。请确保已安装基础开发环境。

安装步骤

1. 克隆仓库（如果尚未克隆）：

   git clone https://github.com/KarhouTam/FL-bench.git
   cd FL-bench
   

2. 安装 Python 依赖： 推荐使用国内镜像源加速安装（如清华源）：

   pip install -r .env/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

基本使用

FL-bench 的工作流主要分为两步：生成数据集 和 运行实验。所有算法均继承自 FedAvgServer 和 FedAvgClient。

第一步：生成分布式数据集

以将 MNIST 数据集按 Dirichlet 分布 (alpha=0.1) 划分给 100 个客户端为例：

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

提示: 更多数据生成策略（如 CIFAR-10, Shakespeare 等）请参考 data/README.md。

第二步：运行实验

使用 main.py 启动训练。默认配置下运行 FedAvg 算法：

python main.py method=fedavg

参数说明

• method: 算法名称，必须与 src/server/ 目录下的 .py 文件名一致（例如 fedprox, scaffold）。
• --config-name: 指定配置文件名（不含 .yaml 后缀），默认为 defaults。
• --config-path: 配置文件所在相对路径，默认为 config。

自定义超参数

你可以通过命令行直接覆盖默认参数，优先级顺序为：命令行 > 配置文件 > 代码默认值。

示例：运行 FedProx 并将正则化参数 mu 设为 0.01：

python main.py --config-name defaults method=fedprox fedprox.mu=0.01

可选：开启可视化监控

FL-bench 支持 tensorboard 和 visdom。

1. 修改配置 (config/your_config.yaml)：

   common:
     monitor: tensorboard # 可选: null, visdom, tensorboard
   

2. 启动监控服务（需在单独终端运行）：

   • TensorBoard:

     tensorboard --logdir=<your_log_dir>
     

     浏览器访问：localhost:6006

   • Visdom:

     python -m visdom.server
     

     浏览器访问：localhost:8097

进阶：并行加速 (Ray)

若需大幅提升训练效率，可启用 Ray 并行模式。只需在配置文件中设置：

mode: parallel
parallel:
  num_workers: 2 # 设置为大于 1 的正整数

框架会自动处理 Ray 集群的创建与管理，无需额外操作。