FederatedScope
v0.3.0
FederatedScope est une plate-forme d'apprentissage fédérée complète qui offre une utilisation pratique et une personnalisation flexible pour diverses tâches d'apprentissage fédérées dans le monde universitaire et l'industrie. Sur la base d'une architecture axée sur les événements, FederatedScope intègre de riches collections de fonctionnalités pour satisfaire les demandes naissantes de l'apprentissage fédéré et vise à créer une plate-forme facile à utiliser pour promouvoir l'apprentissage en toute sécurité et efficacement.
Un tutoriel détaillé est fourni sur notre site Web: FederatedScope.io
Vous pouvez essayer FederatedScope via FederatedScope Playground ou Google Colab.
| Structure du code | Démarrage rapide | Avancé | Documentation | Publications | Contribution |
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
Nous fournissons un exemple de bout en bout aux utilisateurs pour commencer à exécuter un cours FL standard avec FederatedScope.
Tout d'abord, les utilisateurs doivent cloner le code source et installer les packages requis (nous suggérons Python version> = 3,9). Vous pouvez choisir entre les deux méthodes d'installation suivantes (via Docker ou Conda) pour installer FederatedScope.
git clone https://github.com/alibaba/FederatedScope.git
cd FederatedScopeVous pouvez créer une image Docker et exécuter avec Docker Env (CUDA 11 et 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
Si vous devez s'exécuter avec des tâches en bas telles que Graph FL, modifiez le nom de fichier exigence / docker en un autre lors de l'exécution des commandes ci-dessus:
# 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
Remarque: Vous pouvez choisir d'utiliser CUDA 10 et Torch 1.8 via Changer torch1.10 en torch1.8 . Les images Docker sont basées sur le nvidia-docker. Veuillez pré-installer les pilotes Nvidia et nvidia-docker2 dans la machine hôte. Voir plus de détails ici.
Nous vous recommandons d'utiliser un nouvel environnement virtuel pour installer FederatedScope:
conda create -n fs python=3.9
conda activate fsSi votre backend est une torche, veuillez installer la torche à l'avance (TORCH-Startted). Par exemple, si votre version CUDA est 11.3, veuillez exécuter la commande suivante:
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-forgePour les utilisateurs avec des puces Apple M1:
conda install pytorch torchvision torchaudio -c pytorch
# Downgrade torchvision to avoid segmentation fault
python -m pip install torchvision==0.11.3 Enfin, une fois le backend installé, vous pouvez installer FederatedScope à partir de source :
# Editable mode
pip install -e .
# Or (developers for dev mode)
pip install -e .[dev]
pre-commit installMaintenant, vous avez installé avec succès la version minimale de FederatedScope. ( Optinal ) pour la version de l'application, y compris le graphique, le NLP et la parole, l'exécution:
bash environment/extra_dependencies_torch1.10-application.sh Pour exécuter une tâche FL, les utilisateurs doivent préparer un ensemble de données. Le datazoo fourni dans FederatedScope peut aider à télécharger et à prétraiter automatiquement les ensembles de données publics largement utilisés pour diverses applications FL, y compris CV, NLP, l'apprentissage du graphique, la recommandation, etc. Les utilisateurs peuvent directement spécifier cfg.data.type = DATASET_NAME dans la configuration. Par exemple,
cfg.data.type = ' femnist 'Pour utiliser des ensembles de données personnalisés, vous devez préparer les ensembles de données en suivant un certain format et l'enregistrer. Veuillez vous référer aux ensembles de données personnalisés pour plus de détails.
Ensuite, les utilisateurs doivent spécifier l'architecture du modèle qui sera formé au cours FL. FederatedScope fournit un modelzoo qui contient la mise en œuvre d'architectures de modèle largement adoptées pour diverses applications FL. Les utilisateurs peuvent configurer cfg.model.type = MODEL_NAME pour appliquer une architecture de modèle spécifique dans les tâches FL. Par exemple,
cfg.model.type = 'convnet2'FederatedScope permet aux utilisateurs d'utiliser des modèles personnalisés via l'enregistrement. Veuillez vous référer aux modèles personnalisés pour plus de détails sur la façon de personnaliser une architecture de modèle.
Notez que FederatedScope fournit une interface unifiée pour le mode autonome et le mode distribué, et permet aux utilisateurs de changer via la configuration.
Le mode autonome dans FederatedScope signifie simuler plusieurs participants (serveurs et clients) dans un seul appareil, tandis que les données des participants sont isolées les unes des autres et que leurs modèles peuvent être partagés via le passage des messages.
Ici, nous démontrons comment exécuter une tâche FL standard avec FederatedScope, avec la définition de cfg.data.type = 'FEMNIST' et cfg.model.type = 'ConvNet2' pour exécuter la vanille Fedavg pour une tâche de classification d'image. Les utilisateurs peuvent personnaliser les configurations de formation, telles que cfg.federated.total_round_num , cfg.dataloader.batch_size et cfg.train.optimizer.lr , dans la configuration (un fichier .yaml), et exécuter une tâche FL standard comme:
# 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 128Ensuite, vous pouvez observer certaines mesures surveillées pendant le processus de formation comme:
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.
... ...
Le mode distribué dans FederatedScope désigne l'exécution de plusieurs procédures pour construire un cours FL, où chaque procédure joue en tant que participant (serveur ou client) qui instancie son modèle et charge ses données. La communication entre les participants est déjà fournie par le module de communication de FederatedScope.
Pour fonctionner avec le mode distribué, il vous suffit de:
cfg.data.file_path = PATH/TO/DATA pour chaque participant;cfg.federate.model = 'distributed' et spécifiez le rôle de chaque participant par cfg.distributed.role = 'server'/'client' .cfg.distribute.server_host/client_host = xxxx et cfg.distribute.server_port/client_port = xxxx . (Notez que pour un serveur, vous devez configurer server_host et server_port pour l'écoute des messages, tandis que pour un client, vous devez configurer client_host et client_port pour écouter ainsi que server_host et server_port pour rejoindre un cours FL)Nous préparons un exemple synthétique pour fonctionner avec le mode distribué:
# 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 Un exemple exécutable avec des données de jouets générées peut être exécutée avec (un script peut être trouvé dans 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 50054Et vous pouvez observer les résultats comme (les adresses IP sont anonymisées de «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.
... ...
En tant que plate-forme FL complète, FederatedScope fournit la mise en œuvre fondamentale pour soutenir les exigences de diverses applications FL et des études frontalières, à la fois à une utilisation pratique et à une extension flexible, notamment:
Plus de supports arrivent bientôt! Nous avons préparé un tutoriel pour fournir plus de détails sur la façon d'utiliser le Scope fédéré pour profiter de votre voyage d'apprentissage fédéré!
Les matériaux de sujets connexes sont constamment mis à jour, veuillez vous référer à la recommandation FL, Federateated-HPO, FL personnalisé, Federated Graph Learning, FL-NLP, FL-Attacker, Fl-Incentive-Mechanism, FL-Fairness, etc.
Les classes et les méthodes de FederatedScope ont été bien documentées afin que les utilisateurs puissent générer les références d'API par:
cd doc
pip install -r requirements.txt
make htmlNOTE:
doc/requirements.txt est uniquement pour la documentation de l'API par Sphinx, qui peut être généré automatiquement par les actions GitHub .github/workflows/sphinx.yml . (Déclencher par demande de traction si DOC dans le titre.)Nous mettons les références API sur notre site Web.
En outre, nous fournissons des documents pour les scripts exécutables et les configurations personnalisables.
FederatedScope est libéré sous Apache Licence 2.0.
Si vous trouvez FederatedScope utile pour vos recherches ou développement, veuillez citer l'article suivant:
@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}
}
D'autres publications peuvent être trouvées dans les publications.
Nous apprécions grandement toute contribution à FederatedScope! Nous fournissons une version développeur de FederatedScope avec des crochets pré-engagements supplémentaires pour effectuer des vérifications de validation par rapport à la version officielle:
# 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-filesVous pouvez vous référer à la contribution à FederatedScope pour plus de détails.
Bienvenue à rejoindre notre canal Slack ou notre groupe de dingding (veuillez analyser le code QR suivant) pour la discussion.
