FederatedScope
v0.3.0
A FederatedScope é uma plataforma de aprendizado federada abrangente que fornece uso conveniente e personalização flexível para várias tarefas de aprendizado federadas na academia e na indústria. Com base em uma arquitetura orientada a eventos, a FederatedScope integra ricas coleções de funcionalidades para satisfazer as demandas crescentes do aprendizado federado e pretende criar uma plataforma fácil de usar para promover o aprendizado com segurança e eficácia.
Um tutorial detalhado é fornecido em nosso site: federatedscope.io
Você pode experimentar o FederatedScope via FederatedScope Playground ou Google Colab.
| Estrutura de código | Iniciar rápido | Avançado | Documentação | Publicações | Contribuindo |
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
Fornecemos um exemplo de ponta a ponta para os usuários começarem a executar um curso de FL padrão com FederatedScope.
Primeiro de tudo, os usuários precisam clonar o código -fonte e instalar os pacotes necessários (sugerimos a versão python> = 3.9). Você pode escolher entre os dois métodos de instalação a seguir (via Docker ou CONDA) para instalar o FederatedScope.
git clone https://github.com/alibaba/FederatedScope.git
cd FederatedScopeVocê pode construir a imagem do Docker e executar com o Docker Env (CUDA 11 e 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
Se você precisar ser executado com tarefas de fluxo negativo, como o Graph FL, altere o nome do arquivo requisito/docker em outro ao executar os comandos acima:
# 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
NOTA: Você pode optar por usar o CUDA 10 e a tocha 1.8 através da alteração torch1.10 para torch1.8 . As imagens do Docker são baseadas no NVIDIA-Docker. Por favor, pré-instale os drivers da NVIDIA e nvidia-docker2 na máquina host. Veja mais detalhes aqui.
Recomendamos o uso de um novo ambiente virtual para instalar o FederatedScope:
conda create -n fs python=3.9
conda activate fsSe o seu back-end for uma tocha, instale a tocha com antecedência (tocha-departamento de tocha). Por exemplo, se sua versão CUDA for 11.3, execute o seguinte comando:
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-forgePara usuários com chips Apple M1:
conda install pytorch torchvision torchaudio -c pytorch
# Downgrade torchvision to avoid segmentation fault
python -m pip install torchvision==0.11.3 Finalmente, após a instalação do back -end, você pode instalar o federatedscope da source :
# Editable mode
pip install -e .
# Or (developers for dev mode)
pip install -e .[dev]
pre-commit installAgora, você instalou com sucesso a versão mínima do FederatedScope. ( Optinal ) para versão do aplicativo, incluindo gráfico, PNL e fala, execute:
bash environment/extra_dependencies_torch1.10-application.sh Para executar uma tarefa FL, os usuários devem preparar um conjunto de dados. O Datazoo fornecido no FederatedScope pode ajudar a baixar automaticamente e pré-processar conjuntos de dados públicos amplamente utilizados para vários aplicativos de FL, incluindo CV, PNL, aprendizado gráfico, recomendação, etc. Os usuários podem especificar diretamente cfg.data.type = DATASET_NAME na configuração. Por exemplo,
cfg.data.type = ' femnist 'Para usar conjuntos de dados personalizados, você precisa preparar os conjuntos de dados seguindo um determinado formato e registrá -lo. Consulte os conjuntos de dados personalizados para obter mais detalhes.
Em seguida, os usuários devem especificar a arquitetura do modelo que será treinada no curso da FL. O FederatedScope fornece um ModelZoo que contém a implementação de arquiteturas de modelos amplamente adotadas para várias aplicações de FL. Os usuários podem configurar cfg.model.type = MODEL_NAME para aplicar uma arquitetura de modelo específica nas tarefas FL. Por exemplo,
cfg.model.type = 'convnet2'FederatedScope permite que os usuários usem modelos personalizados via registro. Consulte os modelos personalizados para obter mais detalhes sobre como personalizar uma arquitetura de modelo.
Observe que o FederatedScope fornece uma interface unificada para o modo independente e o modo distribuído e permite que os usuários mudem por meio da configuração.
O modo independente no FederatedScope significa simular vários participantes (servidores e clientes) em um único dispositivo, enquanto os dados dos participantes são isolados um do outro e seus modelos podem ser compartilhados por meio de passagem de mensagens.
Aqui, demonstramos como executar uma tarefa FL padrão com FederatedScope, com a configuração de cfg.data.type = 'FEMNIST' e cfg.model.type = 'ConvNet2' para executar o Fedavg de baunilha para uma tarefa de classificação de imagem. Os usuários podem personalizar configurações de treinamento, como cfg.federated.total_round_num , cfg.dataloader.batch_size e cfg.train.optimizer.lr , na configuração (a .yaml) e executar uma tarefa padrão como:
# 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 128Então você pode observar algumas métricas monitoradas durante o processo de treinamento como:
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.
... ...
O modo distribuído no FederatedScope denota executando vários procedimentos para criar um curso de FL, onde cada procedimento é reproduzido como participante (servidor ou cliente) que instancia seu modelo e carrega seus dados. A comunicação entre os participantes já é fornecida pelo módulo de comunicação do FederatedScope.
Para executar com o modo distribuído, você só precisa:
cfg.data.file_path = PATH/TO/DATA para cada participante;cfg.federate.model = 'distributed' e especifique a função de cada participante por cfg.distributed.role = 'server'/'client' .cfg.distribute.server_host/client_host = xxxx e cfg.distribute.server_port/client_port = xxxx . (Observe que, para um servidor, você precisa configurar server_host e server_port para ouvir mensagens, enquanto para um cliente, você precisa configurar client_host e client_port para ouvir, bem como server_host e server_port para ingressar em um curso de FL)Preparamos um exemplo sintético para correr com o modo distribuído:
# 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 Um exemplo executável com dados de brinquedos gerados pode ser executado (um script pode ser encontrado nos 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 50054E você pode observar os resultados como (os endereços IP são anonimizados com '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.
... ...
Como uma plataforma abrangente de FL, o FederatedScope fornece a implementação fundamental para apoiar os requisitos de várias aplicações de FL e estudos de fronteira, para uso conveniente e extensão flexível, incluindo:
Mais apoios estão chegando em breve! Preparamos um tutorial para fornecer mais detalhes sobre como utilizar o FederatedScope para aproveitar sua jornada de aprendizado federado!
Os materiais de tópicos relacionados estão sendo atualizados constantemente, consulte a Recompensação FL, federada-HPO, FL personalizada, Federated Graph Learning, FL-NLP, FL-Ataque, mecanismo de incentivo, FL-Fairness e assim por diante.
As classes e métodos do FederatedScope foram bem documentados para que os usuários possam gerar as referências da API por:
cd doc
pip install -r requirements.txt
make htmlOBSERVAÇÃO:
doc/requirements.txt é apenas para documentação da API pela Sphinx, que pode ser gerada automaticamente por ações do GitHub .github/workflows/sphinx.yml . (Trigger By Pull Solicy se DOC no título.)Colocamos as referências da API em nosso site.
Além disso, fornecemos documentos para scripts executáveis e configurações personalizáveis.
FederatedScope é liberado pelo Apache License 2.0.
Se você achar federatedscope útil para sua pesquisa ou desenvolvimento, cite o seguinte artigo:
@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}
}
Mais publicações podem ser encontradas nas publicações.
Agradecemos muito qualquer contribuição para o FederatedScope! Fornecemos uma versão do desenvolvedor do FederatedScope com ganchos adicionais de pré-compromisso para executar verificações de confirmação em comparação com a versão oficial:
# 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-filesVocê pode se referir a contribuir com FederatedScope para obter mais detalhes.
Bem -vindo a participar do nosso Slack Channel, ou Dingding Group (digitalize o seguinte código QR) para discussão.
