ONNXモデル用のJSONメタデータ・パラメータ

IMPORT_ONNX_MODEL (DBMS_DATA_MINING)、 LOAD_ONNX_MODEL (DBMS_VECTOR)またはLOAD_ONNX_MODEL_CLOUD (DBMS_VECTOR)プロシージャを使用してモデルをインポートする場合は、メタデータをJSONパラメータとして指定します。

パラメータ

フィールド	値の型	説明
function	文字列	regression、classification、clusteringまたはembeddingを指定します。これは必須の設定です。 ノート: モデルのインポート時に必要なJSONパラメータは、機械学習機能のみです。
input	該当なし	モデル入力のマッピングを指定します。詳細は、使用方法の入力に関する項を参照してください。
regressionOutput	文字列	回帰結果を格納する回帰モデル出力の名前。出力は、サポートされている回帰出力タイプのサポートされるシェイプのテンソルであることが想定されます。詳細は、使用方法の出力に関する項を参照してください。
classificationProbOutput	文字列	確率を格納する分類モデル出力の名前。出力は、サポートされているシェイプのfloat型(幅32/64)のテンソル値である必要があります。使用方法の「出力確率の自動正規化」を参照してください。
clusteringDistanceOutput	文字列	距離を格納するクラスタリング・モデル出力の名前。出力は、サポートされているシェイプのfloat型(幅16/32/64)です。
clusteringProbOutput	文字列	確率を格納するクラスタリング・モデル出力の名前。出力は、サポートされているシェイプのfloat型(幅16/32/64)です。
classificationLabelOutput	文字列	ラベル情報を保持するモデル出力の名前。 分類のラベルを指定するための次のメタデータ・パラメータがあります。 labels: JSONメタデータで直接ラベルを指定します classificationLabelOutput: ラベルを提供するモデル出力を指定します このパラメータに値を指定しない場合、またはモデルの機能が分類でない場合は、エラーが発生します。 ユーザーは、ラベル情報を保持するモデル出力にclassificationLabelOutputを設定することで、モデルのラベルを直接使用するように指定できます。ラベル情報を保持するテンソル出力は、クラスの数と同じサイズで、整数型または文字列型である必要があります。ラベルを保持するテンソルが文字列型の場合、PREDICTION演算子の戻り型はVARCHAR2です。ラベルを保持するテンソルが整数型の場合、PREDICTION演算子の戻り型はNUMBERです。
normalizeProb	文字列	出力確率の自動正規化について記述します。使用方法の「出力確率の自動正規化」を参照してください。
labels	該当なし	分類に使用されるラベル。 カスタム・ラベルを使用する場合は、JSONメタデータのlabelsフィールドを使用してラベルを指定します。このフィールドは、クラス数と同じ長さの配列に設定できます。クラスiのラベルは、ラベル配列の索引iに格納する必要があります。文字列の配列を使用する場合、PREDICTION演算子の戻り型はVARCHAR2です。ユーザーが指定する文字列ラベルのサイズは、4000バイトを超えないようにしてください。数値の配列を使用する場合、PREDICTION演算子の戻り型はNUMBERです。 ラベルまたはclassificationLabelOutputを指定しない場合、クラスは1からNの範囲の整数で識別されます。Nはクラスの数です。この場合、PREDICTION演算子の戻り型はNUMBERです。
embeddingOutput	文字列	生成された埋込みを保持するモデル出力。
suitableDistanceMetrics	文字列	モデルに適した距離メトリックの名前の配列。名前は、Oracle VECTOR_DISTANCE演算子に使用される距離メトリックの名前である必要があります。サポートされている距離メトリックを確認するには、「ベクトル距離メトリック」を参照してください。 このパラメータは参照専用です。
normalization	ブール	ブール値は、正規化が出力ベクトルに適用されるかどうかを示します。値1は、正規化が適用されることを意味します。正規化は、標準または長さが1になるように埋込みベクトルを変換するプロセスです。正規化されたベクトルでは方向が維持されますが、長さは1になります。結果のベクトルは、多くの場合、単位ベクトルと呼ばれます。
maxSequenceLength	数値	モデルにとって意味のあるトークン(入力)シーケンスの最大長。このパラメータは、モデルが処理する各入力シーケンス内のトークン、単語または要素の数に制限を設定します。これにより、モデルの入力サイズが均一になります。たとえば、パラメータが使用されるタスクに応じて、値は128または512から4096になります。機械翻訳モデルでは、maxSequenceLengthを512にして、翻訳タスクに最大512個のトークンの文または段落を格納できます。 このパラメータは参照専用です。
pooling	文字列	出力ベクトルに対して実行されるプーリング関数を示します。 このパラメータは参照専用です。
modelDescription	オブジェクト	既存のONNXメタデータのモデルの記述を補完するために、ユーザーがモデルに記述を追加できるJSONオブジェクト。 このパラメータは参照専用です。
languages	文字列	言語名または略称のカンマ区切りリスト。『Oracle Databaseグローバリゼーション・サポート・ガイド』の「A.1 言語」を参照してください。多言語埋込みモデルをインポートする場合は、メタデータとして言語または言語の略称を指定します。 このパラメータは参照専用です。
tokenizer	文字列	トークナイザはテキストを単語に変換するために使用されます。bert、gpt2、bpe、wordpiece、sentencepiece、clipなどの様々なトークナイザを使用できます。 このパラメータは参照専用です。
embeddingLayer	文字列	埋込みレイヤーの識別子。ニューラル・ネットワークの隠れ層として機能する埋込みレイヤーは、入力データを高い次元から低い次元に変換し、入力の関係およびデータ処理効率に対するネットワークの理解を高めます。埋込みレイヤーは、カテゴリ・データまたは個別データの処理と分析に役立ちます。これを実現するために、カテゴリを連続した埋込みに変換し、重要な意味的な関係とそれらの間の類似度を取得します。たとえば、一部のトランスフォーマの最後の非表示状態、または残差ネットワーク内のレイヤーです。 このパラメータは参照専用です。
defaultOnNull	該当なし	JSONの欠落値の置換を指定するには、defaultOnNullフィールドを使用します。defaultOnNullが指定されていない場合、欠落値の置換は実行されません。defaultOnNullは、欠落値をデフォルトでNULLに設定します。NULLのかわりに意味のあるデフォルト値を指定することで、デフォルト値のNULLをオーバーライドできます。このフィールドはJSONオブジェクト・リテラルである必要があります。フィールドは入力属性名であり、その値は入力のデフォルト値です。デフォルト値は文字列型で、指定されたデータ型の有効なOracle PL/SQL NVL値である必要があります。

