FederatedScope 是一个全面的联邦学习平台，为学术界和工业界的各类联邦学习任务提供便捷的使用方式和灵活的定制能力。基于事件驱动架构，FederatedScope 集成了丰富的功能模块，以满足联邦学习领域日益增长的需求，并致力于打造一个易于使用的平台，推动安全、高效的联邦学习实践。

详细的教程请访问我们的官网：federatedscope.io

您可以通过 FederatedScope Playground 或 Google Colab 体验 FederatedScope。

| 代码结构 | 快速入门 | 进阶指南 | 文档 | 相关论文 | 贡献指南 |

新闻

• [2023年5月17日] 我们的论文 FS-REAL 已被 KDD'2023 接受！
• [2023年5月17日] 我们关于 FL 后门攻击的基准研究论文 Backdoor Attacks Bench 已被 KDD'2023 接受！
• [2023年5月17日] 我们的论文 分布式环境下的通信高效且差分隐私逻辑回归 已被 KDD'2023 接受！
• [2023年4月25日] 我们的论文 pFedGate 已被 ICML'2023 接受！
• [2023年4月25日] 我们关于 FedHPO 的基准研究论文 FedHPO-Bench 已被 ICML'2023 接受！
• [2023年4月3日] 我们发布了 FederatedScope v0.3.0！
• [2022年2月10日] 我们阐述 FederatedScope 的论文 论文 被 VLDB'23 接受！
• [2022年10月5日] 我们关于个性化联邦学习的基准研究论文 pFL-Bench 被 NeurIPS'22 数据集与基准赛道接受！
• [2022年8月18日] 我们在 KDD 2022 上发表的关于联邦图学习的论文 论文 获得了 ADS 赛道的最佳论文奖！
• [2022年7月30日] 我们发布了 FederatedScope v0.2.0！
• [2022年6月17日] 我们发布了 pFL-Bench，这是一个针对个性化联邦学习（pFL）的综合性基准，包含 10 多个数据集和 20 多个基线。[代码, pdf]
• [2022年6月17日] 我们发布了 FedHPO-Bench，一套用于研究联邦超参数优化的基准工具。[代码, pdf]
• [2022年6月17日] 我们发布了 B-FHTL，一套用于研究联邦异构任务学习的基准工具。[代码, pdf]
• [2022年6月13日] 我们的项目曾遭受攻击，现已解决。详情.
• [2022年5月25日] 我们的论文 FederatedScope-GNN 已被 KDD'2022 接受！
• [2022年5月6日] 我们发布了 FederatedScope v0.1.0！

代码结构

FederatedScope
├── federatedscope
│   ├── core           
│   |   ├── workers              # 参与者的具体行为（即服务器和客户端）
│   |   ├── trainers             # 本地训练的详细实现
│   |   ├── aggregators          # 联邦聚合的具体实现
│   |   ├── configs              # 可配置的参数设置
│   |   ├── monitors             # 日志记录与可视化模块
│   |   ├── communication.py     # 参与者之间的通信实现   
│   |   ├── fed_runner.py        # 用于构建和运行联邦学习流程的主程序
│   |   ├── ... ..
│   ├── cv                       # 计算机视觉领域的联邦学习        
│   ├── nlp                      # 自然语言处理领域的联邦学习          
│   ├── gfl                      # 图联邦学习          
│   ├── autotune                 # 联邦学习中的自动调参         
│   ├── vertical_fl              # 垂直联邦学习         
│   ├── contrib                          
│   ├── main.py           
│   ├── ... ...          
├── scripts                      # 用于复现现有算法的脚本
├── benchmark                    # 我们发布了一些基准，便于公平比较
├── doc                          # 用于自动生成文档
├── environment                  # 安装要求及提供的 Docker 文件
├── materials                    # 相关主题的资料（如论文列表）
│   ├── notebook                        
│   ├── paper_list                                        
│   ├── tutorial                                       
│   ├── ... ...                                      
├── tests                        # 用于持续集成的单元测试模块
├── LICENSE
└── setup.py

快速入门

我们提供了一个端到端的示例，帮助用户使用 FederatedScope 开始运行一个标准的联邦学习流程。

第1步：安装

首先，用户需要克隆源代码并安装所需的软件包（建议使用Python 3.9及以上版本）。您可以选择以下两种安装方式（通过Docker或Conda）来安装FederatedScope。

