Initial commit

Author: luisquintanilla

articles/machine-learning/how-to-homomorphic-encryption-seal.md

@@ -0,0 +1,395 @@
+---
+title: Deploy an encrypted image classification service
+titleSuffix: Azure Machine Learning
+description: Learn how to use Microsoft SEAL to deploy an encrypted prediction service for image classification
+author: luisquintanilla
+ms.author: luquinta 
+ms.date: 05/14/2020
+services: machine-learning
+ms.service: machine-learning
+ms.subservice: core
+ms.topic: conceptual
+#intent: As a data scientist, I want to deploy a service that uses homomorphic encryption to make predictions on encrypted image data
+---
+
+# Deploy an image classification model for encrypted inferencing in Azure Container Instance (ACI)
+
+This tutorial is **a new addition to the two-part series**. In the [previous tutorial](img-classification-part1-training.ipynb), you trained machine learning models and then registered a model in your workspace on the cloud.  
+
+Now, you're ready to deploy the model as a encrypted inferencing web service in [Azure Container Instances](https://docs.microsoft.com/azure/container-instances/) (ACI). A web service is an image, in this case a Docker image, that encapsulates the scoring logic and the model itself. 
+
+In this part of the tutorial, you use Azure Machine Learning service (Preview) to:
+
+> * Set up your testing environment
+> * Retrieve the model from your workspace
+> * Test the model locally
+> * Deploy the model to ACI
+> * Test the deployed model
+
+ACI is a great solution for testing and understanding the workflow. For scalable production deployments, consider using Azure Kubernetes Service. For more information, see [how to deploy and where](https://docs.microsoft.com/azure/machine-learning/service/how-to-deploy-and-where).
+
+
+## Prerequisites
+
+Complete the model training in the [Tutorial #1: Train an image classification model with Azure Machine Learning](train-models.ipynb) notebook.  
+
+
+<!-- #endregion -->
+
+```python
+# If you did NOT complete the tutorial, you can instead run this cell 
+# This will register a model and download the data needed for this tutorial
+# These prerequisites are created in the training tutorial
+# Feel free to skip this cell if you completed the training tutorial 
+
+# register a model
+from azureml.core import Workspace
+ws = Workspace.from_config()
+
+from azureml.core.model import Model
+
+model_name = "sklearn_mnist"
+model = Model.register(model_path="sklearn_mnist_model.pkl",
+                        model_name=model_name,
+                        tags={"data": "mnist", "model": "classification"},
+                        description="Mnist handwriting recognition",
+                        workspace=ws)
+
+
+```
+
+### Setup the Environment 
+
+Add `encrypted-inference` package as a conda dependency 
+
+```python
+from azureml.core.environment import Environment
+from azureml.core.conda_dependencies import CondaDependencies
+
+# to install required packages
+env = Environment('tutorial-env')
+cd = CondaDependencies.create(pip_packages=['azureml-dataprep[pandas,fuse]>=1.1.14', 'azureml-defaults', 'azure-storage-blob', 'encrypted-inference==0.9'], conda_packages = ['scikit-learn==0.22.1'])
+
+env.python.conda_dependencies = cd
+
+# Register environment to re-use later
+env.register(workspace = ws)
+```
+
+## Set up the environment
+
+Start by setting up a testing environment.
+
+### Import packages
+
+Import the Python packages needed for this tutorial.
+
+```python tags=["check version"]
+%matplotlib inline
+import numpy as np
+import matplotlib.pyplot as plt
+ 
+import azureml.core
+
+# display the core SDK version number
+print("Azure ML SDK Version: ", azureml.core.VERSION)
+```
+
+#### Install Homomorphic Encryption based library for Secure Inferencing
+
+Our library is based on [Microsoft SEAL](https://github.com/Microsoft/SEAL) and pubished to [PyPi.org](https://pypi.org/project/encrypted-inference) as an easy to use package 
+
+```python
+!pip install encrypted-inference==0.9
+```
+
+## Deploy as web service
+
+Deploy the model as a web service hosted in ACI. 
+
+To build the correct environment for ACI, provide the following:
+* A scoring script to show how to use the model
+* A configuration file to build the ACI
+* The model you trained before
+
+### Create scoring script
+
+Create the scoring script, called score.py, used by the web service call to show how to use the model.
+
+You must include two required functions into the scoring script:
+* The `init()` function, which typically loads the model into a global object. This function is run only once when the Docker container is started. 
+
+* The `run(input_data)` function uses the model to predict a value based on the input data. Inputs and outputs to the run typically use JSON for serialization and de-serialization, but other formats are supported. The function fetches homomorphic encryption based public keys that are uploaded by the service caller. 
+
+
+
+```python
+%%writefile score.py
+import json
+import os
+import pickle
+import joblib
+from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient, PublicAccess
+from encrypted.inference.eiserver import EIServer
+
+def init():
+    global model
+    # AZUREML_MODEL_DIR is an environment variable created during deployment.
+    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
+    # For multiple models, it points to the folder containing all deployed models (./azureml-models)
+    model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'sklearn_mnist_model.pkl')
+    model = joblib.load(model_path)
+
+    global server
+    server = EIServer(model.coef_, model.intercept_, verbose=True)
+
+def run(raw_data):
+
+    json_properties = json.loads(raw_data)
+
+    key_id = json_properties['key_id']
+    conn_str = json_properties['conn_str']
+    container = json_properties['container']
+    data = json_properties['data']
+
+    # download the Galois keys from blob storage
+    #TODO optimize by caching the keys locally  
+    blob_service_client = BlobServiceClient.from_connection_string(conn_str=conn_str)
+    blob_client = blob_service_client.get_blob_client(container=container, blob=key_id)
+    public_keys = blob_client.download_blob().readall()
+    
+    result = {}
+    # make prediction
+    result = server.predict(data, public_keys)
+
+    # you can return any data type as long as it is JSON-serializable
+    return result
+```
+
+### Create configuration file
+
+Create a deployment configuration file and specify the number of CPUs and gigabyte of RAM needed for your ACI container. While it depends on your model, the default of 1 core and 1 gigabyte of RAM is usually sufficient for many models. If you feel you need more later, you would have to recreate the image and redeploy the service.
+
+```python tags=["configure web service", "aci"]
+from azureml.core.webservice import AciWebservice
+
+aciconfig = AciWebservice.deploy_configuration(cpu_cores=1, 
+                                               memory_gb=1, 
+                                               tags={"data": "MNIST",  "method" : "sklearn"}, 
+                                               description='Encrypted Predict MNIST with sklearn + SEAL')
+```
+
+### Deploy in ACI
+Estimated time to complete: **about 2-5 minutes**
+
+Configure the image and deploy. The following code goes through these steps:
+
+1. Create environment object containing dependencies needed by the model using the environment file (`myenv.yml`)
+1. Create inference configuration necessary to deploy the model as a web service using:
+   * The scoring file (`score.py`)
+   * envrionment object created in previous step
+1. Deploy the model to the ACI container.
+1. Get the web service HTTP endpoint.
+
+```python tags=["configure image", "create image", "deploy web service", "aci"]
+%%time
+from azureml.core.webservice import Webservice
+from azureml.core.model import InferenceConfig
+from azureml.core.environment import Environment
+from azureml.core import Workspace
+from azureml.core.model import Model
+
+ws = Workspace.from_config()
+model = Model(ws, 'sklearn_mnist')
+
+myenv = Environment.get(workspace=ws, name="tutorial-env")
+inference_config = InferenceConfig(entry_script="score.py", environment=myenv)
+
+service = Model.deploy(workspace=ws, 
+                       name='sklearn-mnist-svc', 
+                       models=[model], 
+                       inference_config=inference_config, 
+                       deployment_config=aciconfig)
+
+service.wait_for_deployment(show_output=True)
+```
+
+Get the scoring web service's HTTP endpoint, which accepts REST client calls. This endpoint can be shared with anyone who wants to test the web service or integrate it into an application.
+
+```python tags=["get scoring uri"]
+print(service.scoring_uri)
+```
+
+## Test the model
+
+
+
+### Download test data
+Download the test data to the **./data/** directory
+
+```python
+import os
+from azureml.core import Dataset
+from azureml.opendatasets import MNIST
+
+data_folder = os.path.join(os.getcwd(), 'data')
+os.makedirs(data_folder, exist_ok=True)
+
+mnist_file_dataset = MNIST.get_file_dataset()
+mnist_file_dataset.download(data_folder, overwrite=True)
+```
+
+### Load test data
+
+Load the test data from the **./data/** directory created during the training tutorial.
+
+```python
+from utils import load_data
+import os
+import glob
+
+data_folder = os.path.join(os.getcwd(), 'data')
+# note we also shrink the intensity values (X) from 0-255 to 0-1. This helps the neural network converge faster
+X_test = load_data(glob.glob(os.path.join(data_folder,"**/t10k-images-idx3-ubyte.gz"), recursive=True)[0], False) / 255.0
+y_test = load_data(glob.glob(os.path.join(data_folder,"**/t10k-labels-idx1-ubyte.gz"), recursive=True)[0], True).reshape(-1)
+```
+
+<!-- #region -->
+### Predict test data
+
+Feed the test dataset to the model to get predictions.
+
+
+The following code goes through these steps:
+
+1. Create our Homomorphic Encryption based client 
+
+1. Upload HE generated public keys 
+
+1. Encrypt the data
+
+1. Send the data as JSON to the web service hosted in ACI. 
+
+1. Use the SDK's `run` API to invoke the service. You can also make raw calls using any HTTP tool such as curl.
+<!-- #endregion -->
+
+#### Create our Homomorphic Encryption based client 
+
+Create a new EILinearRegressionClient and setup the public keys 
+
+```python
+from encrypted.inference.eiclient import EILinearRegressionClient
+
+# Create a new Encrypted inference client and a new secret key.
+edp = EILinearRegressionClient(verbose=True)
+
+public_keys_blob, public_keys_data = edp.get_public_keys()
+
+```
+
+#### Upload HE generated public keys
+
+Upload the public keys to the workspace default blob store. This will allow us to share the keys with the inference server
+
+```python
+import azureml.core
+from azureml.core import Workspace, Datastore
+import os
+
+ws = Workspace.from_config()
+
+datastore = ws.get_default_datastore()
+container_name=datastore.container_name
+
+# Create a local file and write the keys to it
+public_keys = open(public_keys_blob, "wb")
+public_keys.write(public_keys_data)
+public_keys.close()
+
+# Upload the file to blob store
+datastore.upload_files([public_keys_blob])
+
+# Delete the local file
+os.remove(public_keys_blob)
+```
+
+#### Encrypt the data 
+
+```python
+#choose any one sample from the test data 
+sample_index = 1
+
+#encrypt the data
+raw_data = edp.encrypt(X_test[sample_index])
+
+```
+
+#### Send the test data to the webservice hosted in ACI
+
+Feed the test dataset to the model to get predictions. We will need to send the connection string to the blob storage where the public keys were uploaded 
+
+
+```python
+import json
+from azureml.core import Webservice
+
+service = Webservice(ws, 'sklearn-mnist-svc')
+
+#pass the connection string for blob storage to give the server access to the uploaded public keys 
+conn_str_template = 'DefaultEndpointsProtocol={};AccountName={};AccountKey={};EndpointSuffix=core.windows.net'
+conn_str = conn_str_template.format(datastore.protocol, datastore.account_name, datastore.account_key)
+
+#build the json 
+data = json.dumps({"data": raw_data, "key_id" : public_keys_blob, "conn_str" : conn_str, "container" : container_name })
+data = bytes(data, encoding='ASCII')
+
+print ('Making an encrypted inference web service call ')
+eresult = service.run(input_data=data)
+
+print ('Received encrypted inference results')
+```
+
+#### Decrypt the data
+
+Use the client to decrypt the results
+
+```python
+import numpy as np 
+
+results = edp.decrypt(eresult)
+
+print ('Decrypted the results ', results)
+
+#Apply argmax to identify the prediction result
+prediction = np.argmax(results)
+
+print ( ' Prediction : ', prediction)
+print ( ' Actual Label : ', y_test[sample_index])
+```
+
+## Clean up resources
+
+To keep the resource group and workspace for other tutorials and exploration, you can delete only the ACI deployment using this API call:
+
+```python tags=["delete web service"]
+service.delete()
+```
+
+<!-- #region -->
+
+If you're not going to use what you've created here, delete the resources you just created with this quickstart so you don't incur any charges. In the Azure portal, select and delete your resource group. You can also keep the resource group, but delete a single workspace by displaying the workspace properties and selecting the Delete button.
+
+## Next steps
+
+In this Azure Machine Learning tutorial, you used Python to:
+
+> * Set up your testing environment
+> * Retrieve the model from your workspace
+> * Test the model locally
+> * Deploy the model to ACI
+> * Test the deployed model
+ 
+You can also try out the [regression tutorial](regression-part1-data-prep.ipynb).
+<!-- #endregion -->
+
+![Impressions](https://PixelServer20190423114238.azurewebsites.net/api/impressions/MachineLearningNotebooks/tutorials/img-classification-part2-deploy.png)