Client API Usage

The FLARE Client API provides an easy way for users to convert their centralized, local training code into federated learning code with the following benefits:

• Only requires a few lines of code changes, without the need to restructure the code or implement a new class

• Reduces the number of new FLARE specific concepts exposed to users

• Easy adaptation from existing local training code using different frameworks (PyTorch, PyTorch Lightning, HuggingFace)

Core concept

The general structure of the popular federated learning (FL) workflow, “FedAvg” is as follows:

1. FL server initializes an initial model

2. For each round (global iteration):

   1. FL server sends the global model to clients

   2. Each FL client starts with this global model and trains on their own data

   3. Each FL client sends back their trained model

   4. FL server aggregates all the models and produces a new global model

On the client side, the training workflow is as follows:

1. Receive the model from the FL server

2. Perform local training on the received global model and/or evaluate the received global model for model selection

3. Send the new model back to the FL server

To convert a centralized training code to federated learning, we need to adapt the code to do the following steps:

1. Obtain the required information from received FLModel

2. Run local training

3. Put the results in a new FLModel to be sent back

For a general use case, there are three essential methods for the Client API:

• init(): Initializes NVFlare Client API environment.

• receive(): Receives model from NVFlare side.

• send(): Sends the model to NVFlare side.

Users can use the Client API to change their centralized training code to federated learning, for example:

import nvflare.client as flare

flare.init() # 1. Initializes NVFlare Client API environment.
input_model = flare.receive() # 2. Receives model from NVFlare side.
params = input_model.params # 3. Obtain the required information from received FLModel

# original local training code begins
new_params = local_train(params)
# original local training code ends

output_model = flare.FLModel(params=new_params) # 4. Put the results in a new FLModel
flare.send(output_model) # 5. Sends the model to NVFlare side.

With 5 lines of code changes, we convert the centralized training code to a federated learning setting.

After this, we can utilize the job templates and the NVIDIA FLARE Job CLI to generate a job so it can be run using NVIDIA FLARE FL Simulator or submit to a deployed NVFlare system.

Below is a table overview of key Client APIs.

Client API

API	Description	API Doc Link
init	Initializes NVFlare Client API environment.	init
receive	Receives model from NVFlare side.	receive
send	Sends the model to NVFlare side.	send
system_info	Gets NVFlare system information.	system_info
get_job_id	Gets job id.	get_job_id
get_site_name	Gets site name.	get_site_name
is_running	Returns whether the NVFlare system is up and running.	is_running
is_train	Returns whether the current task is a training task.	is_train
is_evaluate	Returns whether the current task is an evaluation task.	is_evaluate
is_submit_model	Returns whether the current task is a submit_model task.	is_submit_model

Lightning APIs

API	Description	API Doc Link
patch	Patches the PyTorch Lightning Trainer for usage with FLARE.	patch

Metrics Logger

API	Description	API Doc Link
SummaryWriter	SummaryWriter mimics the usage of Tensorboard’s SummaryWriter.	SummaryWriter
WandBWriter	WandBWriter mimics the usage of weights and biases.	WandBWriter
MLflowWriter	MLflowWriter mimics the usage of MLflow.	MLflowWriter

For more details on communication configuration, please refer to Client API.

Please check Client API Module nvflare.client.api for more in-depth information about all of the Client API functionalities.

If you are using PyTorch Lightning in your training code, you can check the Lightning API Module nvflare.app_opt.lightning.api.