Work with Oracle Machine Learning ONNX Format Models

Open Neural Network Exchange or ONNX is an open standard format of machine learning models. By using the Oracle Machine Learning Services REST API, you can deploy and score with your ONNX format models.

The REST API is exposed as part of the Oracle Machine Learning Services on Oracle Autonomous AI Database cloud service. The Oracle Machine Learning Services REST API supports ONNX format model deployment through REST endpoints for:

• Classification models (both non-image models and image models)
• Clustering models
• Features Extraction models (image models)
• Regression models

Before deploying your ONNX format model, ensure the following:

• Create the ONNX model zip file containing the modelName.onnx file, metadata.json file, and label.txt (optional) file.
• Ensure that the metadata.json file contains the following as listed in the table Contents and Description of metadata.json file in Deploy ONNX Format Models.

The Linux utility jq can be used to parse the JSON output into a readable format. The jq utility is included in all the major Linux distributions repositories. On Oracle Linux and Red Hat systems, it is installed by using the command:

$ sudo yum install jq

Note:

Using jq in the cURL command does not return the HTTP response. To return HTTP response, remove jq and add the -i flag to the curl command.

1: Get a List of All Saved Models

This example demonstrates how to get the list of models that are visible to the caller and that satisfy the optional modelName, version, and namespace parameters.

Run the following cURL command:

curl -X GET --header "Authorization: Bearer $token" "<oml-cloud-service-location-url>/omlmod/v1/models" | jq

Note:

Only shared models and models created by the caller are visible to the caller.

The command returns the following information:

{
  "items": [
    {
      "version": "1.5",
      "modelType": "OML",
      "createdBy": "OMLUSER",
      "modelId": "1b6fed66-bacb-48c7-8549-14542abe2a82",
      "modelName": "GLM_MOD",
      "links": [
        {
          "rel": "self",
          "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/1b6fed66-bacb-48c7-8549-14542abe2a82"
        }
      ],
      "namespace": "OML_MODELS",
      "shared": true,
      "storedOn": "2020-11-16T20:43:28.733Z"
    },
	...
	...
	
    }
  ]
}

2: Get a list of Models Filtered by Model Name

This example demonstrates how to get the list of models filtered by the model name sk_cl_iris

Run the following cURL command:

curl -X GET --header "Authorization: Bearer $token" "<oml-cloud-service-location-url>/omlmod/v1/models?modelName=sk_cl_iris" | jq

The command returns the following information about the model sk_cl_iris :

{
  "items": [
    {
      "version": "1.0",
      "modelType": "OML",
      "createdBy": "OMLUSER",
      "modelId": "bc5cf626-d4f6-45ba-8a50-c3e57a008bd7",
      "modelName": "sk_cl_iris",
      "links": [
        {
          "rel": "self",
          "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/bc5cf626-d4f6-45ba-8a50-c3e57a008bd7"
        }
      ],
      "namespace": "OML_MODELS",
      "shared": true,
      "storedOn": "2020-11-06T22:16:29.387Z"
    },
	...
	...
    }
  ]
}

3: Get a List of Models Filtered by Version and Namespace

This example demostrates how to get the list of models filtered by version=1.0 and namespace=ONNX_MODELS

Run the following cURL command:

curl -X GET --header "Authorization: Bearer $token" "<oml-cloud-service-location-url>/omlmod/v1/models?version=1.0&namespace=ONNX_MODELS" | jq

The command returns the following information:

{
  "items": [
    {
      "version": "1.0",
      "modelType": "ONNX",
      "createdBy": "OMLUSER",
      "modelId": "e667cbb3-9887-4dee-96a6-203403804269",
      "modelName": "onnxTitanicModel",
      "links": [
        {
          "rel": "self",
          "href": "https://adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/e667cbb3-9887-4dee-96a6-203403804269"
        }
      ],
      "namespace": "ONNX_MODELS",
      "shared": true,
      "storedOn": "2020-11-10T17:17:27.792Z"
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models"
    }
  ]
}

4: Store an ONNX Format Model

This example demonstrates how to store an ONNX format model in the repository. A unique modelId is assigned to the stored model, and the creator of the model is assigned from the access token used to authorize the request. This method takes the binary data for model, model name, description, model version, model type, shared, and model namespace as inputs.

Run the following cURL command:

curl -X POST --header "Authorization: Bearer $token" \
<oml-cloud-service-location-url>/omlmod/v1/models \
--header 'content-type: multipart/form-data; boundary=Boundary' \
--form modelData=@sk_cl_iris_onnx.zip \
--form modelName=sk_cl_iris \
--form modelType=ONNX \
--form 'description=Saving ONNX ML model' \
--form 'namespace=ONNX_MODELS' \
--form version=1.0 \
--form shared=true  | jq

The command stores the model in the repository, generates the unique modelId, and provides the URL of the repository where the model is stored, as shown in the message below:

{
  "modelId": "fdbbde68-9d36-48d7-837d-08ac9d4d6172",
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172"
    }
  ]
}

5: Create an ONNX Format Model Scoring Endpoint

This example demonstrates how to create an ONNX format model scoring endpoint identified by modelId and URI.

Run the following cURL command and provide the modelId and URI:

curl -X POST "<oml-cloud-service-location-url>/omlmod/v1/deployment" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${token}" \
--data '{
"modelId":"fdbbde68-9d36-48d7-837d-08ac9d4d6172",
"uri":"sk_cl_iris"
}' | jq

The command creates the model scoring endpoint, and returns the following information:

