Important:

IBM Cloud Pak® for Data Version 4.6 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.6 reaches end of support. For more information, see Upgrading IBM Software Hub in the IBM Software Hub Version 5.1 documentation.

Federated Learning Tensorflow 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 with the UI and with a Tensorflow framework.

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, see Federated Learning Tensorflow samples.

Tip: 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 information on the admin and party, see Terminology.

In this tutorial you will learn to:

Step 1: Start Federated Learning as the admin
Step 2: Train model as a party
Step 3: Save and deploy the model online

Step 1: Start Federated Learning as the admin

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

Before you begin

Login your Cloud Pak for Data cluster. If you don't have an account, create one with any email.
Install the Watson Machine Learning image if you do not have it set up in your environment.
Login your IBM Cloud Pak for Data host.
You can use an existing project or create a new project in Cloud Pak for Data.

Start the aggregator

On the Assets tab of your project, click New asset.
Click Federated Learning experiment.
Enter a Name for your experiment and optionally a description.
Under the Machine learning framework dropdown, select Tensorflow 2 under Model specification.
Download the untrained model.
Back in the Federated Learning experiment, click Select under Model specification.
Move the downloaded file, named tf_mnist_model.zip, into the Upload file box.
Select runtime-22.2-py3.10 for the Software Specification dropdown.
Give your model a name and then click Add.
Choose Weighted average for the Fusion method and click Next.
In the Define hyperparameters tab, you can use the default hyperparameters or adjust as you need. When you are finished, click Next.
In the Select remote training systems tab, click Add new system.
Give your Remote Training System a name.
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.
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.
Return to the Select remote training systems tab, verify that your systems are selected, and then click Next.
Review your settings, and then click Create.
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.
To download the party configuration and the party connector script that can be run on the remote party, click View setup information.
Click the "down arrow" icon besides each of the remote training systems that you created, and then click Party connector script. This gives you the party connector script. Save the script to a directory on your machine.

Train model as the party

Ensure that you are using the same Python version as the admin. Using a different Python version might cause compatibility issues. To see Python versions compatible with different frameworks, see Frameworks and Python version compatibility.
Create a new local directory, and put your party connector script in it.
Download the data handler mnist_keras_data_handler.py by right-clicking on it and click Save link as. Save it to the same directory as the party connector script.
Download the MNIST handwriting data set from our gallery. In the the same directory as the party connector script, data handler, and the rest of your files, unzip it by running the unzip command unzip MNIST-pkl.zip.
Install Watson Machine Learning.
- If you are using Linux, run pip install 'ibm-watson-machine-learning[fl-rt22.2-py3.10]'.
- If you are using Mac OS with M-series CPU and Conda, download the installation script and then run ./install_fl_rt22.2_macos.sh <name for new conda environment>.
  You now have the party connector script, mnist_keras_data_handler.py, mnist-keras-test.pkl and mnist-keras-train.pkl, data handler in the same directory.

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

from ibm_watson_machine_learning import APIClient

wml_credentials = {
  "username": "<username>",
  "password": "<password>",
  "instance_id" : "wml_local",
  "url": "https://cpd-cluster.com",
  "version": "4.6"
}

wml_client = APIClient(wml_credentials)
wml_client.set.default_project("XXX-XXX-XXX-XXX-XXX")

party_metadata = {  
          wml_client.remote_training_systems.ConfigurationMetaNames.DATA_HANDLER: {
          # Supply the name of the data handler class and path to it.
          # The info section may be used to create a key value pair for the file type of local data set or the path of your data set.
          # For example,
          #     "name": "MnistTFDataHandler", # This is the name of the data handler class
          #     "path": "pwd + "mnist_sklearn_data_handler.py"",
          #     "info": {
          #         "train_file": pwd + "/mnist-keras-train.pkl",
          #         "test_file": pwd + "/mnist-keras-test.pkl"
          #     }
          "name": "<data handler>",
          "path": "<path to data handler>",
                  "info": {
                      "<information to pass to data handler>"
                  }
              }
          }

party = wml_client.remote_training_systems.create_party("XXX-XXX-XXX-XXX-XXX", party_metadata)

party.monitor_logs()
party.run(aggregator_id="XXX-XXX-XXX-XXX-XXX", asynchronous=False)

Run the party connector script: python3 rts_<RTS Name>_<RTS ID>.py.
From the UI you can monitor the status of your Federated Learning experiment.

Step 3: Save and deploy the model online

In this section, you will learn to save and deploy the model that you trained.

In your completed Federated Learning experiment, click Save model to project.
Give your model a name and click Save.
Go to your Watson Studio project home. If you don't have a Deployment space, create one. Click the hamburger icon on the upper-left to open the navigation.
Under Deployments, click View all spaces. Click New deployment space. Fill in the fields and click Create.
In your Watson Studio project, you should see the newly saved model under the Models assets. Click the model to go to its details page and click Promote to space.
Choose a deployment space for your trained model and click Promote.
Go into the deployment space where you promoted the model.
Find your model and click the deploy icon.
Choose Online for Deployment type.
Give your deployment a name. Click Create.
You can monitor your model's deployment status under the Deployments tab.

Next steps

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

Parent topic: Federated Learning tutorial and samples