モデルをバインドする

2025-04-24

機械学習モデルには、モデルとの間で情報を渡す入力機能と出力機能があります。

モデルを LearningModel として読み込んだ後、LearningModel.InputFeatures と LearningModel.OutputFeatures を使用して ILearningModelFeatureDescriptor オブジェクトを取得できます。次に、モデルの予想される入力機能と出力機能の種類を示します。

LearningModelBinding を使用して値をフィーチャーにバインドし、その Name プロパティで ILearningModelFeatureDescriptor を参照します。

次のビデオでは、機械学習モデルのバインド機能の概要を示します。

機能の種類

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

テンソル: TensorFeatureDescriptor
シーケンス: SequenceFeatureDescriptor
マップ: MapFeatureDescriptor
画像: ImageFeatureDescriptor

テンソル

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

シーケンス

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

地図

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

スカラー

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

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

実際のマップフィーチャ値は IMap<string, float>になります。

マップのシーケンス

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

画像

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

イメージの形式

モデルは画像トレーニングデータを使用してトレーニングされ、そのトレーニングセットに合わせて重みが保存され、調整されます。画像入力をモデルに渡す場合、その形式はトレーニング画像の形式と一致する必要があります。

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

ほとんどのモデルでは次の形式が使用されますが、これはすべてのモデルに共通ではありません。

Image.BitmapPixelFormat: bgr8
Image.ColorSpaceGamma: SRGB (英語)
Image.NominalPixelRange: NominalRange_0_255

テンソル化

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

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

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

画像の各ピクセルは 8 ビットの色番号であり、0 から 255 の範囲で格納され、32 ビット浮動小数点にパックされます。

モデルに画像を渡す方法

モデルに画像を渡す方法は 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 を使用して、使用するイメージのセクションを選択できます。指定しない場合、ランタイムはイメージをモデルサイズにスケーリングし (縦横比を考慮して)、中央のトリミングを行います。
テンソルフロート

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

このメソッドを使用すると、モデル上のすべての画像メタデータは無視されます。

例

次の例は、モデルの入力にバインドする方法を示しています。この場合、セッションからバインドを作成し、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);
}

こちらも参照ください

前へ: セッションを作成する
次へ: モデルの入力を評価する

注

Windows ML のヘルプについては、次のリソースを使用してください。

Windows ML に関する技術的な質問や回答を行うには、Stack Overflowの windows-machine-learning タグを使用してください。
バグを報告するには、GitHubで問題を報告してください。