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では、ONNX Runtime 1.11.1をサポートしています。

サポートされる機能

  • デプロイ済モデルの格納、削除およびリスト
  • モデルのメタデータおよびコンテンツの取得
  • ネームスペースでのモデルの編成
  • モデル・エンドポイントの作成、削除およびリスト
  • モデル・エンドポイントのSwaggerドキュメントの取得
  • モデルの詳細の取得
  • エンドポイント詳細の取得
  • モデル・エンドポイントを使用したスコアリング

サポートされる機械学習モデル

Oracle Machine Learning ServicesのREST APIは、次のRESTエンドポイントを介したONNX形式モデル・デプロイメントをサポートしています。
  • 分類モデル(イメージ以外のモデルとイメージ・モデルの両方)
  • クラスタリング・モデル(イメージ以外のモデル)
  • 特徴抽出モデル(イメージ・モデル)
  • 回帰モデル(イメージ以外のモデル)

前提条件

ONNXモデルをデプロイする前に、次のことを確実に行ってください。
  • modelName.onnxファイル、metadata.jsonファイルおよびlabel.txt(オプション)ファイルを含むONNXモデルzipファイルを作成します。
  • 「metadata.jsonファイルの内容と説明」の表に示されているように、metadata.jsonファイルに次のものが含まれていることを確認します。

ノート:

ONNX形式モデルの仕様の詳細は、ONNX形式モデルの仕様を参照してください

表 - metadata.jsonファイルの内容と説明

フィールド名 データ型 説明 必須/オプション 例

function

String

モデルのマイニング機能。値"classification"、"regression"または"clustering"を受け入れます

大/小文字は区別されません

必須

"classification"

clusteringDistanceOutput

String

距離を格納するクラスタリング・モデル出力の名前。topN結果の場合、出力は昇順でソートされます。出力は、値の型がfloat/doubleのテンソルである必要があります。

大/小文字は区別されます
次のいずれかを指定する必要があります。
  • clusteringDistanceOutputまたは
  • clusteringProbOutput

ノート:

両方を指定することはできません。

"scores"

clusteringProbOutput

String

確率を格納するクラスタリング・モデル出力の名前。topNの結果の場合、出力は降順でソートされます。出力は、値の型がfloat/doubleのテンソルである必要があります。

大/小文字は区別されます
次のいずれかを指定する必要があります。
  • clusteringDistanceOutputまたは
  • clusteringProbOutput

ノート:

両方を指定することはできません。

"probabilities"

regressionOutput

String

回帰結果を格納する回帰モデル出力の名前。出力は、値の型がfloat/doubleのテンソルである必要があります。

大/小文字は区別されます
  • オプション - 回帰モデルにテンソル出力が1つのみの場合
  • 必須 - 回帰モデルに複数の出力がある場合

"variable"

classificationLabelOutput

String

ラベル結果を格納する分類モデル出力の名前。出力はテンソルであることが必要です。

大/小文字は区別されます
  • 無視 - 分類モデルの出力が1つのみで、確率を格納するテンソルである場合
  • オプション - 分類モデルに2つの出力がある場合、1つのテンソルにラベル情報が格納され、もう1つのシーケンスに確率が格納されます
分類モデルのその他の場合:
  • オプション - label.txtが存在する場合。
  • 必須 - label.txtが指定されていない場合。

"label"

classificationProbOutput

String
確率を格納する分類モデル出力の名前。出力は次のいずれかである必要があります。
  • float/double型のテンソル値、または
  • <label, probability>情報を格納するfloat/double型の値を持つ<key, value>ペアのマップのシーケンス。

大/小文字は区別されます
  • オプション - 分類モデルの出力が1つのみで、確率を格納するテンソルである場合
  • オプション - 分類モデルに2つの出力がある場合、1つのテンソルにラベル情報が格納され、もう1つのシーケンスに確率が格納されます
  • 必須 - 分類モデルのその他の場合

"dense/Sigmoid:0"

featureExtractionOutput String

特徴を格納するONNXイメージ・モデル出力の名前。出力は、値の型がfloat/doubleのテンソルである必要があります。

