KarhouTam/FL-bench
Benchmark of federated learning. Dedicated to the community. 🤗
FL‑bench란?
FL‑bench는 연합 학습(FL) 연구를 위한 오픈소스 벤치마킹 스위트입니다. 다양한 이미지 분류 데이터셋에서 수십 개의 고전 및 최신 FL 알고리즘을 훈련하고 평가할 수 있는 즉시 실행 가능한 프레임워크를 제공합니다. 코드는 공통 서버-클라이언트 추상화를 중심으로 구성되어 있어 각 메서드는 훈련 파이프라인의 대부분을 재사용하면서 몇 개의 훅만 구현하면 됩니다.
중요한 이유
- 빠른 실험 – 단일 명령줄 플래그로 알고리즘(FedAvg, FedProx, SCAFFOLD, pFedSim 등)을 전환할 수 있습니다.
- 재현 가능한 설정 – 모든 하이퍼파라미터는 YAML 설정 파일에 있으며 기본값은 문서화되어 CLI로 재정의할 수 있습니다.
- 확장 가능한 실행 – Ray를 사용한 병렬 훈련을 기본 지원하여 추가 코드 없이 멀티프로세스 또는 멀티노드 실행이 가능합니다.
- 풍부한 생태계 – 다양한 표준 비전 모델(ResNet, EfficientNet, MobileNet, LeNet5 등)과 폭넓은 데이터셋(MNIST, CIFAR‑10/100, FEMNIST, DomainNet, 의료 이미지 세트 등)을 구성 가능한 분할 전략과 함께 포함합니다.
- 확장 가능 – 제공된
FedAvgServer/FedAvgClient기본 클래스를 하위 클래스화하거나 데이터셋/모델 레지스트리를 확장하여 새로운 FL 메서드, 모델 또는 데이터셋을 추가할 수 있습니다.
빠른 시작(원라이너)
# 의존성 설치
pip install -r .env/requirements.txt
# 100개 클라이언트용 합성 MNIST 분할 생성
data/generate_data.py -d mnist -a 0.1 -cn 100
# 기본 FedAvg 실험 실행
python main.py method=fedavg
이 명령은 config/defaults.yaml에서 기본 구성을 읽고, 100개 클라이언트를 조정하는 서버를 시작하며, 분할된 MNIST 데이터에서 ResNet(또는 선택한 모델)을 훈련하고 메트릭을 TensorBoard 또는 Visdom에 기록합니다.
사용자 지정 방법
| 항목 | 방법 |
|---|---|
| 알고리즘 | CLI에서 method=를 변경하거나 YAML 파일을 편집합니다(예: method=fedprox fedprox.mu=0.01). |
| 하이퍼파라미터 | CLI(optimizer.lr=0.1), 사용자 지정 설정 파일, 또는 메서드의 get_hyperparams() 함수 편집을 통해 모든 인수를 재정의합니다. |
| 모델 | 내장 모델(model: resnet18)을 선택하거나 src/utils/models.py에 CustomModel 클래스를 만들고 model: custom으로 참조합니다. |
| 데이터셋 / 분할 | 데이터셋 목록(MNIST, CIFAR‑10, DomainNet 등)과 data/README.md에 정의된 분할 전략을 선택합니다. |
| 병렬 처리 | 설정에서 mode: parallel 및 parallel.num_workers를 설정합니다. Ray가 자동으로 워커를 생성합니다. |
| 모니터링 | common.monitor를 tensorboard 또는 visdom으로 설정하고 해당 서버(tensorboard --logdir=… 또는 python -m visdom.server)를 시작합니다. |
새 FL 메서드 추가(개발자 팁)
- 서버 및 클라이언트 클래스 생성 –
FedAvgServer/FedAvgClient(또는 해당 유틸리티가 필요한 경우 기존 메서드)에서 상속합니다. - 필요에 따라 훅 재정의:
package()– 서버와 클라이언트 간에 전송되는 매개변수.aggregate_client_updates()– 서버의 사용자 지정 집계 논리.fit(),set_parameters()– 클라이언트 측 훈련 조정.
- 새 메서드 등록 –
src/server/에.py파일을 추가합니다(파일 이름이 CLI에서 사용되는method이름이 됩니다). - 하이퍼파라미터 노출 –
argparse.Namespace를 반환하는 정적get_hyperparams()를 통해 설정 파일에서 설정할 수 있습니다.
라이선스 및 인용
프로젝트는 GPL‑3.0으로 출시되었습니다. 논문에서 FL‑bench를 사용하는 경우 제공된 BibTeX 항목을 인용하세요:
@software{Tan_FL-bench,
author = {Tan, Jiahao and Wang, Xinpeng},
license = {GPL-3.0},
title = {{FL-bench: A federated learning benchmark for solving image classification tasks}},
url = {https://github.com/KarhouTam/FL-bench}
}
결론
FL‑bench는 실제 이미지 데이터에서 연합 학습 알고리즘을 비교하고, 개인화 또는 도메인 일반화 확장을 실험하고, Ray로 실행을 확장하려는 모든 사람에게 실용적이고 문서화된 플랫폼입니다. 모듈식 설계로 실험을 재현 가능하게 유지하면서 새로운 메서드, 모델 또는 데이터셋을 쉽게 연결할 수 있습니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트