git clone https://github.com/alibaba/FederatedScope.git
cd FederatedScope

使用 Docker

您可以构建Docker镜像，并在带有CUDA 11和PyTorch 1.10的Docker环境中运行：

docker build -f environment/docker_files/federatedscope-torch1.10.Dockerfile -t alibaba/federatedscope:base-env-torch1.10 .
docker run --gpus device=all --rm -it --name "fedscope" -w $(pwd) alibaba/federatedscope:base-env-torch1.10 /bin/bash

如果您需要运行下游任务，例如图联邦学习，在执行上述命令时，请将依赖文件和Docker文件名更改为相应的文件：

# environment/requirements-torch1.10.txt -> 
environment/requirements-torch1.10-application.txt

# environment/docker_files/federatedscope-torch1.10.Dockerfile ->
environment/docker_files/federatedscope-torch1.10-application.Dockerfile

注意：您可以通过将torch1.10替换为torch1.8来选择使用CUDA 10和PyTorch 1.8。这些Docker镜像基于nvidia-docker。请提前在宿主机上安装NVIDIA驱动程序和nvidia-docker2。更多详细信息请参阅此处。

使用 Conda

我们建议使用一个新的虚拟环境来安装FederatedScope：

conda create -n fs python=3.9
conda activate fs

如果您的后端是PyTorch，请提前安装PyTorch（PyTorch入门）。例如，如果您的CUDA版本是11.3，请执行以下命令：

conda install -y pytorch=1.10.1 torchvision=0.11.2 torchaudio=0.10.1 torchtext=0.11.1 cudatoolkit=11.3 -c pytorch -c conda-forge

对于配备Apple M1芯片的用户：

conda install pytorch torchvision torchaudio -c pytorch
# 降级torchvision以避免段错误
python -m pip install torchvision==0.11.3

最后，在安装好后端之后，您可以从源代码安装FederatedScope：

从源代码安装

# 可编辑模式
pip install -e .

# 或者（开发者用于开发模式）
pip install -e .[dev]
pre-commit install

现在，您已成功安装了FederatedScope的最小版本。（可选）对于包含图、NLP和语音等应用的版本，请运行：

bash environment/extra_dependencies_torch1.10-application.sh

第2步：准备数据集

要运行一个联邦学习任务，用户需要准备一个数据集。FederatedScope提供的DataZoo可以帮助自动下载和预处理广泛使用的公共数据集，适用于各种联邦学习应用场景，包括计算机视觉、自然语言处理、图学习、推荐系统等。用户可以直接在配置中指定cfg.data.type = DATASET_NAME。例如：

cfg.data.type = 'femnist'

如果要使用自定义数据集，您需要按照特定格式准备数据集并进行注册。更多详情请参阅自定义数据集。

第3步：准备模型

接下来，用户应指定将在联邦学习过程中训练的模型架构。FederatedScope提供了一个ModelZoo，其中包含了各种联邦学习应用中广泛采用的模型架构实现。用户可以通过设置cfg.model.type = MODEL_NAME来在联邦学习任务中应用特定的模型架构。例如：

cfg.model.type = 'convnet2'

FederatedScope还允许用户通过注册的方式使用自定义模型。有关如何自定义模型架构的更多信息，请参阅自定义模型。

第4步：开始运行联邦学习任务

请注意，FederatedScope同时支持单机模式和分布式模式，并且用户可以通过配置轻松切换。

单机模式

FederatedScope中的单机模式是指在一台设备上模拟多个参与者（服务器和客户端），参与者的数据彼此隔离，但他们的模型可以通过消息传递共享。

下面我们演示如何使用FederatedScope运行一个标准的联邦学习任务，设置cfg.data.type = 'FEMNIST'和cfg.model.type = 'ConvNet2'，以运行针对图像分类任务的Vanilla FedAvg算法。用户可以在配置文件（.yaml文件）中自定义训练参数，如cfg.federated.total_round_num、cfg.dataloader.batch_size和cfg.train.optimizer.lr，然后按如下方式运行标准联邦学习任务：

# 使用默认配置运行
python federatedscope/main.py --cfg scripts/example_configs/femnist.yaml

# 或者使用自定义配置
python federatedscope/main.py --cfg scripts/example_configs/femnist.yaml federate.total_round_num 50 dataloader.batch_size 128

然后，您可以在训练过程中观察到一些监控指标，如下所示：