大/小文字は区別されます。
  • オプション - 特徴抽出モデルのテンソル出力が1つのみの場合
  • 必須 - 特徴抽出モデルに複数の出力がある場合

"1446"

inputTensorDimNames

ONNXイメージ・モデルの場合のみ

String

入力テンソルでの各ディメンションの意味を指定します。ディメンション名には"batch"、"height"、"width"、"channel"を指定できます。

大/小文字は区別されます。小文字のみ使用します。
  • 必須 - イメージ・モデルの場合
  • height、width、channelとともに値を指定します

    それ以外の場合は、例外が発生します

  • 無視 - イメージ以外のモデルの場合

["batch", "height", "width", "channel"]

height

ONNXイメージ・モデルの場合のみ

Integer

前処理用にイメージの高さを指定します。
  • 必須 - イメージ・モデルの場合

    inputTensorDimNames、width、channelとともに値を指定します

    それ以外の場合は、例外が発生します

  • 無視 - イメージ以外のモデルの場合

224

width

ONNXイメージ・モデルの場合のみ

Integer

前処理用にイメージの幅を指定します。
  • 必須 - イメージ・モデルの場合

    inputTensorDimNames、height、channelとともに値を指定します

    それ以外の場合は、例外が発生します

  • 無視 - イメージ以外のモデルの場合

224

channel

ONNXイメージ・モデルの場合のみ

Integer

前処理用にイメージのチャネル番号を指定します。

  • 必須 - イメージ・モデルの場合

    inputTensorDimNames、height、widthとともに値を指定します。

    それ以外の場合は、例外が発生します

  • 無視 - イメージ以外のモデルの場合

3

mean

ONNXイメージ・モデルの場合のみ

Float[]

正規化のためのR、G、B (赤、緑、青)チャネルの平均値を指定します。

  • オプション - イメージ・モデルの場合。指定しない場合、デフォルト値はRGB (赤、緑、青)の順序で[0.0, 0.0, 0.0]になります

  • 無視 - イメージ以外のモデルの場合

[112.1, 105.2, 89.4]

scale

ONNXイメージ・モデルの場合のみ

Float[]

正規化のためのR、G、B (赤、緑、青)チャネルのスケール値を指定します。

  • オプション - イメージ・モデルの場合。指定しない場合、デフォルト値はRGB (赤、緑、青)の順序で[1.0, 1.0, 1.0]になります

  • 無視 - イメージ以外のモデルの場合

[0.8, 1.0, 0.9]

inputChannel

ONNXイメージ・モデルの場合のみ

String

前処理用にチャネル順序を指定します。現在は、3つのチャネル・イメージのみがサポートされています。値は"RGB"または"BGR"のいずれかです。

大/小文字は区別されません。
  • オプション - イメージ・モデルの場合。指定されない場合、デフォルト値は"RGB"です
  • 無視 - イメージ以外のモデルの場合

"BGR"
ONNXモデルをデプロイするには:
  1. 次のコマンドを使用して、ONNX.zipファイルを作成します。
    zip -r modelName.zip modelName.onnx, metadata.json, label.txt

    zipファイルには、次のファイルが含まれる必要があります:

    • modelName.onnxファイル(必須)。これは、ONNXモデル・ファイルです。

      ノート:

      ONNXサポートが統合されているお気に入りのフレームワークに、modelName.onnxなどの独自のONNXモデルを作成できます。または、ONNXモデル・コンバータを使用して、モデルを同等のONNX形式に変換することもできます。

    • metadata.jsonファイル(必須)。このファイルには、次の情報が含まれます。function、regressionOutput、classificationLabelOutput、classificationProbOutput、inputTensorDimNames、height、width、channel、mean、scale、inputChannel、clusteringDistanceOutput、clusteringProbOutput

      metadata.jsonファイルの例: 

      {
  "function": "classification",
  "classificationProbOutput": "dense/Sigmoid:0",
  "inputTensorDimNames": ["batch", "height", "width", "channel"],
  "height": 224,
  "width": 224,
  "channel": 3,
  "mean": [123.68, 116.779, 103.939],
  "scale": [1.0,1.0,1.0],
  "inputChannel": "BGR"
}

    • label.txt ファイル(オプション)。このファイルには、分類モデルまたはクラスタリング・モデルのラベルが格納されます。ラベルは、モデルがトレーニングされたのと同じ順序でリストする必要があります。スコアリング出力にラベル情報が含まれている場合、このファイルは必須ではありません。その場合は無視されます。

      label.txtファイルの例: 

      scorpion-winter
