Work with Oracle Machine Learning ONNX Image 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 image models.

The REST API is exposed as part of the Oracle Machine Learning Services on Oracle Autonomous 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) and Feature Extraction models (image models).

Before deploying your ONNX image 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 command and add the -i flag to the curl command.

This topic lists the following examples to:

List all saved models
Get the list of models filtered by namespace=ONNX_IMG
Store ONNX Image model
Create ONNX Image endpoint
Get ONNX Image Model Details
GET ONNX Image Scoring REST API
Score ONNX Image model
Delete ONNX Image endpoint
Delete ONNX Image model

1: List 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.

Note:

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

Run the following cURL command to get the list of all saved models:

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

The command returns the following information:

{
  "items": [
    {
      "version": "1.5",
      "modelType": "OML",
      "createdBy": "OMLUSER",
      "modelId": "1b6fed66-bacb-48c7-8549-14542abe2a82",
      "modelName": "OML_Insurance_Affinity",
      "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": "2021-11-16T20:43:28.733Z"
    },
    {
      "version": "1.4",
      "modelType": "ONNX",
      "createdBy": "OMLUSER",
      "modelId": "228707fa-218a-4fb9-b1e7-bc111059a04f",
      "modelName": "onnxTitanicModel",
      "links": [
        {
          "rel": "self",
          "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/228707fa-218a-4fb9-b1e7-bc111059a04f"
        }
      ],
      "namespace": "ONNX_MODELS",
      "shared": true,
      "storedOn": "2021-11-16T21:07:13.291Z"
    },
...
...
}
  ]
}

2: Get the List of Models Filtered by Namespace

This example demonstrates how to get the list of models filtered by the namespace ONNX_IMG.

Run the following cURL command to get the list of models filtered by namespace=ONNX_IMG:

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

The command returns the following information:

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

3: Store ONNX Format Image Model

This example demonstrates how to store an ONNX format image model in the Oracle Machine Learning 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.

Run the following cURL command to store an ONNX image model. You must provide the binary data for the model, model name, description, model version, model type, shared, and model namespace as inputs.

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=@squeezenet_onnx.zip \
--form modelName=squeezenet_onnx \
--form modelType=ONNX_IMG \
--form 'description=Saving ONNX ML model' \
--form 'namespace=ONNX_IMG' \
--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": "ea37b82a-d25a-45d2-9fcc-c4e4b478de78",
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/models/ea37b82a-d25a-45d2-9fcc-c4e4b478de78"
    }
  ]
}

4: Create ONNX Format Image Endpoint

This example demonstrates how to create an ONNX format image model endpoint identified by the modelId. The provided URI must be unique and will be assigned to the endpoint.

Run the following cURL command to create an ONNX format image model endpoint:

curl -X POST "<oml-cloud-service-location-url>/omlmod/v1/deployment" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${token}" \
--data '{
"modelId":"ea37b82a-d25a-45d2-9fcc-c4e4b478de78",
"uri":"squeezenet_onnx"
}' | jq

In this example, ea37b82a-d25a-45d2-9fcc-c4e4b478de78 is the modelId and squeezenet_onnx is the URI.

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

{
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/deployment/squeezenet_onnx"
    }
  ],
  "modelId": "ea37b82a-d25a-45d2-9fcc-c4e4b478de78",
  "uri": "squeezenet_onnx",
  "deployedOn": "2021-11-17T01:59:22.303Z"
}

5: Get ONNX Image Model Details

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

Run the following cURL command to get the details of the ONNX model:

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

In this example, squeezenet_onnx is the model name.

The command returns the following details about the model:

