モデルを作成する

[アーティクル]
07/11/2023

機械学習モデルには、モデルとの間で情報をやり取りする入力および出力機能があります。

モデルを LearningModel として読み込んだ後、LearningModel.InputFeatures と LearningModel.OutputFeatures を使用して ILearningModelFeatureDescriptor オブジェクトを取得できます。これらにより、モデルで想定される入力および出力機能の型が一覧表示されます。

値を機能にバインドし、その Name プロパティで ILearningModelFeatureDescriptor を参照するには、LearningModelBinding を使用します。

次のビデオは、機械学習モデルのバインド機能の概要を簡単に紹介したものです。

特徴の種類

Windows ML は、LearningModelFeatureKind で列挙されるすべての ONNX 機能の型をサポートしています。これらは、次のさまざまな機能記述子クラスにマップされます。

テンソル: TensorFeatureDescriptor
シーケンス: SequenceFeatureDescriptor
マップ: MapFeatureDescriptor
イメージ: ImageFeatureDescriptor

テンソル

テンソルは多次元配列であり、最も一般的なテンソルは 32 ビット浮動小数点数のテンソルです。テンソルのディメンションは行優先であり、各ディメンションを表す緊密にパックされた連続データを含みます。テンソルの合計サイズは、各ディメンションのサイズの積です。

シーケンス

シーケンスは、値のベクトルです。シーケンス型の一般的な使用法は、浮動小数点数の確率のベクトルです。これは、一部の分類モデルから返され、予測ごとの精度の評価を示します。

マップ

マップは、情報のキーと値のペアです。分類モデルは一般に、ラベルの付いた分類名ごとの浮動小数点数の確率が記述された文字列/浮動小数点数のマップを返します。たとえば、画像内の犬の種類を予測しようとするモデルの出力が ["Boston terrier", 90.0], ["Golden retriever", 7.4], ["Poodle", 2.6] になることがあります。

スカラー

ほとんどのマップやシーケンスにはスカラー値があります。これらは、TensorFeatureDescriptor.Shape.Size が 0 である場合に表示されます。この場合、マップまたはシーケンスはスカラー型になります。最も一般的なのは float です。たとえば、文字列から浮動小数点数へのマップは次のようになります。

MapFeatureDescriptor.KeyKind == TensorKind.String
MapFeatureDescriptor.ValueDescriptor.Kind == LearningModelFeatureKind.Tensor
MapFeatureDescriptor.ValueDescriptor.as<TensorFeatureDescriptor>().Shape.Size == 0

実際のマップ機能の値は IMap<string, float> になります。

マップのシーケンス

マップのシーケンスは、単なるキーと値のペアのベクトルです。たとえば、文字列から浮動小数点数へのマップのシーケンスは型 IVector<IMap<string, float>> になります。犬の種類の予測に関する上の出力 ["Boston terrier", 90.0], ["Golden retriever", 7.4], ["Poodle", 2.6] は、マップのシーケンスの例です。

Images

イメージを操作する場合は、イメージ形式とテンソル化に注意する必要があります。

イメージ形式

モデルがイメージトレーニングデータでトレーニングされた後、重みが保存され、そのトレーニングセットに対して調整されます。イメージ入力をモデルに渡す場合は、その形式がトレーニングイメージの形式に一致している必要があります。

多くの場合、モデルは想定されるイメージ形式を記述します。ONNX モデルは、メタデータを使用して想定されるイメージ形式を記述できます。

ほとんどのモデルは次の形式を使用しますが、これはすべてのモデルに対して汎用性があるわけではありません。

Image.BitmapPixelFormat: Bgr8
Image.ColorSpaceGamma: SRGB
Image.NominalPixelRange: NominalRange_0_255

テンソル化

Windows ML では、イメージはテンソル形式で表されます。テンソル化は、イメージをテンソルに変換するプロセスであり、バインド中に発生します。

Windows ML は、イメージを "NCHW テンソル形式" の 32 ビット浮動小数点数の 4 次元テンソルに変換します。

N: バッチサイズ (またはイメージの数)。 Windows ML は現在、1 のバッチサイズ N をサポートしています。
C:チャネル数 (Gray8 では 1、Bgr8 では 3)。
H: 高さ。
W: 幅。

イメージの各ピクセルは、0-255 の範囲に格納され、32 ビット浮動小数点数にパックされる 8 ビットの色番号です。

イメージをモデルに渡す方法

イメージは、次の 2 つの方法でモデルに渡すことができます。

ImageFeatureValue

イメージを入力と出力としてバインドするには、ImageFeatureValue を使用することをお勧めします。これは変換とテンソル化の両方を処理するため、イメージがモデルの必要なイメージ形式に一致します。現在サポートされているモデル形式の種類は Gray8、Rgb8、および Bgr8 であり、サポートされているピクセル範囲は 0-255 です。

ImageFeatureValue は、静的メソッド ImageFeatureValue.CreateFromVideoFrame を使用して作成できます。

モデルにどのような形式が必要かを見つけるために、WinML は次のロジックと優先順位を使用します。
1. Bind(String, Object, IPropertySet) で、すべてのイメージ設定がオーバーライドされます。
2. その後、モデルメタデータがチェックされ、可能であれば使用されます。
3. モデルメタデータが指定されておらず、どの呼び出し元もプロパティを指定しなかった場合は、ランタイムが最適な一致を試みます。
- テンソルが NCHW (4 次元 float32、N==1) である可能性がある場合、ランタイムは、チャネル数に応じて Gray8 (C==1) または Bgr8 (C==3) のどちらかを想定します。
- NominalRange_0_255 が想定されます。
- SRGB が想定されます。
Bind(String, Object, IPropertySet) には、次のいくつかのオプションプロパティを渡すことができます。
- BitmapBounds: 指定されている場合、これらは、イメージをモデルに送信する前に適用するトリミング境界です。
- BitmapPixelFormat: 指定されている場合、これは、イメージの変換中にモデルのピクセル形式として使用されるピクセル形式です。
イメージシェイプの場合、モデルは受け取る特定のシェイプを指定できます (たとえば、SqueezeNet は 224,224 を受け取ります)。または、シェイプイメージの場合、モデルはフリーディメンションを指定できます (多くの StyleTransfer タイプのモデルは可変サイズのイメージを受け取ることができます)。呼び出し元は、BitmapBounds を使用して、イメージのどのセクションを使用するかを選択できます。指定されていない場合、ランタイムは (縦横比を考慮して) イメージをモデルサイズにスケーリングしてから、センタートリミングします。
TensorFloat

Windows ML でモデルの色形式またはピクセル範囲がサポートされていない場合は、変換とテンソル化を実装できます。入力値に対して 32 ビット浮動小数点数の NCHW 4 次元テンソルを作成します。この実行方法の例については、カスタムテンソル化のサンプルに関するページを参照してください。

この方法が使用された場合、モデル上のイメージメタデータはすべて無視されます。

例

次の例は、モデルの入力にバインドする方法を示しています。この場合は、session からバインドを作成し、inputFrame から ImageFeatureValue を作成した後、イメージをモデルの入力 inputName にバインドします。

private void BindModel(
    LearningModelSession session,
    VideoFrame inputFrame,
    string inputName)
{
    // Create a binding object from the session
    LearningModelBinding binding = new LearningModelBinding(session);

    // Create an image tensor from a video frame
    ImageFeatureValue image =
        ImageFeatureValue.CreateFromVideoFrame(inputFrame);

    // Bind the image to the input
    binding.Bind(inputName, image);
}

次の方法で共有