INFO: 服务器已启动 ...
INFO: 模型元信息：`<class 'federatedscope.cv.model.cnn.ConvNet2'>`。
... ...
INFO: 客户端已启动 ...
INFO: 模型元信息：`<class 'federatedscope.cv.model.cnn.ConvNet2'>`。
... ...
INFO: {'角色': '客户端 #5', '轮次': 0, '原始结果': {'train_loss': 207.6341676712036, 'train_acc': 0.02, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.152683353424072}}
INFO: {'角色': '客户端 #1', '轮次': 0, '原始结果': {'train_loss': 209.0940284729004, 'train_acc': 0.02, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.1818805694580075}}
INFO: {'角色': '客户端 #8', '轮次': 0, '原始结果': {'train_loss': 202.24929332733154, 'train_acc': 0.04, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.0449858665466305}}
INFO: {'角色': '客户端 #6', '轮次': 0, '原始结果': {'train_loss': 209.43883895874023, 'train_acc': 0.06, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.1887767791748045}}
INFO: {'角色': '客户端 #9', '轮次': 0, '原始结果': {'train_loss': 208.83140087127686, 'train_acc': 0.0, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.1766280174255375}}
INFO: ----------- 开始新一轮训练（第1轮） -------------
... ...
INFO: 服务器：训练结束！开始评估。
INFO: 客户端 #1：（第20轮测试集评估）test_loss 为 163.029045
... ...
INFO: 服务器：最终评估结束！开始合并结果。
... ...

分布式模式

FederatedScope 中的分布式模式是指通过运行多个进程来构建一个联邦学习流程，其中每个进程充当参与者（服务器或客户端），实例化其模型并加载数据。参与者之间的通信已经由 FederatedScope 的通信模块提供。

要以分布式模式运行，您只需：

• 为每个参与者准备独立的数据文件，并设置 cfg.data.file_path = PATH/TO/DATA；
• 将 cfg.federate.model = 'distributed'，并通过 cfg.distributed.role = 'server'/'client' 指定每个参与者的角色；
• 通过 cfg.distribute.server_host/client_host = x.x.x.x 和 cfg.distribute.server_port/client_port = xxxx 设置有效的地址。（请注意，对于服务器，您需要设置 server_host 和 server_port 来监听消息；而对于客户端，除了需要设置用于监听的 client_host 和 client_port 外，还需要设置用于加入联邦学习流程的 server_host 和 server_port）

我们准备了一个使用分布式模式运行的合成示例：

# 对于服务器
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_server.yaml data.file_path 'PATH/TO/DATA' distribute.server_host x.x.x.x distribute.server_port xxxx

# 对于客户端
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_client_1.yaml data.file_path 'PATH/TO/DATA' distribute.server_host x.x.x.x distribute.server_port xxxx distribute.client_host x.x.x.x distribute.client_port xxxx
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_client_2.yaml data.file_path 'PATH/TO/DATA' distribute.server_host x.x.x.x distribute.server_port xxxx distribute.client_host x.x.x.x distribute.client_port xxxx
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_client_3.yaml data.file_path 'PATH/TO/DATA' distribute.server_host x.x.x.x distribute.server_port xxxx distribute.client_host x.x.x.x distribute.client_port xxxx

使用生成的玩具数据的可执行示例可以这样运行（脚本可在 scripts/run_distributed_lr.sh 中找到）：

# 生成玩具数据
python scripts/distributed_scripts/gen_data.py

# 首先启动等待客户端加入的服务器
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_server.yaml data.file_path toy_data/server_data distribute.server_host 127.0.0.1 distribute.server_port 50051

# 启动客户端 #1（通过另一个进程）
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_client_1.yaml data.file_path toy_data/client_1_data distribute.server_host 127.0.0.1 distribute.server_port 50051 distribute.client_host 127.0.0.1 distribute.client_port 50052
# 启动客户端 #2（通过另一个进程）
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_client_2.yaml data.file_path toy_data/client_2_data distribute.server_host 127.0.0.1 distribute.server_port 50051 distribute.client_host 127.0.0.1 distribute.client_port 50053
# 启动客户端 #3（通过另一个进程）
python federatedscope/main.py --cfg scripts/distributed_scripts/distributed_configs/distributed_client_3.yaml data.file_path toy_data/client_3_data distribute.server_host 127.0.0.1 distribute.server_port 50051 distribute.client_host 127.0.0.1 distribute.client_port 50054