ノート:パラメータでは大文字と小文字が区別されます。出力パラメータ名とデフォルト値の多くのデフォルト規則により、指定する必要のある情報を最小限に抑えることができます。suitableDistanceMetricsなどのパラメータは情報提供専用のものであり、この情報をモデルのインポート時に指定する必要はありません。JSON記述子では、入力属性を1つのみ指定できます。それより多く指定すると、エラーが表示されます。normalizeProbフィールドがJSONメタデータ・パラメータとして指定されている場合、エラーが発生します。

使用上の注意

モデルの名前は、次のような他の機械学習モデルで使用されるものと同じ制限に従います。

• 入力

  ONNX表現からモデルをインポートする場合、スコアリングに使用される属性の名前と実際のONNX入力をマップする方法を指定する必要があります。スコアリング演算子は、これらの属性名を使用して、使用する列を識別します。(たとえば、PREDICTION)。次の規則に従って、入力フィールドを使用して属性名を指定します。

  指定なし: inputフィールドが指定されていない場合、属性名は名前によってモデル入力に直接マップされます。つまり、属性名がJSONメタデータに指定されていない場合、入力テンソルの名前が属性名として使用されます。各モデル入力には、次元[batch_size, value]が必要です。JSONメタデータでinputを指定しない場合、値は1である必要があります。モデルの入力がすでにその形式に準拠している場合は、追加のメタデータを指定する必要はありません。埋込みモデルの場合は、バッチで使用できる単一の入力が提供されます。ここで、JSONメタデータでinputパラメータを指定しない場合、有効なモデルは[batch_size, 1]となります。

  モデルによって暗黙的に指定されているか、入力フィールドを使用して明示的に設定したかに関係なく、すべての属性名が列名に対して有効なOracle Database識別子であるようにする必要があります。モデル内の各属性名は一意である必要があり、重複が存在しないようにします。

  1より大きい次元を持つ入力テンソルを使用するモデルの属性名を明示的に指定できます((batch_size, 2)など)。この場合、これらの値を独立した属性名として解釈するには、それぞれの名前を指定する必要があります。これは、スコアリング操作で複数の入力属性を受け取ることができるモデルである回帰、分類、クラスタリングに対して実行できます。

