Decision Optimization for Watson Machine Learning V4 final API

6 min readSep 2, 2020

Decision Optimization (DO) has been available in Watson Machine Learning (WML) for almost one year now. As optimization models requires some specific asynchronous usage, during this period, some specific new v4 APIs from WML have been necessary to deploy and use optimization models.

These beta v4 APIs will have a final release this summer. It will bring some functional improvements, including the ability to deploy models and create jobs from the Watson Studio User Interface, but will also require some changes and adaptations in the code using it, that we try to summarize here. These changes apply to the newly created Lite plans and the to the new v2 Standard and Professional plans.

We will first describe the important changes in details and quickly comment about the smaller ones. Then we will summarize the modified flow of actions.

New WML instances

All what is described in this post is applying to the new WML instances introduced on September 4th. You can see other new non DO-related improvements on this what’s new page.

You will need to create a new v2 instance or upgrade your current v1 instances to benefit from these enhancements. The existing v1 instances will continue to use the previous APIs.

Important changes

The important topics are:

apikeys and tokens
deployment spaces
software specifications
hardware specifications
other smaller API changes

A documentation of this final REST API is available here: https://cloud.ibm.com/apidocs/machine-learning

Note that the root name space for this API is now /ml/v4/.

apikeys and tokens.

A first simplification is on authorization. Getting bearer tokens from IAM is now done using a generic user apikey instead of a WML specific apikey. It is hence not necessary to create specific credentials on the WML instance.

Be careful that we do refer to apikey and not serviceId. This is the option you can access in cloud.ibm.com as shown below.

Deployment Spaces.

In beta V4 API, all WML usage was linked to some specific WML instance. In the final API release, in addition to WML instance, deployment spaces are introduced. Spaces are the equivalent for WML deployment of what projects are for WS development.

Spaces allow to group under a given bucket all types of assets (data, models, deployments) which are related to the same problem or task. You can create several spaces to organized the models and assets you deploy to be used in different production contexts or applications.

As a consequence, to deploy and use an optimization model, you will not only need a WML instance as before, but also a WML space. Also, in order to create a space you will need a Cloud Object Storage (COS) instance to store all the different assets which get added to the space. For ease of use, all this can now be done using user interface as previously in the private cloud version of Cloud Pak for Data.

But you can also do all this using spaces REST APIs (see https://cpd-spaces-api.eu-gb.cf.appdomain.cloud/#/Spaces/spaces_create). In the payload of this API you will need the crn (Cloud Resource Name) for the WML and COS instance. One simple way to get access to these is to use the ibmcloud tool.

As you are now promoting models or assets and creating deployments in a given space, in most REST API calls, the space_id identifying the space has to be passed in place of instance_id, as you will see in the following examples.

Software Specifications

Another important improvement is the ability to better configure the software used when running your optimization models. Before, you could only choose among predefined and not configurable runtimes. Now software specifications allow to precisely define not only the CPLEX version to be used but also include additional extensions (e.g. using conda yml files or custom libraries).

You might get the list of existing predefined software specifications using https://api.dataplatform.dev.cloud.ibm.com/v2/environments/docs/swagger/#/Software%20Specifications/software_specifications_list or simply use default specifications using their names do_12.9 or do_12.10.

As a consequence the payload to create a model will now look like:

{
    "name":"Diet22",
    "description":"Diet",
    "type":"do-docplex_12.10",
    "software_spec":{
        "name":"do_12.10"
    },
    "space_id":"d6cc3c2c-8ed7-435e-bdd5-aad7e99783df"
}

For a more advanced usage, and to configure additional software which will be available for your model execution, you can derive existing software specifications and add some package extensions. See more details here: https://api.dataplatform.dev.cloud.ibm.com/v2/environments/docs/swagger/#/

Hardware Specifications

After the model is created and the formulation uploaded, one or several deployments are created that can be called from a production application. Deployments used to be configured with T Shirt size and number of nodes parameters. More configuration capability is now provided through Hardware specifications. Just as for software specifications, you can list the existing ones or simply update your code to use the one of the default ones.

The payload to deploy a model will now look like:

{
    "name":"test-Diet-deploy",
    "space_id":"d6cc3c2c-8ed7-435e-bdd5-aad7e99783df",
    "asset": {
        "id": "baa56ac4-c8f4-4e0a-aa54-ce7e1dd8fbb4"
    },
    "hardware_spec":{
        "name":"S",
        "num_nodes": 1
    }
}

Other smaller changes

Uploading model formulation

When uploading a model formulation, you know need to set the url parameter content_format as native. For example:

curl --location --request PUT 'https://wml-fvt.ml.test.cloud.ibm.com/ml/v4/models/baa56ac4-c8f4-4e0a-aa54-ce7e1dd8fbb4/content?version=2020-08-01&space_id=d6cc3c2c-8ed7-435e-bdd5-aad7e99783df&content_format=native' \
--header 'Authorization: Bearer XXX' \
--header 'ML-Instance-ID: ML_INSTANCE' \
--header 'Content-Type: application/gzip' \
--data-binary '@Diet8.zip'

Root name space

Note that the root name space for this API is now /ml/v4/.

Jobs endpoint

The end point for jobs is now deployment_jobs.

Version

In most queries, an additional query parameter is mandatory to state the version, e.g. ?version=2020-08-07 .

Returned payloads

In some of the returned payloads (e.g. when creating a model or a deployment) the id should be accessed using id instead of guid as before.

Billing

Rounding now on job duration (1s), leading to 30 sec CUH.

Creating and running Jobs does not change

After you have deployed your model and created your deployment, you create jobs with input and output data has not changed. The payload for this has not changed, except that you need to pass the space_id instead of the instance_id.

Python Client

If you were using the Python Client, and want to use v2 instances, you might want to switch to the new client:

pip install ibm-watson-machine-learning

Only minimal changes are required from:

from watson_machine_learning_client import WatsonMachineLearningAPIClient
client = WatsonMachineLearningAPIClient(wml_credentials)

changes to

from ibm_watson_machine_learning import APIClient
client = APIClient(wml_credentials)

And set the space using the set_default_space() API.

You can refer to the gallery example notebook which has been updated.

You might also look at this complete post about how to migrate your python code for DO in WML v2 instances.

Summary of the new flow

Here is a summary of the modified flow, identifying the main changes.

Remember that the root name space for this API is now /ml/v4/!

create WML and COS instance, and create WML space, using UI or API.
create your model in WML, using software_spec, space_id and version_id.
upload your model formulation setting content_format as native
create your deployment in WML, using hardware_spec, space_id and version_id.
create and monitor jobs using space_id and version_id.

To create the instances (WML and COS), use https://cloud.ibm.com.

To create the deployment space you can use Watson Studio, associating the new instance and then creating the space.

Schedule

Starting September 1st, Lite Plan users will not be able to create new models or new deployments on their existing instances using the beta v4 API. But existing deployments can still be used with beta v4 during 1 month.

Standard and Professional will continue to have access to beta v4 API through the migration period.

https://twitter.com/AlainChabrier

https://www.linkedin.com/in/alain-chabrier-5430656/