Overview: Deploying Python functions in Watson Machine Learning

You can deploy Python functions in Watson Machine Learning the same way that you can deploy models. Your tools and apps can use the Watson Machine Learning Python client or REST API to send data to your deployed functions the same way that they send data to deployed models. Deploying functions gives you the ability to hide details (such as credentials), preprocess data before passing it to models, perform error handling, and include calls to multiple models, all within the deployed function instead of in your application.

Sections in this topic:

 

Basic steps for using deployed functions

There are four basic steps for creating and deploying functions in Watson Machine Learning:

  1. Define the function
  2. Store the function in the repository
  3. Deploy the stored function
  4. Send data to the function for processing

 

Step 1: Define the function

Create a Python closure with a nested function named “score”.

Example Python code

Note: You could run this code in your local environment, or in a notebook in Watson Studio.

def my_deployable_function():

    def score( payload ):
    
        return payload["values"][0]

    return score

You could test your function like this:

function_result = my_deployable_function()( { "values" : [ "Hello, world!" ] } )
print( function_result )

Output:

Test output

Python closures

To learn more about closures, see:

Requirements for the nested, “score” function

The nested function must meet the following requirements:

  • Must be named “score”
  • Must accept a single, JSON input parameter
  • The input parameter must include an array with the name “values”:
    { "values" : [] }
    
  • The input parameter can also include additional name-value pairs
  • The score function must return a JSON-serializable object (for example: dictionaries or lists)

 

Step 2: Store the function

Store the enclosing function in your Watson Machine Learning repository using the Watson Machine Learning Python client.

See also:

Example Python code

# Look up your Watson Machine Learning credentials and then paste them here
wml_credentials = {
    "apikey"      : "",
    "instance_id" : "",
    "password"    : "",
    "url"         : "",
    "username"    : ""
}

# Instantiate WatsonMachineLearningAPIClient
from watson_machine_learning_client import WatsonMachineLearningAPIClient
client = WatsonMachineLearningAPIClient( wml_credentials )

# Store the function
meta_data = { client.repository.FunctionMetaNames.NAME : 'My deployable function' }
function_details = client.repository.store_function( meta_props=meta_data, function=my_deployable_function )

 

Step 3: Deploy the stored function

Deploy the stored function the same way you deploy stored models.

Notes

  • The only deployment type supported with Python functions is web service deployment
  • The body of the outer function of your closure is run once: when the function is deployed
  • The body of the inner function named score is run whenever the function deployment is used (whenever payload data is sent to the function deployment endpoint URL for processing)

Example Python code

function_id = function_details["metadata"]["guid"]
function_deployment_details = client.deployments.create( artifact_uid=function_id, name='My function deployment' )

 

Step 4: Send data to the deployed function for processing

You can use the Watson Machine Learning Python client or REST API to send data to your function deployment for processing in exactly the same way you send data to models for processing.

See also:

Example 1: Python code, using the Python client

function_deployment_endpoint_url = client.deployments.get_scoring_url( function_deployment_details )
payload = { "values" : [ "Hello, world!" ] }

# Send data to deployment for processing
client.deployments.score( function_deployment_endpoint_url, payload )

Example 2: Python code, using the REST API

import requests

# Get an IAM token from IBM Cloud
url     = "https://iam.bluemix.net/oidc/token"
headers = { "Content-Type" : "application/x-www-form-urlencoded" }
data    = "apikey=" + wml_credentials["apikey"] + "&grant_type=urn:ibm:params:oauth:grant-type:apikey"
IBM_cloud_iam_uid = "bx"
IBM_cloud_iam_pwd = "bx"
response  = requests.post( url, headers=headers, data=data, auth=( IBM_cloud_iam_uid, IBM_cloud_iam_pwd ) )

if 200 != response.status_code:
    print( response.status_code )
    print( response.reason )
else:
    iam_token = response.json()["access_token"]
    
    # Send data to deployment for processing
    headers = { "Content-Type" : "application/json", 
                "Authorization" : "Bearer " + iam_token,
                "ML-Instance-ID" : wml_credentials["instance_id"] }
    response = requests.post( function_deployment_endpoint_url, json=payload, headers=headers )
    print ( response.text )

 

Making build-time variables available to the function

You can cause build-time data to be saved with the deployed function, making it available at run time, by including that data in a default parameter of the outer function of the closure.

Example Python code

In this example, a dictionary containing the text string “Hello again.” is in the default value of the parameter parms in the function definition.

build_time_var = { "text" : "Hello again." }

def my_deployable_function( parms=build_time_var ):

    def score( payload ):
    
        return payload["values"][0] + "\n" + parms["text"]

    return score

Test output:

Test output

 

Passing payload data to model deployments

Your function can pass payload data on to one or more deployed models.

Example Python code

In this example, a dictionary containing credentials for a Watson Machine Learning service instance as well as an endpoint url for a model deployment in that instance are passed in the default parameter of the outer function of the closure. At run time, the score function uses the credentials and endpoint to send payload data received by the function on to the model.

wml_credentials = {
    "instance_id" : "4da73ecf-73da-83c7-13f8-123b95e78a03",
    "password"    : "72efa97c-84fb-835a-04f7-3d86b35dfe87",
    "url"         : "https://us-south.ml.cloud.ibm.com",
    "username"    : "8f4dce63-8d53-7e7a-cbad-f63e6792aebc"
}

model_deployment_endpoint_url = "https://../deployments/ad5e7ae2-4bc3-67e2-1d4c-a7db84624679/online"

ai_parms = { "wml_credentials" : wml_credentials,
             "model_deployment_endpoint_url" : model_deployment_endpoint_url }

def my_deployable_function( parms=ai_parms ):

    from watson_machine_learning_client import WatsonMachineLearningAPIClient
    client = WatsonMachineLearningAPIClient( parms["wml_credentials"] )
    
    def score( payload ):
    
        return client.deployments.score( parms["model_deployment_endpoint_url"], payload )

    return score

 

For more information about creating and using deployed functions, see these links: