Getting started with FEDn

Note

This tutorial is a quickstart guide to FEDn based on a pre-made FEDn Project. It is designed to serve as a minimalistic starting point for developers. To learn about FEDn Projects in order to develop your own federated machine learning projects, see FEDn Projects.

Prerequisites

Set up a FEDn Studio Project

Start by creating an account in FEDn Studio and set up a project by following the instruction here: Studio.

Install FEDn

Using pip

Install the FEDn package using pip:

pip install fedn

From source

Clone the FEDn repository and install the package:

git clone https://github.com/scaleoutsystems/fedn.git
cd fedn
pip install .

It is recommended to use a virtual environment when installing FEDn.

Initialize FEDn with the client code bundle and seed model

Next, we will prepare the client. The key part of a FEDn Project is the client definition - code that contains entrypoints for training and (optionally) validating a model update on the client.

Locate into examples/mnist-pytorch and familiarize yourself with the project structure. The dependencies needed in the client environment are specified in client/python_env.yaml.

In order to train a federated model using FEDn, your Studio project needs to be initialized with a compute package and a seed model. The compute package is a bundle of the client specification, and the seed model is a first version of the global model.

Create a package of the fedn project (assumes your current working directory is in the root of the project /examples/mnist-pytorch):

fedn package create --path client

This will create a package called ‘package.tgz’ in the root of the project.

Next, run the build entrypoint defined in client/fedn.yaml to build the model artifact.

fedn run build --path client

This will create a seed model called ‘seed.npz’ in the root of the project. We will now upload these to your Studio project using the FEDn APIClient.

Upload the package and seed model

Note

You need to create an API admin token and use the token to authenticate the APIClient. Do this by going to the ‘Settings’ tab in FEDn Studio and click ‘Generate token’. Copy the access token and use it in the APIClient below. The controller host can be found on the main Dashboard in FEDn Studio.

You can also upload the file via the FEDn Studio UI. Please see Upload files for more details.

Upload the package and seed model using the APIClient:

>>> from fedn import APIClient
>>> client = APIClient(host="<controller-host>", token="<access-token>", secure=True, verify=True)
>>> client.set_active_package("package.tgz", helper="numpyhelper")
>>> client.set_active_model("seed.npz")

Configure and attach clients

Each local client needs an access token in order to connect. These tokens are issued from your Studio Project. Go to the ‘Clients’ tab and click ‘Connect client’. Download a client configuration file and save it to the root of the examples/mnist-pytorch folder. Rename the file to ‘client.yaml’. Then start the client by running the following command in the root of the project:

fedn run client -in client.yaml --secure=True --force-ssl

Repeat the above for the number of clients you want to use. A normal laptop should be able to handle several clients for this example.

Modifing the data split:

The default traning and test data for this example (MNIST) is for convenience downloaded and split by the client when it starts up (see ‘startup’ entrypoint). The number of splits and which split used by a client can be controlled via the environment variables FEDN_NUM_DATA_SPLITS and FEDN_DATA_PATH. For example, to split the data in 10 parts and start a client using the 8th partiton:

  • Unix/MacOS
  • Windows (Powershell)
export FEDN_PACKAGE_EXTRACT_DIR=package
export FEDN_NUM_DATA_SPLITS=10
export FEDN_DATA_PATH=./data/clients/8/mnist.pt
fedn client start -in client.yaml --secure=True --force-ssl

$env:FEDN_PACKAGE_EXTRACT_DIR="package"
$env:FEDN_NUM_DATA_SPLITS=10
$env:FEDN_DATA_PATH="./data/clients/8/mnist.pt"
fedn run client -in client.yaml --secure=True --force-ssl

Start a training session

You are now ready to start training the model using the APIClient:

>>> ...
>>> client.start_session(id="test-session", rounds=3)
# Wait for training to complete, when controller is idle:
>>> client.get_controller_status()
# Show model trail:
>>> models = client.get_model_trail()
# Show performance of latest global model:
>>> model_id = models[-1]['model']
>>> validations = client.get_validations(model_id=model_id)

Please see fedn.network.api for more details on the APIClient.

Note

In FEDn Studio, you can start a training session by going to the ‘Sessions’ tab and click ‘Start session’. See Studio for a step-by-step guide for how to control experiments using the UI.

Access model updates

Note

In FEDn Studio, you can access global model updates by going to the ‘Models’ or ‘Sessions’ tab. Here you can download model updates, metrics (as csv) and view the model trail.

You can access global model updates via the APIClient:

>>> ...
>>> client.download_model("<model-id>", path="model.npz")

Connecting clients using Docker

You can also use Docker to containerize the client. For convenience, there is a Docker image hosted on ghrc.io with fedn preinstalled. To start a client using Docker:

docker run \
  -v $PWD/client.yaml:/app/client.yaml \
  -e FEDN_PACKAGE_EXTRACT_DIR=package \
  -e FEDN_NUM_DATA_SPLITS=2 \
  -e FEDN_DATA_PATH=/app/package/data/clients/1/mnist.pt \
  ghcr.io/scaleoutsystems/fedn/fedn:0.9.0 run client -in client.yaml --force-ssl --secure=True

Where to go from here?

With you first FEDn federation set up, we suggest that you take a close look at how a FEDn project is structured and how you develop your own FEDn projects:

Local development deployment (using docker compose)

Note

These instructions are for users wanting to set up a local development deployment of FEDn (wihout Studio). This requires basic knowledge of Docker and docker-compose. The main use-case for this is rapid iteration while developing the FEDn Project, development of aggregator plugins, etc.

Follow the steps above to install FEDn, generate ‘package.tgz’ and ‘seed.tgz’. Then, instead of using a Studio project for a managed FEDn server-side, start a local FEDn network using docker-compose:

docker compose \
 -f ../../docker-compose.yaml \
 -f docker-compose.override.yaml \
 up

This starts up local services for MongoDB, Minio, the API Server, one Combiner and two clients. You can verify the deployment using these urls:

Upload the package and seed model to FEDn controller using the APIClient. In Python:

from fedn import APIClient
client = APIClient(host="localhost", port=8092)
client.set_active_package("package.tgz", helper="numpyhelper")
client.set_active_model("seed.npz")

You can now start a training session with 5 rounds (default):

client.start_session()

Automate experimentation with several clients

If you want to scale the number of clients, you can do so by modifying docker-compose.override.yaml. For example, in order to run with 3 clients, change the environment variable FEDN_NUM_DATA_SPLITS to 3, and add one more client by copying client1 and setting FEDN_DATA_PATH to /app/package/data/clients/3/mnist.pt

Access message logs and validation data from MongoDB

You can access and download event logs and validation data via the API, and you can also as a developer obtain the MongoDB backend data using pymongo or via the MongoExpress interface:

The credentials are as set in docker-compose.yaml in the root of the repository.

Access global models

You can obtain global model updates from the ‘fedn-models’ bucket in Minio:

Reset the FEDn deployment

To purge all data from a deployment incuding all session and round data, access the MongoExpress UI interface and delete the entire fedn-network collection. Then restart all services.

Clean up

You can clean up by running

docker-compose -f ../../docker-compose.yaml -f docker-compose.override.yaml down -v