您可以观察到以下结果（IP 地址已用 'x.x.x.x' 匿名化）：

INFO: 服务器：正在监听 x.x.x.x:xxxx...
INFO: 服务器已启动 ...
模型元信息：`<class 'federatedscope.core.lr.LogisticRegression'>`。
... ...
INFO: 客户端：正在监听 x.x.x.x:xxxx...
INFO: 客户端（地址 x.x.x.x:xxxx）已启动 ...
客户端（地址 x.x.x.x:xxxx）被分配为 #1。
INFO: 模型元信息：`<class 'federatedscope.core.lr.LogisticRegression'>`。
... ...
{'角色': '客户端 #2', '轮次': 0, '原始结果': {'train_avg_loss': 5.215108394622803, 'train_loss': 333.7669372558594, 'train_total': 64}}
{'角色': '客户端 #1', '轮次': 0, '原始结果': {'train_total': 64, 'train_loss': 290.9668884277344, 'train_avg_loss': 4.54635763168335}}
----------- 开始新一轮训练（第1轮） -------------
... ...
INFO: 服务器：训练结束！开始评估。
INFO: 客户端 #1：（第20轮测试集评估）test_loss 为 30.387419
... ...
INFO: 服务器：最终评估结束！开始合并结果。
... ...

高级功能

作为一款全面的联邦学习平台，FederatedScope 提供了支持各类联邦学习应用及前沿研究需求的基础实现，在易用性和灵活性扩展方面均表现出色，具体包括：

• 个性化联邦学习：通过为不同客户端定制模型架构和训练配置，有效应对由数据分布不独立同分布（non-IID）及系统资源异构性带来的挑战。
• 联邦超参数优化：在联邦学习场景下进行超参数优化（HPO）时，由于需要跨参与方进行多轮通信，每次尝试的成本极高。值得注意的是，联邦学习环境下的超参数优化具有独特性，亟需推广低精度 HPO 等技术。
• 隐私攻击者：隐私攻击算法是验证联邦学习系统与算法隐私保护强度的重要工具，随着联邦学习的发展，其重要性日益凸显。
• 图联邦学习：针对无处不在的图数据，图联邦学习旨在利用分散的子图数据联合学习全局模型，近年来受到广泛关注。
• 推荐系统：随着全球范围内一系列法律法规的实施，隐私保护的重要性愈发受到重视，这促使推荐系统必须以隐私友好的方式从用户数据中学习。
• 差分隐私：与需要大量计算资源的加密算法不同，差分隐私是一种经济高效且灵活的隐私保护技术，在数据库领域已取得显著成效，并在联邦学习中不断发展壮大。
• …

更多支持即将推出！我们准备了一份教程，详细介绍如何使用 FederatedScope 开启您的联邦学习之旅！

相关主题资料正在持续更新，请参阅 FL-Recommendation、Federated-HPO、Personalized FL、Federated Graph Learning、FL-NLP、FL-Attacker、FL-Incentive-Mechanism、FL-Fairness 等。

文档

FederatedScope 的类和方法均已完善文档化，用户可通过以下步骤生成 API 参考文档：

cd doc
pip install -r requirements.txt
make html

注意：

• doc/requirements.txt 仅用于通过 Sphinx 生成 API 文档，该过程可由 GitHub Actions 中的 .github/workflows/sphinx.yml 自动触发。（标题中包含 DOC 时会触发构建。）
• 文档也可通过 GitHub Actions 中的 Artifacts 下载。

我们已将 API 参考文档部署至我们的官网。

此外，我们还提供了可执行脚本和可定制配置的相关文档。

许可证

FederatedScope 采用 Apache License 2.0 许可协议发布。

出版物

如果您在研究或开发中使用了 FederatedScope，请引用以下论文：论文：

@article{federatedscope,
  title = {FederatedScope: A Flexible Federated Learning Platform for Heterogeneity},
  author = {Xie, Yuexiang and Wang, Zhen and Gao, Dawei and Chen, Daoyuan and Yao, Liuyi and Kuang, Weirui and Li, Yaliang and Ding, Bolin and Zhou, Jingren},
  journal={Proceedings of the VLDB Endowment},
  volume={16},
  number={5},
  pages={1059--1072},
  year={2023}
}

更多出版物请访问FederatedScope 出版物页面。

贡献