{
  "version": "1.0",
  "modelType": "ONNX_IMG",
  "createdBy": "OMLUSER",
  "modelId": "ea37b82a-d25a-45d2-9fcc-c4e4b478de78",
  "description": "Saving ONNX ML model",
  "modelName": "squeezenet_onnx",
  "metadata": {
    "miningFunction": "CLASSIFICATION",
    "algorithm": "ONNX",
    "onnxAttributes": [
      {
        "name": "data_0",
        "attributeType": "FLOAT",
        "shape": [
          1,
          3,
          224,
          224
        ]
      }
    ],
    "outputs": [
      {
        "name": "softmaxout_1",
        "attributeType": "FLOAT"
      }
    ],
    "labels": [
      "n01440764 tench, Tinca tinca",
      "n01443537 goldfish, Carassius auratus",
      "n01484850 great white shark, white shark, man-eater, man-eating shark, Carcharodon carcharias",
      "n01491361 tiger shark, Galeocerdo cuvieri",
      "n01494475 hammerhead, hammerhead shark",
      "n01496331 electric ray, crampfish, numbfish, torpedo",
      "n01498041 stingray",...
	  ...
	  ...
	     ],
    "modelName": "squeezenet_onnx"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://qtraya2braestch-omldb.adb.us-sanjose-1.oraclecloudapps.com/omlmod/v1/deployment/squeezenet_onnx"
    }
  ],
  "namespace": "ONNX_IMG",
  "shared": true,
  "uri": "squeezenet_onnx",
  "deployedOn": "2021-11-17T01:59:22.303Z"
}

6: GET ONNX Format Image Scoring REST API

This example demonstrates how to get the Open API specification for an ONNX format image 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 to get the ONNX format image scoring REST API:

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

In this example, squeezenet_onnx is the URI.

The command returns the Open API specification:

HTTP/1.1 200 OK
Date: Thu, 12 Nov 2021 19:55:42 GMT
Content-Type: application/json
Content-Length: 4679
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" : "squeezenet_onnx",
    "description" : "Saving ONNX ML model",
    "version" : "1.0"
  },

..
..

7: Score with ONNX Format Image Model

This example demonstrates how to score with an ONNX format image model identified by the URI.

Run the following cURL command to score with the ONNX image model:

curl -X POST "<oml-cloud-service-location-url>/omlmod/v1/deployment/squeezenet_onnx/score" \
--header "Authorization: Bearer ${token}" \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--form "imageData=@dog-kitten.jpg"

In this example, squeezenet_onnx is the URI.

The command returns the following scoring results:

{
  "scoringResults": [
    {
      "classifications": [
        {
          "label": "n01440764 tench, Tinca tinca",
          "probability": 1.2603611730666042e-12
        },
        {
          "label": "n01443537 goldfish, Carassius auratus",
          "probability": 3.403307843874437e-11
        },
        {
          "label": "n01484850 great white shark, white shark, man-eater, man-eating shark, Carcharodon carcharias",
          "probability": 3.984535618117846e-11
        },
        {
          "label": "n01491361 tiger shark, Galeocerdo cuvieri",
          "probability": 3.584859839533827e-11
        },
        {
          "label": "n01494475 hammerhead, hammerhead shark",
          "probability": 4.4141756916360464e-10
        },
        {
          "label": "n01496331 electric ray, crampfish, numbfish, torpedo",
          "probability": 2.612540461743862e-10
        },
        {
          "label": "n01498041 stingray",
          "probability": 4.751101313586747e-13
        },
	...
	...
	
	        }
      ]
    }
  ]
}

8: Delete ONNX Image Model Endpoint

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

Run the following cURL command to delete an ONNX image model endpoint:

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

In this example, squeezenet_onnx 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 02:03:48 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

9: Delete ONNX Image Model

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

Run the following cURL command to delete an ONNX image model:

curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/models/ea37b82a-d25a-45d2-9fcc-c4e4b478de78" \
--header "Authorization: Bearer ${token}"

In this example, ea37b82a-d25a-45d2-9fcc-c4e4b478de78 is the modelId.

The command returns the following information:

HTTP/1.1 204 No Content
Date: Tue, 17 Nov 2021 02:04:35 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