KarhouTam/FL-bench
Benchmark of federated learning. Dedicated to the community. 🤗
什么是 FL‑bench？
FL‑bench 是一个用于**联邦学习（FL）**研究的开源基准测试套件。它提供了一个开箱即用的框架，让您可以在各种图像分类数据集上训练和评估数十种经典及最新的 FL 算法。代码围绕一个通用的服务器-客户端抽象进行组织，因此每种方法只需实现几个挂钩（hook），而可以复用大部分训练流程。
为何重要
- 快速实验 – 通过一个命令行标志即可在算法之间切换（如 FedAvg、FedProx、SCAFFOLD、pFedSim 等）。
- 可复现的设置 – 所有超参数都保存在 YAML 配置文件中；默认值有文档说明，并可通过命令行覆盖。
- 可扩展执行 – 内置对 Ray 并行训练的支持，无需额外代码即可进行多进程或多节点运行。
- 丰富的生态系统 – 包含许多标准视觉模型（ResNet、EfficientNet、MobileNet、LeNet5 等）以及各种数据集（MNIST、CIFAR‑10/100、FEMNIST、DomainNet、医学图像集等），并支持可配置的划分策略。
- 可扩展 – 可以通过继承提供的
FedAvgServer/FedAvgClient基类或扩展数据集/模型注册表来添加新的 FL 方法、模型或数据集。
快速开始（一行命令）
# 安装依赖
pip install -r .env/requirements.txt
# 为 100 个客户端生成合成 MNIST 划分
data/generate_data.py -d mnist -a 0.1 -cn 100
# 运行默认的 FedAvg 实验
python main.py method=fedavg
该命令从 config/defaults.yaml 读取默认配置，启动一个协调 100 个客户端的服务器，在划分的 MNIST 数据上训练 ResNet（或您选择的任何模型），并将指标记录到 TensorBoard 或 Visdom。
如何自定义
| 项目 | 方法 |
|---|---|
| 算法 | 在命令行中更改 method= 或编辑 YAML 文件（例如，method=fedprox fedprox.mu=0.01）。 |
| 超参数 | 通过命令行（optimizer.lr=0.1）、自定义配置文件或编辑方法的 get_hyperparams() 函数来覆盖任何参数。 |
| 模型 | 选择内置模型（model: resnet18）或在 src/utils/models.py 中创建 CustomModel 类，并用 model: custom 引用。 |
| 数据集/划分 | 从列表（MNIST、CIFAR‑10、DomainNet 等）中选择数据集和 data/README.md 中定义的划分策略。 |
| 并行性 | 在配置中设置 mode: parallel 和 parallel.num_workers；Ray 会自动启动工作进程。 |
| 监控 | 将 common.monitor 设置为 tensorboard 或 visdom，然后启动相应的服务器（tensorboard --logdir=… 或 python -m visdom.server）。 |
添加新的 FL 方法（开发者提示）
- 创建服务器和客户端类，继承自
FedAvgServer/FedAvgClient（或另一个现有方法，如果您需要其工具）。 - 根据需要覆盖以下任何挂钩：
package()– 服务器和客户端之间发送的参数。aggregate_client_updates()– 服务器上的自定义聚合逻辑。fit()、set_parameters()– 客户端训练调整。
- 注册新方法，在
src/server/下添加一个.py文件（文件名将成为命令行中使用的method名称）。 - 通过静态
get_hyperparams()暴露超参数，它返回一个argparse.Namespace– 这些可以在配置文件中设置。
许可证与引用
该项目以 GPL‑3.0 许可发布。如果您在论文中使用 FL‑bench，请引用提供的 BibTeX 条目：
@software{Tan_FL-bench,
author = {Tan, Jiahao and Wang, Xinpeng},
license = {GPL-3.0},
title = {{FL-bench: A federated learning benchmark for solving image classification tasks}},
url = {https://github.com/KarhouTam/FL-bench}
}
总结
FL‑bench 是一个实用、文档完善的平台，适合任何希望在真实图像数据上比较联邦学习算法、尝试个性化或域泛化扩展，以及使用 Ray 扩展运行规模的人。其模块化设计使得在保持实验可复现的同时，轻松集成新的方法、模型或数据集。
相关
- 项目
- 项目
- 项目
- 项目