1. Oracle Machine Learning ServicesのREST API
  2. Oracle Machine LearningのONNXイメージ・モデルの使用

Oracle Machine LearningのONNXイメージ・モデルの使用

Open Neural Network Exchange (ONNX)は、機械学習モデルのオープン・スタンダードな形式です。Oracle Machine Learning ServicesのREST APIを使用することで、ONNX形式イメージ・モデルを使用してデプロイおよびスコアリングできます。

REST APIは、Oracle Autonomous Databaseクラウド・サービス上のOracle Machine Learning Servicesの一部として公開されます。Oracle Machine Learning ServicesのREST APIでは、RESTエンドポイントによる、分類モデル(イメージ以外のモデルとイメージ・モデルの両方)と特徴抽出モデル(イメージ・モデル)のONNX形式モデルのデプロイメントがサポートされています。

ONNXイメージ・モデルをデプロイする前に、次のことを確実に行ってください。
  • modelName.onnxファイル、metadata.jsonファイルおよびlabel.txt(オプション)ファイルを含むONNXモデルzipファイルを作成します。
  • 「ONNX形式モデルのデプロイ」の「metadata.jsonファイルの内容と説明」の表に示されているように、metadata.jsonファイルに次のものが含まれていることを確認します。
Linuxユーティリティjqを使用して、JSON出力を読取り可能な形式に解析できます。jqユーティリティは、主要なLinux配布リポジトリのすべてに含まれています。Oracle LinuxおよびRed Hatシステムでは、次のコマンドを使用してインストールされます。 
$ sudo yum install jq

ノート:

cURLコマンドでjqを使用しても、HTTPレスポンスは返されません。HTTPレスポンスを返すには、jqコマンドを削除し、curlコマンドに-iフラグを追加します。
このトピックでは、次の例を示します。
  • すべての保存済モデルのリスト
  • namespace=ONNX_IMGでフィルタされたモデルのリストの取得
  • ONNXイメージ・モデルの格納
  • ONNXイメージ・エンドポイントの作成
  • ONNXイメージ・モデル詳細の取得
  • ONNXイメージ・スコアリングREST APIの取得
  • ONNXイメージ・モデルのスコアリング
  • ONNXイメージ・エンドポイントの削除
  • ONNXイメージ・モデルの削除

1: すべての保存済モデルのリスト

この例では、コール元に表示され、オプションのmodelName、versionおよびnamespaceパラメータを満たすモデルのリストを取得する方法を示します。

ノート:

コール元に表示されるのは、共有モデルおよびコール元が作成したモデルのみです。
次のcURLコマンドを実行して、すべての保存済モデルのリストを取得します。 
curl -X GET --header "Authorization: Bearer ${token}" "<oml-cloud-service-location-url>/omlmod/v1/models"
このコマンドは、次の情報を返します。 
{
  "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: ネームスペースでフィルタされたモデルのリストの取得

この例では、ネームスペースONNX_IMGでフィルタされたモデルのリストを取得する方法を示します。

次のcURLコマンドを実行して、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
このコマンドは、次の情報を返します。 
{
  "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: ONNX形式イメージ・モデルの格納

この例では、ONNX形式のイメージ・モデルをOracle Machine Learningリポジトリに格納する方法を示します。格納されたモデルには一意のmodelIdが割り当てられ、モデルの作成者はリクエストの認可に使用されたアクセス・トークンから割り当てられます。

次のcURLコマンドを実行して、ONNXイメージ・モデルを格納します。モデル、モデル名、説明、モデル・バージョン、モデル・タイプ、共有およびモデル・ネームスペースのバイナリ・データを入力として指定する必要があります。 
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
このコマンドは、次のメッセージに示すように、モデルをリポジトリに格納し、一意のmodelIdを生成し、モデルが格納されているリポジトリのURLを提供します。 
{
  "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: ONNX形式イメージ・エンドポイントの作成

この例では、modelIdで識別されるONNX形式のイメージ・モデル・エンドポイントを作成する方法を示します。指定されたURIは一意である必要があり、エンドポイントに割り当てられます。

次のcURLコマンドを実行して、ONNX形式のイメージ・モデル・エンドポイントを作成します。 
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

この例では、ea37b82a-d25a-45d2-9fcc-c4e4b478de78がmodelIdで、squeezenet_onnxがURIです。

このコマンドは、エンドポイントを作成し、次の情報を返します。 
{
  "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: ONNXイメージ・モデル詳細の取得

この例では、モデルURIで識別されるONNX形式イメージ・モデルのモデル詳細を取得する方法を示します

次のcURLコマンドを実行して、ONNXモデルの詳細を取得します。 
curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/squeezenet_onnx" \
--header "Authorization: Bearer ${token}" | jq

この例では、squeezenet_onnxがモデル名です。

このコマンドは、モデルに関する次の詳細を返します。 
{
  "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: ONNX形式イメージ・スコアリングREST APIの取得

この例では、URIで識別されるONNX形式イメージ・モデルのOpen API仕様を取得する方法を示します。このAPIは、入力および出力形式を定義し、モデル・リポジトリへのデプロイ時にモデルから抽出されたメタデータに基づきます。Open API仕様は、共有エンドポイントおよびコール元によって作成されたエンドポイントに対してのみ表示されます。

次のcURLコマンドを実行して、ONNX形式のイメージ・スコアリングREST APIを取得します。 
curl -i -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/squeezenet_onnx/api" \
--header "Authorization: Bearer ${token}"

この例では、squeezenet_onnxがURIです。

このコマンドは、Open API仕様を返します。 
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: ONNX形式イメージ・モデルによるスコアリング

この例では、URIで識別されるONNX形式のイメージ・モデルを使用してスコアリングする方法を示します。

次のcURLコマンドを実行して、ONNXイメージ・モデルでスコアリングします。 
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"

この例では、squeezenet_onnxがURIです。

このコマンドは、次のスコアリング結果を返します。 
{
  "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: ONNXイメージ・モデル・エンドポイントの削除

この例では、URIで識別されるONNX形式のイメージ・モデル・スコアリング・エンドポイントを削除する方法を示します。

次のcURLコマンドを実行して、ONNXイメージ・モデル・エンドポイントを削除します。 
curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/deployment/squeezenet_onnx" --header "Authorization: Bearer ${token}"

この例では、squeezenet_onnxがURIです。

このコマンドは、モデル・エンドポイントを削除し、次の情報を返します。 
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: ONNXイメージ・モデルの削除

この例では、modelIdで識別されるONNX形式のモデルを削除する方法を示します。

次のcURLコマンドを実行して、ONNXイメージ・モデルを削除します。 
curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/models/ea37b82a-d25a-45d2-9fcc-c4e4b478de78" \
--header "Authorization: Bearer ${token}"

この例では、ea37b82a-d25a-45d2-9fcc-c4e4b478de78がmodelIdです。

このコマンドは、次の情報を返します。 
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