載入模型

發行項
07/11/2023

機器學習模型具有輸入和輸出功能，其會將資訊傳入和傳出模型。

將模型載入為 LearningModel之後，您可以使用 LearningModel.InputFeatures 和 LearningModel.OutputFeatures 來取得 ILearningModelFeatureDescriptor 物件。這些會列出模型的預期輸入和輸出功能類型。

您可以使用LearningModelBinding將值系結至功能，並依其Name屬性參考ILearningModelFeatureDescriptor。

下列影片提供機器學習模型系結功能的簡短概觀。

特徵類型

Windows ML 支援 LearningModelFeatureKind中列舉的所有 ONNX 功能類型。這些會對應至不同的特徵描述元類別：

張

張量是多維度陣列，最常見的張量是 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> 。

地圖順序

對應序列只是索引鍵/值組的向量。例如，字串對 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

Tensorization

影像會以張量格式以 Windows ML 表示。 Tensorization 是將影像轉換成張量並在系結期間發生的程式。

Windows ML 會將影像轉換成 32 位浮點數的 4 維張量，以「NCHW 張量格式」：

N：批次大小 (或映射數目) 。 Windows ML 目前支援 1 的批次大小 N。
C：灰色 8 的通道計數 (1，Bgr8) 為 3。
H：高度。
W：寬度。

影像的每個圖元都是 8 位色彩號碼，儲存在 0-255 的範圍內，並封裝成 32 位浮點數。

如何將影像傳遞至模型

有兩種方式可將影像傳遞至模型：

ImageFeatureValue

我們建議使用 ImageFeatureValue 將影像系結為輸入和輸出，因為它會同時處理轉換和張量化，因此影像符合模型所需的影像格式。目前支援的模型格式類型為 Gray8、 Rgb8和 Bgr8，而目前支援的圖元範圍為 0-255。

您可以使用靜態方法ImageFeatureValue.CreateFromVideoFrame來建立ImageFeatureValue。

若要瞭解模型所需的格式，WinML 會使用下列邏輯和優先順序：
1. 系結 (String、Object、IPropertySet) 將會覆寫所有映射設定。
2. 模型中繼資料接著會經過檢查，並在可用時使用。
3. 如果未提供任何模型中繼資料，而且沒有呼叫端提供的屬性，執行時間會嘗試進行最佳比對。
- 如果張量看起來像 NCHW (4D float32，N==1) ，則執行時間會假設根據通道計數而定， Gray8 (C==1) 或 Bgr8 (C==3) 。
- 將假設NominalRange_0_255
- 將假設 SRGB
有數個選擇性屬性可以傳入 Bind (String、Object、IPropertySet) ：
- BitmapBounds：如果指定，這些是將影像傳送至模型之前要套用的裁剪界限。
- BitmapPixelFormat：如果指定，這是在影像轉換期間作為模型像素格式的像素格式。
對於影像圖形，模型可以指定它需要 (的特定圖形，例如，在 (，以 224，224) ，或者模型可以指定任何圖形影像的免費維度， (許多 StyleTransfer 類型模型可以採用可變大小的影像) 。呼叫端可以使用 BitmapBounds 來選擇要使用之影像的哪個區段。如果未指定，執行時間會將影像調整為模型大小， (遵守外觀比例) ，然後置中裁剪。
TensorFloat

如果 Windows ML 不支援模型的色彩格式或圖元範圍，您可以實作轉換和張量化。您將針對輸入值的 32 位浮點數建立 NCHW 四維張量。如需如何執行這項操作的範例，請參閱自訂 Tensorization 範例。

使用此方法時，會忽略模型上的任何影像中繼資料。

範例

下列範例示範如何系結至模型的輸入。在此情況下，我們會從會話建立系結、從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 標籤。
如需回報錯誤 (bug)，請在 GitHub 上提出問題。

共用方式為