{
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/deployment/sk_cl_iris"
    }
  ],
  "modelId": "fdbbde68-9d36-48d7-837d-08ac9d4d6172",
  "uri": "sk_cl_iris",
  "deployedOn": "2020-11-17T01:38:45.724Z"

6: Get ONNX Format Model Endpoint Details

This example demonstrates how to get the model endpoint details of an ONNX format model identified by the model URI.

Run the following cURL command:

curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris" \
--header "Authorization: Bearer ${token}" | jq

In this example, sk_cl_iris is the URI:

The command returns the following details:

{
  "version": "1.0",
  "modelType": "ONNX",
  "createdBy": "OMLUSER",
  "modelId": "fdbbde68-9d36-48d7-837d-08ac9d4d6172",
  "description": "Saving ONNX ML model",
  "modelName": "sk_cl_iris",
  "metadata": {
    "miningFunction": "CLASSIFICATION",
    "algorithm": "ONNX",
    "onnxAttributes": [
      {
        "name": "float_input",
        "attributeType": "FLOAT",
        "shape": [
          1,
          4
        ]
      }
    ],
    "outputs": [
      {
        "name": "output_label",
        "attributeType": "INT64"
      },
      {
        "name": "output_probability",
        "attributeType": "FLOAT"
      }
    ],
    "modelName": "sk_cl_iris"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/deployment/sk_cl_iris"
    }
  ],
  "namespace": "ONNX_MODELS",
  "shared": true,
  "uri": "sk_cl_iris",
  "deployedOn": "2020-11-17T01:38:45.724Z"
}

7: Get ONNX Format Model Information

This example demonstrates how to get ONNX format model information identified by the modelId.

Run the following cURL command:

curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172" \
--header "Authorization: Bearer ${token}" | jq

The command returns the following information:

{
  "version": "1.0",
  "modelType": "ONNX",
  "createdBy": "OMLUSER",
  "modelId": "fdbbde68-9d36-48d7-837d-08ac9d4d6172",
  "description": "Saving ONNX ML model",
  "modelName": "sk_cl_iris",
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172"
    }
  ],
  "namespace": "ONNX_MODELS",
  "shared": true,
  "storedOn": "2020-11-17T01:33:39.266Z"
}

8: Get ONNX Format Model Metadata

This example demonstrates how to get the model metadata of an ONNX format model identified by the modelId.

Run the following cURL command:

curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172/metadata" \
--header "Authorization: Bearer ${token}" | jq

In this example, fdbbde68-9d36-48d7-837d-08ac9d4d6172 is the modelId.

The command returns the following information:

{
  "miningFunction": "CLASSIFICATION",
  "algorithm": "ONNX",
  "onnxAttributes": [
    {
      "name": "float_input",
      "attributeType": "FLOAT",
      "shape": [
        1,
        4
      ]
    }
  ],
  "outputs": [
    {
      "name": "output_label",
      "attributeType": "INT64"
    },
    {
      "name": "output_probability",
      "attributeType": "FLOAT"
    }
  ],
  "modelName": "sk_cl_iris"
}

9: GET ONNX Format Model Scoring REST API

This example demonstrates how to get the Open API specification for an ONNX format model identified by the URI. This API defines the input and output format and is based on the metadata extracted from the model when it was deployed to the model repository. The Open API specification is only visible for shared endpoints and endpoints created by the caller.

Run the following cURL command:

curl -i -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris/api" \
--header "Authorization: Bearer ${token}"

In this example, sk_cl_iris is the URI. The command returns the Open API specification:

HTTP/1.1 200 OK
Date: Thu, 12 Nov 2021 19:42:28 GMT
Content-Type: application/json
Content-Length: 3990
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: X-Requested-With, Content-Type

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "sk_cl_iris",
    "description" : "Saving ONNX ML model",
    "version" : "1.0"
..
..

10: Score with ONNX Format Model (Mini-batch of Two Records)

This example demonstrates how to score with an ONNX format model comprising a mini-batch of two records.

Run the following cURL command:

curl -X POST "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris/score" \
--header "Authorization: Bearer ${token}" \
--header 'Content-Type: application/json' \
--data '{"inputRecords": [{"float_input": [[4.8, 7.2, 5.3, 2.4]]}]}' | jq

The command returns the following scoring results:

{
  "scoringResults": [
    {
      "classifications": [
        {
          "label": "0",
          "probability": 0
        },
        {
          "label": "1",
          "probability": 0
        },
        {
          "label": "2",
          "probability": 1.0000001192092896
        }
      ]
    }
  ]
}

11: Delete ONNX Format Model Scoring Endpoint

This example demonstrates how to delete an ONNX format model scoring endpoint identified by the URI.

Run the following cURL command:

curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris" \
--header "Authorization: Bearer ${token}"

In this example, sk_cl_iris is the URI. The command deletes the model endpoint and returns the following information:

HTTP/1.1 204 No Content
Date: Tue, 17 Nov 2021 01:45:00 GMT
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: X-Requested-With, Content-Type

12: Delete ONNX Format Model

This example demonstrates how to delete an ONNX format model identified by the modelId.

Run the following cURL command:

curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172" \
--header "Authorization: Bearer ${token}"

In this example, fdbbde68-9d36-48d7-837d-08ac9d4d6172 is the modelId.

The command deletes the model and returns the following information:

HTTP/1.1 204 No Content
Date: Tue, 17 Nov 2021 01:45:36 GMT
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: X-Requested-With, Content-Type