Watson Machine Learning API changes from V3 to V4
The V4 version of the Watson Machine Learning REST API and Watson Machine Learning Python client library have some significant differences from the v3 version and from the V4 beta version. The V4 library supports a range of new functionality, including deployment spaces and software specifications.
Refer to this list of changed and deprecated fields and parameters in the Watson Machine Learning API when upgrading an asset from a previous release.
API changes for Watson Machine Learning
These changes support new features and functionality.
General changes
- The Python package name has changed to
ibm_watson_machine_learning
. - The link for the Python client library documentation has changed from https://wml-api-pyclient-dev-v4.mybluemix.net/ to http://ibm-wml-api-pyclient.mybluemix.net to reflect the general availability of the new library and APIs.
- All Watson Machine Learning /v4/ APIs will be moved to /ml/v4/.
- /v4/spaces will be moved to the platform /v2/spaces.
- The
version
query parameter is mandatory on every API call. - All API methods require an associated space or project.
- Authorization has changed from being IAM authorization of the Watson Machine Learning instance to membership of the associated space or project.
- These operations have the return code changed from 200 to 204:
- /ml/v4/models/{model_id}/content
- /ml/v4/functions/{function_id}/code
- The
guid
field is no longer supported in metadata - useid
instead. - Runtimes and libraries have been removed and are replaced by environments with software specifications and hardware specifications.
- The
role
field is removed from the metadata for all assets. - The content of compressed files is no longer inspected by the V4 repository. Instead the file is streamed directly to CAMS. This means that schemas are not read from the function compressed file and must be set explicitly if needed. Automatic decoding of the PMML model in order to autofill some fields for the Watson Machine Learning model will no longer work and these fields need to be explicitly set in the Watson Machine Learning model if needed.
- The
import
field will be removed from the model and pipeline payload. Create revision
now supports a commit_message.- The
content_status
andcontent_formats
fields have been removed from the model. - It is now possible to list all model content using
/ml/v4/models/{model_id}/content
. - Model content can be downloaded by id using
/ml/v4/models/{model_id}/content/{attachment_id}
and downloaded by search/ml/v4/models/{model_id}/download
. - Upload and download of function content has changed to the path
/ml/v4/functions/{function_id}/code
and/ml/v4/functions/{function_id}/code
.
Deployment spaces
Creating deployments requires that you have a deployment space, where you can organize all of the assets required for the deployment, including data sources and software specifications. These changes relate to accessing and using spaces.
- When querying a space, the
assets
array in the space resource is no longer supported. Instead, use the assets API to get the assets. - The resource references
project
andspace
in request payloads is no longer supported. Instead, useproject_id
andspace_id
string fields. - The fields
name
,description
,project_id
,space_id
andtags
are all deprecated. They will exist only in the metadata and not the response body. - Tags have not only been moved to the metadata for responses but they are now an array of strings. This applies to the tags that are set in the request payload as well as the tags in the metadata.
- The
space_id
is now a mandatory query parameter for all APIs. The only exception is when usingPOST
to create a resource. In this case,space_id
is part of the request payload. Note that for Watson Machine Learning resources that can be stored in a project or a space, you must specify eitherspace_id
orproject_id
. - The
version
query parameter can be set on all APIs. - The space and project object in the post payload will be replaced by
space_id
andproject_id
. - The
tags
field will be an array of string.
Deployment jobs
- In /v4/deployment_jobs the supported fields are
input_data
,input_data_reference
andoutput_data_reference
. Theinput_data
is meant for inline payload and the output will only be sent toscoring.prediction
s even thoughoutput_data_reference
is given, it won’t be persisted inoutput_data_reference
. Theoutput_data_reference
is only used wheninput_data_reference
is given. Theoutput_data_reference
field will be always used if set. - When referencing a Watson Machine Learning resource in a request payload,
href
is no longer supported. Instead, useid
and an optionalrev
. - Using
href
injobs_entity_request
to reference a deployment is no longer supported. Instead, useid
. - The
parent
object in the metadata has been replaced by theparent_id
string field in the metadata.
Deep learning models
- The following fields are deprecated and replaced by
model_definition
:training_lib
in Models resourcetraining_lib
in Experiments resource (training_references[].training_lib
)training_lib_href
in Pipelines resource (document.pipelines[].nodes[].parameters.training_lib_href
)
Search
- All search APIs use the
offset
query parameter instead ofstart
. Note that the next field can still be used by calling that url directly rather than setting the start parameter and that offset can be used to specify a numerical offset for offset based pagination. - You cannot search by custom fields; use tags instead for searching.
-
Use this format to search for custom parameters:
/v4/....?custom[name]=model&custom[size]=2
Storing an existing model with the new client might require metadata change
A change in functionality for the Python client requires that INPUT_DATA_SCHEMA meta property should be given in a list instead of a dictionary as it now supports multiple input data schemas.
If you stored a model in an earlier version of the Python client, and the model is stored with INPUT_DATA_SCHEMA meta property, when you upgrade and store it again, you must update the meta properties for the model, or the storage operation will fail with this message:
Unexpected type of 'meta_props.inputDataSchema', expected: '<class 'list'>', actual: '<class 'dict'>'.
For example, if your metadata is structured like this:
"id": "stest",
"type": "list",
"fields": [
{"name": "pregnancies", "type": "integer"},
{"name": "glucose", "type": "integer"},
{"name": "diastolic", "type": "integer"},
{"name": "triceps", "type": "integer"},
{"name": "insulin", "type": "integer"},
{"name": "bmi", "type": "float"},
{"name": "dpf", "type": "float"},
{"name": "age", "type": "integer"}
]
}
Change the metadata to use an array. For example:
"input_data_schema": [{
"id": "stest",
"type": "list",
"fields": [
{"name": "pregnancies", "type": "integer"},
{"name": "glucose", "type": "integer"},
{"name": "diastolic", "type": "integer"},
{"name": "triceps", "type": "integer"},
{"name": "insulin", "type": "integer"},
{"name": "bmi", "type": "float"},
{"name": "dpf", "type": "float"},
{"name": "age", "type": "integer"}
]
}]
Changes from the V4 Python client beta
Note these changes from the beta version of the V4 Python client to the generally available version.
Description | Beta python client package usage | New python client package usage |
---|---|---|
Package to install | !pip install watson-machine-learning-client-V4 |
!pip install ibm-watson-machine-learning |
Import statement | from watson_machine_learning_client import WatsonMachineLearningAPIClient |
‘from ibm_watson_machine_learning import APIClient` |
Client instance creation statement | client = WatsonMachineLearningAPIClient(wml_credentials) |
client = APIClient(wml_credentials) |
Package versions | Package version 1.0.99 or higher (Latest version is 1.0.115) | Use version 1.0.9 or higher |
Documentation | https://wml-api-pyclient-dev-v4.mybluemix.net/ | http://ibm-wml-api-pyclient.mybluemix.net |
Accessing the Python client for a “v1” service instance
How you interact with assets developed using a v1 machine learning service instance depends on the type of plan you use.
Accessing the Python client for a “v1” service instance for a Lite user
If you are a Lite plan user, your v1 machine learning service instance is automatically migrated to a v2 service instance and unmigrated assets will be read only. Use these credentials to access v1 assets. Note: to access assets developed with the v1 service instance, you must import and use the V3 or v4-beta APIs.
wml_credentials = {
"apikey":"123456789",
"url": " https://HIJKL",
"instance_id": "v1 lite instance_id"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)
Accessing the Python client for a “v1” service instance for a standard/professional user
For standard and professional plan users, during the migration period, you can still access assets trained and deployed using the deprecated v1 service instance and you can create new assets. Use these credentials to access or create v1 assets. Note: to access assets developed with the v1 service instance, you must import and use the V3 or v4-beta APIs.
wml_credentials = {
"apikey":"123456789",
"url": " https://HIJKL",
"instance_id": "v1 standard instance_id"
}
from ibm_watson_machine_learning import APIClient
wml_client = APIClient(wml_credentials)
Migrating Python functions
After migrating your assets, you must manually update the score()
function of Python functions to match the new format. Follow the steps in Migrating Python functions.