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碼）進行討論。
