FederatedScope
v0.3.0
FederatedScope是一个全面的联合学习平台，可为学术界和行业的各种联合学习任务提供方便的使用和灵活的定制。 FederatedScope基于事件驱动的体系结构，集成了丰富的功能收集，以满足联合学习的新兴需求，并旨在建立一个易于使用的平台，以安全有效地促进学习。
我们的网站上提供了详细的教程：FederatedScope.io
您可以通过FederatedScope Playground或Google Colab尝试FederatedScope。
|代码结构|快速启动|高级|文档|出版物|贡献|
FederatedScope
├── federatedscope
│ ├── core
│ | ├── workers # Behaviors of participants (i.e., server and clients)
│ | ├── trainers # Details of local training
│ | ├── aggregators # Details of federated aggregation
│ | ├── configs # Customizable configurations
│ | ├── monitors # The monitor module for logging and demonstrating
│ | ├── communication.py # Implementation of communication among participants
│ | ├── fed_runner.py # The runner for building and running an FL course
│ | ├── ... ..
│ ├── cv # Federated learning in CV
│ ├── nlp # Federated learning in NLP
│ ├── gfl # Graph federated learning
│ ├── autotune # Auto-tunning for federated learning
│ ├── vertical_fl # Vertical federated learning
│ ├── contrib
│ ├── main.py
│ ├── ... ...
├── scripts # Scripts for reproducing existing algorithms
├── benchmark # We release several benchmarks for convenient and fair comparisons
├── doc # For automatic documentation
├── environment # Installation requirements and provided docker files
├── materials # Materials of related topics (e.g., paper lists)
│ ├── notebook
│ ├── paper_list
│ ├── tutorial
│ ├── ... ...
├── tests # Unittest modules for continuous integration
├── LICENSE
└── setup.py
我们为用户提供了一个端到端示例，以开始使用FederatedScope运行标准的FL课程。
首先，用户需要克隆源代码并安装所需的软件包（我们建议Python版本> = 3.9）。您可以在以下两种安装方法（通过Docker或Conda）之间进行选择，以安装FederatedScope。
git clone https://github.com/alibaba/FederatedScope.git
cd FederatedScope您可以构建Docker Image并使用Docker Env（CUDA 11和TORCH 1.10）运行：
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
如果您需要使用诸如Graph fl之类的下游任务运行，请在执行上述命令时将需求/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和TORCH 1.8。 Docker图像基于Nvidia-Docker。请在主机机器中预先安装NVIDIA驱动程序和nvidia-docker2 。在此处查看更多详细信息。
我们建议使用新的虚拟环境安装FederatedScope：
conda create -n fs python=3.9
conda activate fs如果您的后端是火炬，请提前安装火炬（启动火炬）。例如，如果您的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
# Downgrade torchvision to avoid segmentation fault
python -m pip install torchvision==0.11.3最后，安装后端后，您可以从source安装FederatedScope：
# Editable mode
pip install -e .
# Or (developers for dev mode)
pip install -e .[dev]
pre-commit install现在，您已经成功安装了FederatedScope的最小版本。 （ Optinal ）对于应用程序版本，包括图形，NLP和语音，运行：
bash environment/extra_dependencies_torch1.10-application.sh要运行FL任务，用户应准备数据集。 FederatedScope中提供的Datazoo可以帮助自动下载和预处理广泛使用的FL应用程序，包括CV，NLP，Graph Learning，建议等。用户可以直接指定配置中的cfg.data.type = DATASET_NAME 。例如，
cfg.data.type = ' femnist '要使用自定义的数据集，您需要按照特定格式准备数据集并进行注册。有关更多详细信息，请参考自定义数据集。
然后，用户应指定将在FL课程中培训的模型体系结构。 FederatedScope提供了一种模型ZOO，其中包含针对各种FL应用程序广泛采用的模型体系结构的实现。用户可以设置cfg.model.type = MODEL_NAME以在FL任务中应用特定的模型体系结构。例如，
cfg.model.type = 'convnet2'FederatedScope允许用户通过注册使用自定义模型。请参阅自定义模型，以获取有关如何自定义模型体系结构的更多详细信息。
请注意，FederatedScope为独立模式和分布式模式提供了一个统一的接口，并允许用户通过配置更改。
FederatedScope中的独立模式意味着模拟单个设备中的多个参与者（服务器和客户端），而参与者的数据相互隔离，并且可以通过消息传递共享其模型。
在这里，我们演示了如何使用FederatedScope运行标准的FL任务，并设置cfg.data.type = 'FEMNIST'和cfg.model.type = 'ConvNet2'以进行图像分类任务。用户可以自定义培训配置，例如cfg.federated.total_round_num ， cfg.dataloader.batch_size和cfg.train.optimizer.lr ，在配置（a .yAML文件）中，并运行一个标准的fl任务：
# Run with default configurations
python federatedscope/main.py --cfg scripts/example_configs/femnist.yaml
# Or with custom configurations
python federatedscope/main.py --cfg scripts/example_configs/femnist.yaml federate.total_round_num 50 dataloader.batch_size 128然后，您可以在培训过程中观察一些受监视的指标，为：
INFO: Server has been set up ...
INFO: Model meta-info: <class 'federatedscope.cv.model.cnn.ConvNet2'>.
... ...
INFO: Client 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.6341676712036, 'train_acc': 0.02, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.152683353424072}}
INFO: {'Role': 'Client #1', 'Round': 0, 'Results_raw': {'train_loss': 209.0940284729004, 'train_acc': 0.02, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.1818805694580075}}
INFO: {'Role': 'Client #8', 'Round': 0, 'Results_raw': {'train_loss': 202.24929332733154, 'train_acc': 0.04, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.0449858665466305}}
INFO: {'Role': 'Client #6', 'Round': 0, 'Results_raw': {'train_loss': 209.43883895874023, 'train_acc': 0.06, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.1887767791748045}}
INFO: {'Role': 'Client #9', 'Round': 0, 'Results_raw': {'train_loss': 208.83140087127686, 'train_acc': 0.0, 'train_total': 50, 'train_loss_regular': 0.0, 'train_avg_loss': 4.1766280174255375}}
INFO: ----------- Starting a new training round (Round #1) -------------
... ...
INFO: Server: Training is finished! Starting evaluation.
INFO: Client #1: (Evaluation (test set) at Round #20) test_loss is 163.029045
... ...
INFO: Server: Final evaluation is finished! Starting merging results.
... ...
FederatedScope中的分布式模式表示运行多个过程以构建FL课程，每个过程均以参与者（服务器或客户端）实例化并加载其数据的参与者（服务器或客户端）。参与者之间的通信已经由FederatedScope的通信模块提供。
要以分布式模式运行，您只需要：
cfg.data.file_path = PATH/TO/DATA的每个参与者；cfg.federate.model = 'distributed' ，并通过cfg.distributed.role = 'server'/'client'指定每个参与者的作用。cfg.distribute.server_host/client_host = xxxx和cfg.distribute.server_port/client_port = xxxx设置有效的地址。 （请注意，对于服务器，您需要设置server_host和server_port以获取侦听消息，而对于客户端，您需要设置client_host和client_port进行侦听以及server_host和server_port以在FL课程中加入）我们为以分布式模式运行的合成示例准备了一个：
# For server
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
# For clients
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中找到一个脚本）：
# Generate the toy data
python scripts/distributed_scripts/gen_data.py
# Firstly start the server that is waiting for clients to join in
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
# Start the client #1 (with another process)
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
# Start the client #2 (with another process)
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
# Start the client #3 (with another process)
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地址用“ xxxx”匿名化）：
INFO: Server: Listen to x.x.x.x:xxxx...
INFO: Server has been set up ...
Model meta-info: <class 'federatedscope.core.lr.LogisticRegression'>.
... ...
INFO: Client: Listen to x.x.x.x:xxxx...
INFO: Client (address x.x.x.x:xxxx) has been set up ...
Client (address x.x.x.x:xxxx) is assigned with #1.
INFO: Model meta-info: <class 'federatedscope.core.lr.LogisticRegression'>.
... ...
{'Role': 'Client #2', 'Round': 0, 'Results_raw': {'train_avg_loss': 5.215108394622803, 'train_loss': 333.7669372558594, 'train_total': 64}}
{'Role': 'Client #1', 'Round': 0, 'Results_raw': {'train_total': 64, 'train_loss': 290.9668884277344, 'train_avg_loss': 4.54635763168335}}
----------- Starting a new training round (Round #1) -------------
... ...
INFO: Server: Training is finished! Starting evaluation.
INFO: Client #1: (Evaluation (test set) at Round #20) test_loss is 30.387419
... ...
INFO: Server: Final evaluation is finished! Starting merging results.
... ...
作为一个全面的FL平台，FederatedScope提供了基本实施，以支持各种FL应用程序和边境研究的要求，以方便使用和灵活扩展，包括：
更多支持即将到来！我们准备了一个教程，以提供有关如何利用FederatedScope来享受您的联合学习旅程的更多详细信息！
相关主题的材料正在不断更新，请参阅FL-RECOMENDITATION，联邦HPO，个性化的FL，联合图形学习，FL-NLP，FL-NLP，FL-NLP，Fl-Incentive-Mechanismist，Flairness等。
联合学的类和方法已得到充分记录，因此用户可以通过以下方式生成API参考。
cd doc
pip install -r requirements.txt
make html笔记：
doc/requirements.txt仅用于Sphinx的API文档，可以通过github Actions .github/workflows/sphinx.yml自动生成。 （如果标题中的DOC则通过拉动请求触发。）我们将API引用放在我们的网站上。
此外，我们还提供可执行脚本和可自定义配置的文档。
FederatedScope以Apache许可证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提供了开发人员版本，并提供了与官方版本相比，可以执行提交检查的其他前挂钩：
# Install the developer version
pip install -e .[dev]
pre-commit install
# Or switch to the developer version from the official version
pip install pre-commit
pre-commit install
pre-commit run --all-files您可以参考为FederatedScope做出贡献以获取更多详细信息。
欢迎加入我们的Slack频道或Dingding Group（请扫描以下QR码）进行讨论。
