1. ユーザーズ・ガイド
  2. ONNX Runtimeの統合
  3. ONNXモデルの使用例

7.2 ONNXモデルの使用例

次の例では、Irisデータセットを使用して分類、回帰、クラスタリングなどの機械学習手法のためのONNX形式の機械学習モデルのロードおよび推論を示します。

あやめ(Iris)は花であり、このデータセットには、Sentosa、VersicolourおよびVirginicaという3種類のあやめから収集された花びら(petal)の長さ、がく片(sepal)の長さ、花びらの幅およびがく片の幅などの情報が含まれています。
これらの例では、このデータセットをユーザーが使用できることが前提となっています。

ONNXの分類の例

次の例では、ONNXモデルの場合に定義できる様々なJSONメタデータ・パラメータを示します。

例: 分類モデルの場合のJSONメタデータの指定

次の例では、functionがClassificationであるJSONメタデータ・パラメータを示します。このモデルに、予測の確率を示すprobabilitiesという出力があるとします。PREDICTION_PROBABILITYスコアリング関数を使用するには、フィールドclassificationProbOutputを、確率を保持するモデル出力の名前に設定する必要があります。 

BEGIN 
LOAD_ONNX_MODEL('classification_model.onnx', 'doc_model', 
JSON('{"function" : "classification",
       "classificationProbOutput": "probabilities"}'));
END;
/

例: 分類モデルの場合のJSONメタデータにおけるlabelsの指定

次の例では、JSONメタデータにおいてカスタム・ラベルを指定する方法を示します。 

BEGIN 
LOAD_ONNX_MODEL('classification_model.onnx', 'doc_model',
JSON('{"function" : "classification",
	   "classificationProbOutput": "probabilities",
	   "labels": ["Setosa", "Versicolour", "Virginica"]}'));
END;
/

推論またはスコアリングには、PREDICTION関数とPREDICTION_PROBABILITY関数を使用できます: 

SELECT
    iris.*,
    PREDICTION(doc_model USING *) as predicted_species_id,
    PREDICTION_PROBABILITY(doc_model, 'setosa' USING *) as setosa_probability
FROM iris;

この問合せでは、irisデータセットを使用して、irisの種と、setosa種である確率を予測しています。iris表にあるデータを、doc_modelという名前の機械学習モデルを使用して種のID、およびその種がsetosaである確率を予測するSELECT問合せで使用しています。PREDICTION関数で、表内の属性に基づいて種が予測され、PREDICTION_PROBABILITY関数で、予測された種がsetosaである確率が計算されます。この結果には、irisビューにあるすべての列と、予測された種のID、およびその種がsetosaである確率が含まれています。

例: 分類モデルの場合のJSONメタデータにおけるinputの指定

次の例では、実際のONNXモデルの入力名にマップする、入力属性名を指定する方法を示します。この例では、SEPAL_LENGTH、SEPAL_WIDTH、PETAL_LENGTHおよびPETAL_WIDTHという4つの入力があるモデルを想定しています。この例で示すように、JSONメタデータを使用して代替の入力属性名を指定できます。ここでは、各入力を1次元のテンソルであると仮定します。inputフィールドはJSONオブジェクトである必要があります。その各フィールドはモデル入力名(SEPAL_LENGTHなど)であり、その値は、テンソルの次元(ここでは1)に従ってサイズ設定されたJSON配列です(配列内の要素ごとに1つの属性名がある)。 

BEGIN LOAD_ONNX_MODEL('classification_model.onnx', 'doc_model', 
JSON('{"function" : "classification", 
       "classificationProbOutput": "probabilities", 
       "input": { "SEPAL_LENGTH": ["SEPAL_LENGTH_CM"], 
                  "SEPAL_WIDTH": ["SEPAL_WIDTH_CM"], 
                  "PETAL_LENGTH": ["PETAL_LENGTH_CM"], 
                  "PETAL_WIDTH": ["PETAL_WIDTH_CM"] } }'));
END;
/

入力としての列を別の順序にすることもできます。

BEGIN LOAD_ONNX_MODEL('classification_model.onnx', 'doc_model', 
	JSON('{"function" : "classification", 
		   "classificationProbOutput": "probabilities", 
		   "input": { "SEPAL_WIDTH": ["SEPAL_WIDTH_CM"],
			       "PETAL_LENGTH": ["PETAL_LENGTH_CM"],
			       "PETAL_WIDTH": ["PETAL_WIDTH_CM"],
				"SEPAL_LENGTH": ["SEPAL_LENGTH_CM"] } }'));
END;
/

例: 4次元の1つの入力の指定

ここでは、モデルに4次元のxという1つの入力テンソルがある例を示します。このシナリオでの対応するJSONメタデータは次のとおりです: 

JSON('{"function" : "classification",
       "classificationProbOutput": "probabilities",
       "input": { "x": ["SEPAL_LENGTH_CM",
                        "SEPAL_WIDTH_CM",
                        "PETAL_LENGTH_CM",
                        "PETAL_WIDTH_CM"]
                     }'));

推論またはスコアリングには、PREDICTION関数とPREDICTION_PROBABILITY関数を使用できます。 

WITH
dummy_iris AS (
    SELECT
    4.5 as petal_length_cm,
    1.5 as petal_width_cm,
    4.3 as sepal_length_cm,
    2.9 as sepal_width_cm
    FROM iris
)
SELECT
    dummy_iris.*,
    PREDICTION(doc_model USING *) as predicted_species_id,
    PREDICTION_PROBABILITY(doc_model 'setosa' USING *) as setosa_probability
FROM dummy_iris;

この問合せでは、一時データセット内の指定した属性を使用して、irisの種と、setosa種である確率を予測しています。この問合せでは、属性値を設定して一時的なdummy_irisビューを作成しています。その後、この一時ビューを、doc_modelという名前の機械学習モデルを使用して種のID、およびその種がsetosaである確率を予測するSELECT問合せで使用しています。PREDICTION関数で、指定した属性に基づいて種が予測され、PREDICTION_PROBABILITY関数で、予測された種がsetosaである確率が計算されます。この結果には、dummy_irisビューにあるすべての列と、予測された種のID、およびその種がsetosaである確率が含まれています。

例: 分類モデルの場合のJSONメタデータにおけるdefaultOnNullの指定

次の例では、特定の属性についてデータセット内のそれらの値がNULLである場合に使用されるデフォルト値を提供する、defaulOnNullの指定方法を示します。defaultOnNullオブジェクト内のフィールドとしてSEPAL_LENGTH、SEPAL_WIDTH、PETAL_LENGTHおよびPETAL_WIDTHという名前を使用します。これらは、4つの入力があるONNXモデルの場合の仮の入力属性名です。これらの名前はデフォルトの入力属性名として役立つため、defaultOnNull内のフィールドとして使用できます。 

BEGIN LOAD_ONNX_MODEL('classification_model.onnx', 'doc_model', 
	JSON('{"function" : "classification", 
		   "classificationProbOutput": "probabilities", 
		   "defaultOnNull": {"SEPAL_LENGTH": "5.1", 
		   "SEPAL_WIDTH": "3.5", 
		   "PETAL_LENGTH": "1.4", 
		   "PETAL_WIDTH": "0.2"}}'));
END;
/

  • "SEPAL_LENGTH": "5.1": がく片の長さがnullの場合は、そのデフォルト値として5.1を使用します。

  • "SEPAL_WIDTH": "3.5": がく片の幅がnullの場合は、そのデフォルト値として3.5を使用します。

  • "PETAL_LENGTH": "1.4": 花びらの長さがnullの場合は、そのデフォルト値として1.4を使用します。

  • "PETAL_WIDTH": "0.2": 花びらの幅がnullの場合は、そのデフォルト値として0.2を使用します。

例: 分類モデルの場合のJSONメタデータにおけるinputとdefaultOnNullの指定

ここでは、input値とdefaultOnNull値を組み合せて指定する例を示します。この例では、前述の例(input値とdefaultOnNull値が指定されている)で示した値を使用します。 

JSON('{"function" : "classification",
               "classificationProbOutput": "probabilities",
               "input": { "SEPAL_WIDTH": ["SEPAL_WIDTH_CM"],
                          "PETAL_LENGTH": ["PETAL_LENGTH_CM"],
                          "PETAL_WIDTH": ["PETAL_WIDTH_CM"],
                          "SEPAL_LENGTH": ["SEPAL_LENGTH_CM"] },
                    "defaultOnNull": {"SEPAL_LENGTH_CM": "5.1",
                                      "SEPAL_WIDTH_CM": "3.5"}}')

ONNXのクラスタリングの例

次の例では、ONNXモデルの場合に定義できる様々なJSONメタデータ・パラメータを示します。

例: クラスタリング・モデルの場合のJSONメタデータの指定

次の例では、functionがClusteringであるJSONメタデータ・パラメータを示します。このモデルに、予測の確率を示すprobabilitiesという出力があるとします。CLUSTER_PROBABILITYスコアリング関数を使用するには、フィールドclusteringProbOutputを、確率を保持するモデル出力の名前に設定する必要があります。 

BEGIN
LOAD_ONNX_MODEL('clustering_model.onnx','doc_model',
    JSON('{"function": "clustering",
           "clusteringProbOutput": "probabilities"
        }
    ')
);
END;
/

推論またはスコアリングには、CLUSTER_ID関数とCLUSTER_PROBABILITY関数を使用できます。 

SELECT
    iris.*,
    CLUSTER_ID(doc_model USING *) as cluster_id,
    CLUSTER_PROBABILITY(doc_model, 1 USING *) as cluster_1_probability
FROM iris;

この問合せでは、irisデータセットのレコードごとに、クラスタ割当て、および特定のクラスタに属する確率を予測しています。この問合せでは、各レコードのすべての列(iris.*)を取得し、doc_modelというクラスタリング・モデルをirisデータセットの各レコードに適用し、クラスタIDを予測しています。USING *句により、iris表内の使用可能なすべての列をこの予測に使用するようにモデルに指示しています。問合せのCLUSTER_PROBABILITY(doc_model, 1 USING *) as cluster_1_probabilityという部分では、irisデータセットからdoc_modelに従って各レコードがクラスタ1に属している確率を計算しています。これにより、各レコードがクラスタ1に含まれる可能性について調べることができ、メンバーシップの強度を定量的に測定できます。

例: クラスタリング・モデルの場合のJSONメタデータにおけるclusteringDistanceOutputの指定

次の例では、ONNXクラスタリング・モデルの場合のclusteringDistanceOutputの指定方法を示します。

このモデルでは、distancesという出力テンソルにより、そのinput (4次元のfloat_inputという単一のテンソル)に対して距離を提供しています。JSONメタデータのinputフィールドでは、属性名をテンソルのエントリにマップする必要があります("SEPAL_LENGTH", "SEPAL_WIDTH", "PETAL_LENGTH", "PETAL_WIDTH"など)。 

BEGIN 
LOAD_ONNX_MODEL('clustering_model.onnx', 'doc_model', 
JSON('{"function" : "clustering", 
"clusteringDistanceOutput": "distances", 
"normalizeProb": "softmax", 
"input": { "float_input": ["SEPAL_LENGTH", "SEPAL_WIDTH", "PETAL_LENGTH", "PETAL_WIDTH"] } 
      }')
);
END;
/

推論またはスコアリングには、CLUSTER_DISTANCE関数を使用できます。これらのSQL問合せでは、クラスタリング・モデルを使用してIRISデータセットからクラスタの距離を予測しています。 

SELECT CLUSTER_DISTANCE(doc_model USING *) AS predicted_target_value,
CLUSTER_DISTANCE (doc_model,1 USING *) AS dist1,
CLUSTER_DISTANCE (doc_model,2 USING *) AS dist2,
CLUSTER_DISTANCE (doc_model,3 USING *) AS dist3
FROM IRIS
ORDER BY ID
FETCH NEXT 10 ROWS ONLY;

ここでは、問合せは、クラスタの重心からのデータ・ポイントの物理的な距離を把握することに重点を置いています。これは、外れ値の特定や詳細なクラスタ分析の実行に特に役立ちます。この問合せでは、doc_modelを使用して、様々なクラスタの重心からの、IRISデータセット内の各レコードの距離を計算しています。USING *構文により、モデルで予測の実行にIRISデータセットのすべての使用可能列を使用する必要があることを示しています。CLUSTER_DISTANCE(doc_model, n USING *)では、クラスタnからの距離を計算しています(この問合せではnは1、2および3)。各距離は、別々の列(dist1、dist2、dist3)として選択されています。

出力は、IRIS表のID列でソートされ、結果セットの先頭10行に制限されています。

例: クラスタリング・モデルの場合のJSONメタデータにおけるclusteringProbOutputとnormalizeProbの指定

次の例では、ONNXクラスタリング・モデルの場合のclusteringProbOutputとnormalizeProbの指定方法を示します。 

BEGIN 
LOAD_ONNX_MODEL('clustering_model.onnx', 'doc_model',
               JSON('{"function" :
			   "clustering",
			   "clusteringProbOutput": "probabilities",
                        "normalizeProb" : "softmax",
			   "input": { "float_input": ["SEPAL_LENGTH", "SEPAL_WIDTH", "PETAL_LENGTH", "PETAL_WIDTH"] } }')
      );
END;
/

推論またはスコアリングには、CLUSTER_PROBABILITY関数とCLUSTER_SET関数を使用できます: 

SELECT CLUSTER_ID (doc_model USING *) AS predicted_target_value,
                    CLUSTER_PROBABILITY (doc_model,1 USING *) AS prob1,
                    CLUSTER_PROBABILITY (doc_model,2 USING *) AS prob2,
                    CLUSTER_PROBABILITY (doc_model,3 USING *) AS prob3
                    FROM IRIS
                    ORDER BY ID
                    FETCH NEXT 10 ROWS ONLY;

この場合は、クラスタリング・モデルを使用して、IRISデータセットからレコードのクラスタIDおよび関連する確率を予測しています。このJSONメタデータではnormalizeProbフィールドにsoftmaxを指定しているため、このモデルでは、確率を、softmax正規化を適用してからCLUSTER_PROBABILITYスコアリング演算子の結果として返します。

このSQL問合せでは、IRIS表からCLUSTER_ID列を選択し、doc_modelによる予測を含む新しい列predicted_target_valueを追加しています。このUSING *構文は、doc_modelモデルの入力特徴として現在の行のすべての列を使用し、その値をpredicted_target_valueとして予測することを意味しています。その後、この予測の結果が、問合せの出力に新しい列として含まれます。

CLUSTER_PROBABILITY(model, n USING *): レコードがクラスタnに属している確率を計算します(この問合せでのnは1、2および3)。これは3つの異なるクラスタに対して実行され、各確率は別々の列(prob1、prob2、prob3)として選択されます。

出力は、IRIS表のID列でソートされ、結果セットの先頭10行に制限されています。 


SELECT S.CLUSTER_ID, S.PROBABILITY
 FROM (SELECT CLUSTER_SET(doc_model USING *) pset
          FROM IRIS ORDER BY ID) T,
       TABLE(T.pset) S
FETCH NEXT 10 ROWS ONLY;

CLUSTER_SET問合せでは、doc_modelを使用してクラスタ・データのセットを生成しています。結果列psetは、各レコードの考えられるすべてのクラスタ割当てを表しています。これには、クラスタIDとそれぞれの確率が、ID列でソートされて含まれています。問合せのSELECT S.CLUSTER_ID, S.PROBABILITYという部分では、結果列のセットからクラスタIDと確率を選択しています。出力は、結果セットの先頭10行に制限されています。

ONNXの回帰の例

次の例では、ONNX回帰モデルの場合に定義できる様々なJSONメタデータ・パラメータを示します。すべての例で、ONNXモデルにregressionOutputという名前の出力が1つ、1次元の入力テンソルが4つあり、それらの名前がIRIS表の列の名前(つまり、SEPAL_LENGTH, SEPAL_WIDTH, PETAL_LENGTH, PETAL_WIDTH)と完全に一致していることを想定しています。

例: 回帰モデルの場合のJSONメタデータの指定

次に、functionがRegressionであるJSONメタデータ・パラメータを説明する単純な例を示します。ONNXモデルにregressionOutputという名前の出力が1つ、1次元の入力テンソルが4つあり、それらの名前がIRIS表の列("SEPAL_LENGTH", "SEPAL_WIDTH", "PETAL_LENGTH", "PETAL_WIDTH")と完全に一致していることを想定しています。JSONメタデータは、次のような単純なものにできます: 

BEGIN LOAD_ONNX_MODEL(
    'regression_model.onnx',
    'doc_model',
    JSON('{"function": "regression"}
    ')
);
END;
/

推論またはスコアリングにはPREDICTION関数を使用できます: 

SELECT
    iris.*,
    PREDICTION(doc_model USING *) as predicted_petal_width_cm
FROM iris;

この場合、このSQL問合せでは、iris表からすべての列を選択し、doc_modelによる予測を含む新しい列predicted_petal_width_cmを追加しています。このUSING *構文は、doc_modelモデルの入力特徴として現在の行のすべての列を使用し、PETAL_WIDTHの値をpredicted_petal_width_cmとして予測することを意味しています。その後、この予測の結果が、問合せの出力に新しい列として含まれます。

例: 回帰モデルの場合のJSONメタデータにおけるinputとdefaultOnNullの指定

次の例では、実際のONNXモデルの入力名にマップする、入力属性名を指定する方法を示します。defaulOnNullで、特定の属性についてデータセット内のそれらの値がNULLである場合に使用されるデフォルト値を提供しています。 

BEGIN LOAD_ONNX_MODEL('regression_model.onnx','doc_model',
    JSON('{"function": "regression",
            "input": {
                "SEPAL_LENGTH": ["dummy_sepal_length_cm"],
                "SEPAL_WIDTH": ["dummy_sepal_width_cm"]
                      },
            "defaultOnNull": {
                "dummy_sepal_length_cm": "5.1",
                "dummy_sepal_width_cm": "3.5",
                 }
           }
        ')
);
END;
/

推論またはスコアリングにはPREDICTION関数を使用できます。 

WITH
dummy_iris AS (
    SELECT
    (CASE WHEN petal_length > 5 THEN 4.9 ELSE NULL END)
        as dummy_sepal_length_cm,
    (CASE WHEN petal_length < 4 THEN 2.5 ELSE NULL END)
        as dummy_sepal_width_cm,
    petal_length
    petal_width
    FROM iris
)
SELECT
    dummy_iris.*,
    PREDICTION(doc_model USING *) as predicted_petal_width_cm
FROM dummy_iris;

この場合は、dummy_sepal_length_cm、dummy_sepal_width_cmおよびpetal_lengthという3つの列がある一時dummy_iris表が作成されます。dummy_sepal_length_cmおよびdummy_sepal_width_cmの値は、iris表のpetal_length値に基づいています。petal_lengthが5より大きい場合、dummy_sepal_length_cmは4.9に設定され、それ以外の場合はNULLに設定されます。petal_lengthが4未満の場合、dummy_sepal_width_cmは2.5に設定され、それ以外の場合はNULLのままになります。

次に、SELECT問合せで、dummy_iris表からすべての列を取得し、doc_modelを使用してpetal_widthを予測し、この予測をpredicted_petal_width_cmという新しい列として追加しています。このモデルでは、導出されたダミー列petal_lengthおよびpetal_widthをその予測に使用しています。

関連項目:

親トピック: ONNX Runtimeの統合