cinturato-winter
ice-zero-fr
winter-sottozero
  2. 認証に記載されている手順に従って、トークンを取得します。これは、HTTP認証スキームのセキュリティ・トークンであるBearerトークンです。リクエストの実行時に、Authorizationヘッダーのこのトークンを送信する必要があります。

    ノート:

    トークンを取得できるデータベース・アカウントには、OML_DEVELOPERロールが必要です。

ONNX回帰モデルのスコアリング

ステップ3からステップ6では、ONNX回帰モデルをスコアリングするステップを示します。

  1. POSTリクエストをモデル・リポジトリ・サービスに送信して、ONNXモデルをデータベースのモデル・リポジトリに格納します。

    ONNXモデルを格納するPOSTリクエストの例: 

    curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url>/omlmod/v1/models \
-H 'content-type: multipart/form-data; boundary=Boundary' \
-F modelData=@sk_rg_onnx.zip \
-F modelName=onnxRegressionModel \
-F modelType=ONNX \
-F version=1.0 \
-F 'description=onnx sk regression model version 1.' \
-F shared=true

    ノート:

    モデルをリポジトリに格納すると、一意のIDが生成されます。これは、モデル・エンドポイントの作成時に使用するmodelIdです。
    次に、ONNX形式の回帰モデルの例を示します。この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • sk_rg_onnx.zipはONNX zipファイルです。
    • onnxRegressionModelはモデル名です。
  2. POSTリクエストをデプロイメント・サービスに送信して、モデル・エンドポイントを作成します。このリクエストは、modelIdおよびURIを入力として取ります。

    ノート:

    モデル所有者のみがモデルをデプロイできます。モデル所有者とは、モデルを格納するユーザーです。デプロイ済モデルに対して新しいエンドポイントが作成されます。

    ONNXモデルをデプロイするPOSTリクエストの例: 

    curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url> /omlmod/v1/deployment \
-H 'Content-Type: application/json' \
-d '{\
  "modelId": "29e99b4b-cfc2-4189-952a-bd8e50fb8046",\
  "uri": "onnxrg"\
}'
    この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • 29e99b4b-cfc2-4189-952a-bd8e50fb8046はmodelIdです。モデルをリポジトリに格納すると、modelIdが生成されます。
    • onnxrgはURIです。
  3. GETリクエストを/deployment/{uri}/apiに送信して、このモデル・エンドポイントのOpen APIドキュメントを取得します。

    デプロイ済ONNX回帰モデルのOpen APIドキュメントを取得する例

    curl -X GET --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url>/omlmod/v1/deployment/onnxrg/api
    この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • onnxrgはURIです。
  4. POSTリクエストをdeployment/{uri}/scoreに送信して、モデルでスコアリングします。{uri}/apiへのGETレスポンスは、その詳細情報を提供します。

    ノート:

    予測の詳細は、ONNXモデル・スコアリングではサポートされません。

    2つの入力レコードを使用したミニバッチのスコアリングの例

    curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url> /omlmod/v1/deployment/onnxrg/score \
-H 'Content-Type: application/json' \
-d '{\
  "inputRecords": [\
    {\
      "input": [\
        [\
          -0.07816532,\
          0.05068012,\
          0.07786339,\
          0.05285819,\
          0.07823631,\
          0.0644473,\
          0.02655027,\
          -0.00259226,\
          0.04067226,\
          -0.00936191\
        ]\
      ]\
    },\
    {\
      "input": [\
        [\
          0.0090156,\
          0.05068012,\
          -0.03961813,\
          0.0287581,\
          0.03833367,\
          0.0735286,\
          -0.07285395,\
          0.1081111,\
          0.01556684,\
          -0.04664087\
        ]\
      ]\
    }\
  ]\
}
    これは、URIがonnxrgのデプロイ済ONNX回帰モデルです。この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • POSTリクエストは/deployment/onnxrg/scoreに送信されます。
    これで、ONNX回帰モデルのスコアリング・タスクが完了します。