• 出力

  モデルには複数の出力がある場合があるため、特定の機械学習手法の対象の出力を指定できます。モデル出力を指定するには、次の方法があります。

  • モデルのインポート時に、対象の出力名をJSONで指定します。指定された名前が有効なモデル出力でない場合(特定の機械学習機能の有効な出力を示す表を参照)、エラーが表示されます。
  • 指定された機械学習手法(classificationProbOutputなど)で予期される出力名と一致する出力がモデルで生成され、明示的に指定しなかった場合、出力は自動的に想定されます。
  • 出力名を指定せず、モデルに1つの出力がある場合、システムでは、単一の出力が機械学習手法に固有のデフォルトに対応しているとみなされます。埋込み機械学習機能の場合、デフォルト値はembeddingOutputです。

    モデルの出力を指定しない場合、または指定した機械学習機能でサポートされていない出力を指定した場合は、エラーがレポートされます。次の表に、特定の機械学習機能でサポートされている出力を示します。

    機械学習機能	出力
    regression	regressionOutput
    classification	classificationProbOutput
    clustering	clusteringDistanceOutput
    embedding	embeddingOutput

    前述のモデル出力のいずれも指定されていない場合、または指定した機械学習機能でサポートされていない出力を指定した場合、エラーが表示されます。

• 出力確率の自動正規化

  多くのユーザーは、マルチクラス分類モデルの出力を正規化するためにsoftmax関数を広く採用しています。この関数により、これらのモデルの結果を簡単に解釈できるようになります。softmax関数は、実数のベクトルを確率分布に変換する数学関数です。これはsoftargmaxまたは正規化された指数関数とも呼ばれます。この関数は、classificationProbOutputやclusteringProbOutputなどの出力確率を保持するテンソルにsoftmax正規化を適用する必要があるモデル・インポート時に指定できます。softmax正規化に適用する必要がある正規化を定義するには、normalizeProbを指定します。デフォルト設定はnoneで、正規化が適用されないことを示します。確率出力にsoftmax関数を適用するには、softmaxを選択します。このフィールドに他の値を指定すると、インポート時にエラーが発生します。また、分類およびクラスタリング以外のモデルにこのフィールドを指定した場合も、エラーが発生します。

例: 埋込みモデル用のJSONメタデータ・パラメータの指定

次の例は、DBMS_VECTOR.IMPORT_ONNX_MODELプロシージャを使用してONNX埋込みモデルをデータベースにインポートする際に、JSONメタデータ・パラメータを指定する方法の簡単な例を示しています。

DBMS_VECTOR.IMPORT_ONNX_MODEL('my_embedding_model.onnx', 'doc_model', 
                JSON('{"function" : "embedding", 
                      "embeddingOutput" : "embedding" , 
                       "input":{"input": ["DATA"]}}'));

例: 埋込みモデル用のすべてのJSONメタデータ・パラメータの指定

次の例は、埋込みモデルをインポートするためにすべてのJSONメタデータ・パラメータ(embeddingLayerを除く)を指定する方法を示しています。

DECLARE
  metadata JSON;
  mdtxt varchar2(4000);
BEGIN
  metadata := JSON(q'#
           {
             "function"                : "embedding",
             "embeddingOutput"         : "embedding",
             "input"                   : { "input" : ["txt"]},
             "maxSequenceLength"       : 512,
             "tokenizer"               : "bert",
             "suitableDistanceMetrics" : [ "DOT", "COSINE", "EUCLIDEAN"],
             "pooling"                 : "Mean Pooling",
             "normalization"           : true,
             "languages"               : ["US"],
             "modelDescription"        : {
                 "description" : "This model was tuned for semantic search: Given a query/question, if can find relevant passages. It was trained on a large and diverse set of (question, a
nswer) pairs.", 
                 "url" : "https://example.co/sentence-transformers/my_embedding_model"}
           }
           #');
  -- load the onnx model
    DBMS_VECTOR.IMPORT_ONNX_MODEL('my_embedding_model.onnx', 'doc_model', metadata);
END;
/

関連項目:

機械学習タスクにONNXモデルを使用する例については、『Oracle Machine Learning for SQLユーザーズ・ガイド』を参照してください