绑定模型

2025-04-30

机器学习模型具有输入和输出功能，用于将信息传入和传出模型。

将模型加载为 LearningModel 后，可以使用 LearningModel.InputFeatures 和 LearningModel.OutputFeatures 获取 ILearningModelFeatureDescriptor 对象。这些列表列出了模型的预期输入和输出功能类型。

使用 LearningModelBinding 将值绑定到特征，通过 Name 属性引用 ILearningModelFeatureDescriptor。

以下视频简要概述了机器学习模型的绑定功能。

功能类型

Windows ML 支持 LearningModelFeatureKind 中枚举的所有 ONNX 功能类型。这些被映射到不同的特征描述符类：

Tensor： 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] 的上述输出是地图序列的一个示例。

映像

当处理图像时，你需要知道图像格式和张量化。

图像格式

模型使用图像训练数据进行训练，并且为该训练集保存和定制权重。将图像输入传递到模型时，其格式必须与训练图像的格式匹配。

在许多情况下，模型描述预期的图像格式;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：通道计数（1 表示 Gray8，3 表示 Bgr8）。
H：高度。
W：宽度。

图像的每个像素都是一个 8 位颜色编号，该数字存储在 0-255 的范围内，并打包成 32 位浮点数。

如何将图像传递到模型中

可通过两种方式将图像传递到模型中：

ImageFeatureValue 图像特征值

建议使用 ImageFeatureValue 将图像绑定为输入和输出，因为它负责转换和张量化，因此图像与模型所需的图像格式匹配。当前支持的模型格式类型为 Gray8、 Rgb8 和 Bgr8，当前支持的像素范围为 0-255。

可以使用静态方法 ImageFeatureValue.CreateFromVideoFrame 创建 ImageFeatureValue。

若要了解模型需要的格式，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 四维张量。有关如何执行此操作的示例，请参阅自定义张量化示例。

使用此方法时，将忽略模型上的任何图像元数据。

示例：

以下示例展示了如何绑定到模型的输入。在这种情况下，我们从会话创建绑定，从 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 上提出问题。

通过