ONNXイメージ・モデルのスコアリング

ステップ7からステップ10では、ONNXイメージ・モデルをデプロイする例を示します。イメージ・モデルは、イメージ・データを使用するモデルです。

ONNXイメージ・モデルは、次の2つの方法でスコアリングできます。
  • 単一のイメージ・ファイルを入力としてアップロードします。この場合、アップロードされたイメージの同等のテンソル形式が、モデルの適切な前処理とともに生成されます。
  • スコアリング入力レコードのコレクションをアップロードします(ONNXイメージ以外のモデルに類似しています)。ここでは、ONNXイメージ・モデルを使用したミニ・バッチ・スコアリングが<model_attribute_name, value/array>ペアを使用して実行されます。ここで、value/arrayは、base64文字列内のエンコードされたイメージ、または処理されたイメージ・ピクセル値を格納する多次元配列のいずれかです。サポートされているONNXイメージ・モデルには、1または-1のいずれかのテンソル・バッチ・サイズが必要です。

ONNXイメージ・モデルをデプロイするには:

  1. ONNX model.zipファイルを作成した後、POSTリクエストを使用してモデル・リポジトリにモデルを格納します。

    ONNXイメージ・モデルを格納する例

    curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url>/omlmod/v1/models \
-H 'content-type: multipart/form-data; boundary=Boundary' \
-F modelData=@img_onnx.zip \
-F modelName=onnxImageModel \
-F modelType=ONNX_IMG \
-F version=1.0 \
-F 'description=onnx image model version 1.' \
-F shared=true
    この例は、モデル・リポジトリにONNXイメージ・モデルを格納するPOSTリクエストを示しています。この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • img_onnx.zipはONNXモデルのzipファイルです。
    • onnxImageModelはモデル名です。
  2. POSTリクエストをデプロイメント・サービスに送信して、モデル・エンドポイントを作成します。このメソッドは、modelIdおよびURIを入力として取ります。

    モデル・エンドポイントを作成する例 

    curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url> /omlmod/v1/deployment \
-H 'Content-Type: application/json' \
-d '{\
  "modelId": "5ee516bb-e35e-49f4-b282-bb2d38bedc32",\
  "uri": "onnximg"\
}'
    この例は、エンドポイントを作成するPOSTを示しています。この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • 5ee516bb-e35e-49f4-b282-bb2d38bedc32はmodelIdです。モデルをリポジトリに格納すると、modelIDが生成されます。
    • onnximgはURIです。

    ノート:

    モデル所有者のみがモデルをデプロイできます。モデル所有者とは、モデルを格納するユーザーです。
  3. GETリクエストを/deployment/{uri}/apiに送信して、このONNXモデルのOpen APIドキュメントを取得します。
    デプロイ済ONNXイメージ・モデルのOpen APIドキュメントを取得する例 
    curl -X GET --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url>/omlmod/v1/deployment/onnximg/api
    この例は、デプロイ済ONNXイメージ・モデルのOpen APIドキュメントを返すGET リクエストを示しています。この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • onnximgはURIです。
  4. POSTリクエストをdeployment/{uri}/scoreに送信して、モデルをスコアリングします。

    ONNXイメージ・モデルをスコアリングするPOSTリクエストの例 

    curl -X POST --header "Authorization: Bearer $token" 
<oml-cloud-service-location-url>/omlmod/v1/deployment/onnximg/score \
-F imageData=@test.png
    この例の説明は、次のとおりです。
    • $tokenは、認可APIを介して取得されたトークンに割り当てられる環境変数を表します。
    • onnximgはURIです
    • test.pngはイメージ・ファイルです
    これで、ONNXイメージ・モデルのスコアリング・タスクが完了します。