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フラグを追加します。

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

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

次のcURLコマンドを実行します。
curl -X GET --header "Authorization: Bearer $token" "<oml-cloud-service-location-url>/omlmod/v1/models" | jq

ノート:

コール元に表示されるのは、共有モデルおよびコール元が作成したモデルのみです。
このコマンドは、次の情報を返します。
{
  "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: モデル名でフィルタされたモデルのリストの取得

この例では、モデル名sk_cl_irisでフィルタされたモデルのリストを取得する方法を示します

次のcURLコマンドを実行します。
curl -X GET --header "Authorization: Bearer $token" "<oml-cloud-service-location-url>/omlmod/v1/models?modelName=sk_cl_iris" | jq
このコマンドは、モデル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: バージョンおよびネームスペースでフィルタされたモデルのリストの取得

この例では、version=1.0およびnamespace=ONNX_MODELSでフィルタされたモデルのリストを取得する方法を示します

次のcURLコマンドを実行します。
curl -X GET --header "Authorization: Bearer $token" "<oml-cloud-service-location-url>/omlmod/v1/models?version=1.0&namespace=ONNX_MODELS" | jq
このコマンドは、次の情報を返します。
{
  "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: ONNX形式モデルの格納

この例では、ONNX形式モデルをリポジトリに格納する方法を示します。格納されたモデルには一意のmodelIdが割り当てられ、モデルの作成者はリクエストの認可に使用されたアクセス・トークンから割り当てられます。このメソッドは、モデル、モデル名、説明、モデル・バージョン、モデル・タイプ、共有およびモデル・ネームスペースのバイナリ・データを入力として受け取ります。

次のcURLコマンドを実行します。
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
このコマンドは、次のメッセージに示すように、モデルをリポジトリに格納し、一意のmodelIdを生成し、モデルが格納されているリポジトリのURLを提供します。
{
  "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: ONNX形式モデル・スコアリング・エンドポイントの作成

この例では、modelIdおよびURIで識別されるONNX形式のモデル・スコアリング・エンドポイントを作成する方法を示します。

次のcURLコマンドを実行し、modelIdおよび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
このコマンドは、モデル・スコアリング・エンドポイントを作成し、次の情報を返します。
{
  "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: ONNX形式モデル・エンドポイント詳細の取得

この例では、モデルURIで識別されるONNX形式モデルのモデル・エンドポイント詳細を取得する方法を示します。

次のcURLコマンドを実行します。
curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris" \
--header "Authorization: Bearer ${token}" | jq

この例では、sk_cl_irisがURIです:

このコマンドは、次の詳細を返します。
{
  "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: ONNX形式モデル情報の取得

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

次のcURLコマンドを実行します。
curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172" \
--header "Authorization: Bearer ${token}" | jq
このコマンドは、次の情報を返します。
{
  "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: ONNX形式モデル・メタデータの取得

この例では、modelIdで識別されるONNX形式モデルのモデル・メタデータを取得する方法を示します。

次のcURLコマンドを実行します。
curl -X GET "<oml-cloud-service-location-url>/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172/metadata" \
--header "Authorization: Bearer ${token}" | jq

この例では、fdbbde68-9d36-48d7-837d-08ac9d4d6172がmodelIdです。

このコマンドは、次の情報を返します。
{
  "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: ONNX形式モデル・スコアリングREST APIの取得

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

次のcURLコマンドを実行します。
curl -i -X GET "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris/api" \
--header "Authorization: Bearer ${token}"
この例では、sk_cl_irisがURIです。このコマンドは、Open API仕様を返します。
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: ONNX形式モデルによるスコアリング(2つのレコードのミニバッチ)

この例では、2つのレコードのミニバッチで構成されるONNX形式モデルを使用してスコアリングする方法を示します。

次のcURLコマンドを実行します。
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
このコマンドは、次のスコアリング結果を返します。
{
  "scoringResults": [
    {
      "classifications": [
        {
          "label": "0",
          "probability": 0
        },
        {
          "label": "1",
          "probability": 0
        },
        {
          "label": "2",
          "probability": 1.0000001192092896
        }
      ]
    }
  ]
}

11: ONNX形式モデル・スコアリング・エンドポイントの削除

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

次のcURLコマンドを実行します。
curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/deployment/sk_cl_iris" \
--header "Authorization: Bearer ${token}"
この例では、sk_cl_irisがURIです。このコマンドは、モデル・エンドポイントを削除し、次の情報を返します。
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: ONNX形式モデルの削除

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

次のcURLコマンドを実行します。
curl -i -X DELETE "<oml-cloud-service-location-url>/omlmod/v1/models/fdbbde68-9d36-48d7-837d-08ac9d4d6172" \
--header "Authorization: Bearer ${token}"

この例では、fdbbde68-9d36-48d7-837d-08ac9d4d6172がmodelIdです。

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