Federated Learning Tutorial

This tutorial demonstrates the usage of Federated Learning with the goal of training a machine learning model with data from different users without having users share their data. The steps are done in a low code environment.

Cloud open beta

This is a Cloud open preview and is not supported for use in production environments.

Note: This is a step-by-step tutorial for running a UI driven Federated Learning experiment. To see a code sample for an API driven approach, go to Federated Learning Tutorial for API.

In this tutorial, “admin” refers to the user that starts the Federated Learning experiment, and “party” refers to one or more users who send their model results after the experiment is started by the admin. While the tutorial can be done by the admin and multiple parties, a single user can also complete a full runthrough as both the admin and the party. For a simpler demonstrative purpose, in the following tutorial only one data set is submitted by one party. For more details on the admin and party, see Terminology.

Watch this short video to learn how to create a Federating Learning Experiment in a Cloud Pak for Data as a Service project.

This video provides a visual method as an alternative to following the written steps in this documentation.

Start Federated Learning as the admin

In this tutorial, you train a Federated Learning experiment with a Tensorflow 2 framework and the MNIST data set.

  1. You can use an existing project or create a new project in IBM Watson Studio Cloud.
  2. On the Assets tab of your project, and click Add to project.
  3. Click Federated Learning experiment.
  4. Enter a Name for your experiment. Click Next.
    Screenshot of Federated Learning Define Details UI
  5. Under the Machine learning framework dropdown, select Tensorflow 2 under Model specification.
  6. Download the untrained model here.
  7. Back in the Federated Learning experiment, click Select under Model specification.
  8. Move the downloaded file, named tf_mnist_model.zip, into the Upload file box.
  9. Give your model a name and then click Import.
    Screenshot of Model import UI
  10. Choose Weighted average for the Fusion method and click Next.
    Screenshot of Fusion methods UI
  11. In the Define hyperparameters tab, you can use the default hyperparameters or adjust as you need. When you are finished, click Next.
  12. In the Select remote training systems tab, click Add new system. Screenshot of Add RTS UI
  13. Give your Remote Training System a name.
  14. Under Allowed users, choose the user that is your party then click Add. In this tutorial, you can add a dummy user or yourself, for demonstrative purposes.
    Note: This user must be added to your project as a collaborator with Editor permissions. Add additional systems by repeating this step for each remote party you intent to use. When you are finished, click Add systems.
    Screenshot of Training UI
  15. Return to the Select remote training systems tab, verify that your systems are selected, and then click Next.
  16. Review your settings, and then click Create.
  17. Your Federated Learning experiment status is Pending when it starts. When your experiment is ready for parties to connect, the status will change to Setup – Waiting for remote systems. This may take a few minutes.
  18. To download the party configuration and the party connector script that can be run on the remote party, click View setup information.
  19. Click the “down arrow” icon besides each of the remote training systems that you created, and then click Python script. This gives you the party connector script. Save the script to a directory on your machine.
    Screenshot of Training UI

Send data as the party

  1. Download the data handler mnist_keras_data_handler.py by right-clicking here and click Save link as. Save it to the same directory as the party connector script.
  2. Download the MNIST handwriting data set from our gallery here. In the the same directory as the untrained model, data handler, and the rest of your files, unzip it by running the unzip command unzip MNIST-pkl.zip.
  3. Install Watson Machine Learning by running pip install ibm-watson-machine-learning. You now have the party connector script from step 19 of Start Federated Learning as the admin, mnist_keras_data_handler.py, mnist-keras-test.pkl and mnist-keras-train.pkl, data handler in the same directory.

  4. Your party connector script looks similar to the following. Edit it by filling in the data file locations, the data handler, and API key for the user defined in the remote training system.

    from ibm_watson_machine_learning import APIClient
from ibmfl.party.party import Party
	
	
wml_credentials = {
    "url": "https://us-south.ml.cloud.ibm.com",
    "apikey": "<API KEY>"
}
	
wml_client = APIClient(wml_credentials)
	
party_config = {
    "aggregator": {
        "ip": "us-south.ml.cloud.ibm.com/ml/v4/trainings/dc7ff18e-04fb-4e33-a005-1fedc156fab6"
    },
    "connection": {
        "info": {
            "id": "f0546938-4852-4180-af7b-10b083b43ef7"
        }
    },
    # Supply the name of the data handler class and path to it.
    # The info section may be used to pass information to the 
    # data handler.
    # For example,
    # 	"data": {
    # 		"info": {
    # 			"npz_file":"./example_data/example_data.npz"
    # 		},
    # 		"name": "MnistSklearnDataHandler",
    # 		"path": "example.mnist_sklearn_data_handler"
    # 	},
    "data": {        
        "name": "MnistTFDataHandler",
        "path": "./mnist_keras_data_handler.py",
        "info": {
            "train_file": "./mnist-keras-train.pkl",
            "test_file": "./mnist-keras-test.pkl"
        },
    },
    "local_training": {
        "name": "FedAvgLocalTrainingHandler",
        "path": "ibmfl.party.training.fedavg_local_training_handler"
    },
    "protocol_handler": {
        "name": "PartyProtocolHandler",
        "path": "ibmfl.party.party_protocol_handler"
    }
}
	
p = Party( config_dict = party_config, token = "Bearer " + wml_client.wml_token )
p.start()
	
while not p.connection.stopped:
    pass

    To get your API key, please go to Manage > Access(IAM) > API keys in your IBM Cloud account. If you don’t have one, click Create API key, fill out the fields and click Create.

  5. Run the party connector script.

From the UI you can monitor the status of your Federated Learning experiment.

Next steps

Ready to create your own customized Federated Experiment? See the high level steps in Creating your Federated Learning experiment.