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回帰モデルをスコアリングするステップを示します。

3. 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はモデル名です。
4. 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です。
5. 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です。
6. 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イメージ・モデルをデプロイするには:

7. 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はモデル名です。
8. 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です。

   ノート:

   モデル所有者のみがモデルをデプロイできます。モデル所有者とは、モデルを格納するユーザーです。
9. 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です。
10. 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イメージ・モデルのスコアリング・タスクが完了します。