Syft.js is the “web” part of the OpenMined's open-source ecosystem for federated learning, which currently spans across web, iOS, Android, and servers/IoT.
Syft.js has following core features:
- 🛠️ Integration with PyGrid federated learning API.
- ⚙️ Training and inference of any PySyft model written in PyTorch or TensorFlow.
- 👤 Allows all data to stay on the user's device.
- 🔒 Support for secure multi-party computation and secure aggregation protocols using peer-to-peer WebRTC connections (in progress).
The library is built on top of TensorFlow.js.
There are a variety of additional privacy-preserving protections that may be applied, including differential privacy, muliti-party computation, and secure aggregation.
If you want to know how scalable federated systems are built, Towards Federated Learning at Scale is a fantastic introduction!
We have not currently made our initial release. Syft.js would soon be available via npm.
Meanwhile, you can install syft.js directly from Github. Note that syft.js needs Tensorflow.js library as peer dependency.
If you're using a package manage like NPM:
npm install --save https://github.com/OpenMined/syft.js @tensorflow/tfjs-core
Or if Yarn is your cup of tea:
yarn add https://github.com/OpenMined/syft.js @tensorflow/tfjs-core
If you're not using a package manager, you will be able to include Syft.js within a <script> tag when it's released.
<script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@1.2.5/dist/tf.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@openmined/syft.js@latest/dist/index.js"></script>As a developer, there are few steps to building your own secure federated learning system upon the OpenMined infrastructure:
- 🤖 Develop ML model and training procedure (aka
Planin PySyft terminology) using PySyft. By design, PySyft is built upon PyTorch and TensorFlow so you don't need to learn a new ML framework. - 🌎 Host model and Plans on PyGrid, which will deal with all the federated learning components of your pipeline.
- 🎉 Execute the training on the variety of end-user devices using the client library (syft.js, SwiftSyft, KotlinSyft, PySyft).
- 🔒 Securely aggregate trained user models in PyGrid.
📓 The entire workflow and process is described in greater detail in the Web & Mobile Federated Learning project roadmap.
Syft.js provides minimalistic API to communicate with federated learning PyGrid endpoints and execute PySyft's Plans in a browser. The federated learning cycle implemented with syft.js would contain following steps:
- Register into training cycle on PyGrid.
- Download required model and Plans from PyGrid.
- Execute the Plan with given model parameters and local user's data.
- Submit difference between original and trained model parameters for aggregation.
This whole cycle can be expressed in the following code:
import * as tf from '@tensorflow/tfjs-core';
import { Syft } from '@openmined/syft.js';
const gridUrl = 'ws://pygrid.myserver.com:5000';
const modelName = 'my-model';
const modelVersion = '1.0.0';
// if the model is protected with authentication token (optional)
const authToken = '...';
const worker = new Syft({ gridUrl, authToken, verbose: true });
const job = await worker.newJob({ modelName, modelVersion });
job.start();
job.on('accepted', async ({ model, clientConfig }) => {
const batchSize = clientConfig.batch_size;
const lr = clientConfig.lr;
// Load data.
const batches = LOAD_DATA(batchSize);
// Load model parameters.
let modelParams = model.params.map(p => p.clone());
// Main training loop.
for (let [data, labels] of batches) {
// NOTE: this is just one possible example.
// Plan name (e.g. 'training_plan'), its input arguments and outputs depends on FL configuration and actual Plan implementation.
let updatedModelParams = await job.plans['training_plan'].execute(
job.worker,
data,
labels,
batchSize,
lr,
...modelParams
);
// Use updated model params in the next iteration.
for (let i = 0; i < modelParams.length; i++) {
modelParams[i].dispose();
modelParams[i] = updatedModelParams[i];
}
}
// Calculate & send model diff.
const modelDiff = await model.createSerializedDiff(modelParams);
await job.report(modelDiff);
});
job.on('rejected', ({ timeout }) => {
// Handle the job rejection, e.g. re-try after timeout.
});
job.on('error', err => {
// Handle errors.
});Note that syft.js doesn't handle user's data collection, data storage and loading.
See API Documentation for complete reference.
The “Hello World” syft.js demo is MNIST training example located in examples/mnist folder.
It demonstrates how a simple neural net model created in PySyft can be trained in a browser
and the result of training averaged from multiple federated learning participants.
Running the demo is multi-stage and multi-component process (as the federated learning itself ;-)).
Below are example instructions that assume you
want to put everything under ~/fl-demo folder.
First, you will need to install following packages. It is recommended that you install python packages in separate virtualenv or conda environment, e.g.:
virtualenv -p python3 syft
source syft/bin/activateor
conda create -n syft python=3.7
conda activate syftGet the latest master branch of PySyft:
cd ~/fl-demo
git clone https://github.com/OpenMined/PySyft
cd PySyft
pip install .Get the latest dev branch of PyGrid:
cd ~/fl-demo
git clone https://github.com/OpenMined/PyGrid
cd PyGrid
git checkout devNOTE: currently it's required to replace
syft==0.2.6
with
git+git://github.com/OpenMined/PySyft#egg=syft
in pip-dep/requirements.txt file in PyGrid root folder.
Then continue with install:
pip install .
Get the latest master branch of syft.js with MNIST demo app included:
cd ~/fl-demo
git clone https://github.com/OpenMined/syft.js
cd syft.js
npm install
cd examples/mnist
npm installSyft.js connects to PyGrid to pick up the model and training Plan. For the demo to work, we need to populate that data into PyGrid.
There're two possible ways to start PyGrid:
- Run
./dev_server.shscript in the PyGrid root folder. - Run
docker-compose up --buildin the PyGrid root folder.
Here we assume you don't need to change default PyGrid configuration and it listens
on the localhost:5000. If you need to use different host/port,
PyGrid URL will need to be adjusted accordingly in further steps.
After the PyGrid is running, the next step is to create the model and training plan and host them in the PyGrid. PySyft tutorials include MNIST example jupyter notebooks that guide you through this process.
Fire up jupyter notebook:
cd ~/fl-demo/PySyft
jupyter notebook --notebook-dir=$(pwd)In the console, you should see URL you should open, or the browser will open automatically.
Inside the browser, navigate to examples/experimental/FL Training Plan folder in PySyft root.
There should be two notebooks of interest:
-
Create Plan: In this notebook the MNIST model and training plan are defined and saved into files. Run all cells to get files created.
-
Host Plan: Model and plan files created in the previous notebook are hosted in PyGrid. Run all cells to seed that data into PyGrid instance.
In case you need to reset PyGrid database to blank state, stop the process with Ctrl+C and remove databasegateway.db file in PyGrid root folder.
Or, if you used docker-compose, stop and re-start it using docker-compose up --force-recreate command.
Finally, we got to the browser part of the demo:
cd ~/fl-demo/syft.js/examples/mnist
npm startThis should start development server and open localhost:8080 in the browser.
Assuming PyGrid URL, MNIST model name and version were not modified in previous steps, just
press “Start FL Worker”.
You should see following in dev console:
- Syft.js registers into training cycle on PyGrid and gets configuration, Plan, and the model.
- App loads MNIST dataset and executes the training plan with each data batch. Charts are updated during this process, and you should see the training loss going down and the accuracy going up.
- After the training is complete, model diff is submitted to PyGrid.
If “Keep making cycle requests” is checked, the whole cycle process is repeated until PyGrid tells worker that model training is complete. It should be visible that PyGrid aggregates each 3 submissions into the global model, so each 3rd starts with lower loss and higher accuracy.
Syft.js was tested with Tensorflow.js v1.2.5.
syft.js was tested with Chrome and Firefox browsers.
For support in using this library, please join the #lib_syft_js Slack channel. If you’d like to follow along with any code changes to the library, please join the #code_syftjs Slack channel. Click here to join our Slack community!
Please check open issues as a starting point.
Bug reports and feature suggestions are welcomed as well.
The workflow is usual for github, the master branch is considered stable:
- Star, fork, and clone the repo.
- Create new branch for your changes.
- Push changes in your fork.
- Submit a PR to OpenMined/syft.js.
- PR is reviewed and accepted.
Read the contribution guide as a good starting place.
Additionally, we welcome you to the slack for queries related to the library and contribution in general.
The Slack channel #lib_syft_js is specific to syft.js development. See you there!
These people were integral part of the efforts to bring syft.js to fruition and in its active development.
 Patrick Cason 🤔 💻 🎨 📖 💼 |