Migrating from Watson Machine Learning API V4 Beta
As the Watson Machine Learning V4 API now released, if you previously used the Watson Machine Learning V4 Beta API for Decision Optimization, read here about some changes and improvements.
Important changes
- API keys and tokens
- Deployment spaces
- Software specifications
- Hardware specifications
- Other API changes
See also the API documentation for the new V4 API.
Note that the root name space for this API is now /ml/v4/
.
API keys and tokens
Authorization has now been simplified. Obtaining bearer tokens from IAM is now performed using a
generic user apikey
instead of a Watson Machine Learning specific apikey
. It is no longer
necessary to create specific credentials on the Watson Machine Learning instance.
Deployment spaces
In the Beta V4 API, all Watson Machine Learning usage was linked to some specific Watson Machine Learning instance. In the final API release, in addition to the Watson Machine Learning instance, deployment spaces are required. Spaces in Watson Machine Learning deployment are similar to projects in Watson Studio development.
Spaces allow you to group together all types of assets (data, models, deployments) which are related to the same problem or task all in one "bucket". To create a deployment space you also need to create a Cloud Object Storage (COS) instance. All of this can be done using the https://dataplatform.cloud.ibm.com user interface. You can create a deployment space,. Then view it and copy your Space ID from the settings tab. You can also do all this using the APIs (see Spaces).
Then in all API calls, you must pass the Space ID instead of the Instance ID, as shown in the following examples.
Software specifications
Another important improvement is the ability to better configure the software used when running your optimization models. Previously, you could only choose among predefined and non-configurable runtimes. Now software specifications allow you to precisely define not only the CPLEX version to be used, but also include additional extensions (such as using conda .yml files or custom libraries).
You can
use
the default specifications using their names do_12.9
or
do_12.10
.
{
"name": "Diet",
"description": "Diet model",
"type": "do-docplex_12.10",
"software_spec": {
"name": "do_12.10"
},
"space_id": "SPACE-ID-HERE"
}
For 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.
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 a "T-shirt size" parameter and the number of nodes parameter. More configuration capability is now provided through hardware specifications. Similarly to software specifications, you can list the existing ones or simply update your code to use the one of the default ones.
{
"name":"test-Diet-deploy",
"space_id":"SPACE-ID-HERE",
"asset": {
"id": "ASSET-ID-HERE"
},
"hardware_spec":{
"name":"S",
"num_nodes": 1
}
}
For more information, see REST API example.
Other API changes
- When uploading a model formulation, you must now set the URL parameter
content_format
tonative
. For example:curl --location --request PUT \ "https://us-south.ml.cloud.ibm.com/ml/v4/models/MODEL-ID-HERE/content?version=2020-08-01&space_id=SPACE-ID-HERE&content_format=native" \ -H "Authorization: bearer TOKEN-HERE" \ -H "ML-Instance-ID: MACHINE-LEARNING-SERVICE-GUID-HERE" \ -H "Content-Type: application/gzip" \ --data-binary '@diet.zip'
- The
jobs
endpoint is nowdeployment_jobs
. - In most queries, the
version
parameter must be included, for example:?version=2020-08-07
. - In some of the returned payloads (for example, when creating a model or a deployment) the
id
should be accessed usingid
instead of theguid
as previously.
What has not changed
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
.
If you are using the Python WatsonMachineLearningClient
package, you
should not have to change your code, but just use the new credentials of the new instance and space.
See also Python client examples.
Summary of the new flow
Remember that the root name space for this API is now /ml/v4/
.
- Create a Watson Machine Learning instance and COS instance, and create deployment space, using either the Watson Studio user interface or the API.
- Create your model in Watson Machine Learning, using
software_spec
and yourspace_id.
- Upload your model formulation setting
content_format
tonative
. - Create your deployment in Watson Machine Learning, using
hardware_spec
and yourspace_id
.
For more information, see REST API example.