我们非常欢迎对 FederatedScope 的任何贡献！我们提供开发者版本的 FederatedScope，其中包含额外的 pre-commit 钩子，用于比官方版本更严格的提交检查：

# 安装开发者版本
pip install -e .[dev]
pre-commit install

# 或从官方版本切换到开发者版本
pip install pre-commit
pre-commit install
pre-commit run --all-files

更多详情请参阅FederatedScope 贡献指南。

欢迎加入我们的Slack 社区，或钉钉群（请扫描下方二维码）进行讨论。

FederatedScope 快速上手指南

FederatedScope 是一个综合性的联邦学习平台，基于事件驱动架构，旨在为学术界和工业界提供便捷易用且灵活定制的联邦学习解决方案。

环境准备

• 操作系统: Linux / macOS (Windows 需通过 WSL 或 Docker)
• Python 版本: >= 3.9
• 后端依赖: PyTorch (推荐 1.10+ 或 1.8+)
• 硬件要求:
  • 单机模拟模式：普通 CPU/GPU 即可
  • 分布式模式：多机网络环境
  • 若运行图联邦学习等下游任务，建议配备 NVIDIA GPU (CUDA 11.3+)

安装步骤

你可以选择 Conda 或 Docker 方式进行安装。

方式一：使用 Conda 安装（推荐）

1. 克隆代码库

   git clone https://github.com/alibaba/FederatedScope.git
   cd FederatedScope
   

2. 创建虚拟环境

   conda create -n fs python=3.9
   conda activate fs
   

3. 安装 PyTorch 请根据你的 CUDA 版本安装对应的 PyTorch。例如 CUDA 11.3：

   # 国内用户可使用清华源加速
   conda install -y pytorch=1.10.1 torchvision=0.11.2 torchaudio=0.10.1 torchtext=0.11.1 cudatoolkit=11.3 -c pytorch -c conda-forge
   

   注：Apple M1 芯片用户请直接运行 conda install pytorch torchvision torchaudio -c pytorch，随后执行 python -m pip install torchvision==0.11.3 以避免错误。

4. 安装 FederatedScope

   # 开发模式安装（可编辑源码）
   pip install -e .
   
   # (可选) 如需运行图学习、NLP 等应用任务，安装额外依赖
   bash environment/extra_dependencies_torch1.10-application.sh
   

方式二：使用 Docker 安装

如果你希望避免环境配置冲突，可以使用预构建的 Docker 镜像。

# 构建镜像 (基于 Torch 1.10 + CUDA 11)
docker build -f environment/docker_files/federatedscope-torch1.10.Dockerfile -t alibaba/federatedscope:base-env-torch1.10 .

# 启动容器
docker run --gpus device=all --rm -it --name "fedscope" -w $(pwd) alibaba/federatedscope:base-env-torch1.10 /bin/bash

注：运行前请确保宿主机已安装 NVIDIA 驱动和 nvidia-docker2。

基本使用

FederatedScope 提供了统一的接口，支持在单机上模拟多参与方（服务器与客户端）的联邦学习过程。以下是一个运行标准 FedAvg 算法进行图像分类的最简示例。

1. 准备配置

FederatedScope 内置了常用的数据集（DataZoo）和模型（ModelZoo）。你只需通过配置文件指定数据集和模型类型即可。

• 数据集示例：femnist
• 模型示例：convnet2

2. 运行任务

使用提供的示例配置文件启动训练。

使用默认配置运行：

python federatedscope/main.py --cfg scripts/example_configs/femnist.yaml

自定义参数运行： 你也可以在命令行直接覆盖配置文件中的参数，例如修改总轮数为 50，批大小为 128：

python federatedscope/main.py --cfg scripts/example_configs/femnist.yaml federate.total_round_num 50 dataloader.batch_size 128

3. 查看结果

运行后，终端将实时输出监控指标，包括各客户端的训练损失（train_loss）、准确率（train_acc）等信息：

INFO: Server has been set up ...
INFO: Model meta-info: <class 'federatedscope.cv.model.cnn.ConvNet2'>.
...
INFO: {'Role': 'Client #5', 'Round': 0, 'Results_raw': {'train_loss': 207.63, 'train_acc': 0.02, ...}}
INFO: {'Role': 'Client #1', 'Round': 0, 'Results_raw': {'train_loss': 209.09, 'train_acc': 0.02, ...}}

更多高级用法、自定义数据集注册及分布式部署详情，请访问官方文档：federatedscope.io