LearningModelBinding.Bind 方法

定义

命名空间:

Windows.AI.MachineLearning

重载

Bind(String, Object)	将值绑定到命名特征。
Bind(String, Object, IPropertySet)	使用属性将值绑定到命名功能以控制绑定。

Bind(String, Object)

将值绑定到命名特征。

public:
 virtual void Bind(Platform::String ^ name, Platform::Object ^ value) = Bind;

/// [Windows.Foundation.Metadata.Overload("Bind")]
void Bind(winrt::hstring const& name, IInspectable const& value);

[Windows.Foundation.Metadata.Overload("Bind")]
public void Bind(string name, object value);

function bind(name, value)

Public Sub Bind (name As String, value As Object)

参数

name

String

Platform::String

winrt::hstring

功能的名称。

value

Object

Platform::Object

IInspectable

要绑定的值。

属性

OverloadAttribute

示例

以下示例检索第一个输入和输出特征，创建输出帧，绑定输入和输出特征，然后进行仿真。

private async Task EvaluateModelAsync(
    VideoFrame _inputFrame, 
    LearningModelSession _session, 
    IReadOnlyList<ILearningModelFeatureDescriptor> _inputFeatures, 
    IReadOnlyList<ILearningModelFeatureDescriptor> _outputFeatures,
    LearningModel _model)
{
    ImageFeatureDescriptor _inputImageDescription;
    TensorFeatureDescriptor _outputImageDescription;
    LearningModelBinding _binding = null;
    VideoFrame _outputFrame = null;

    try
    {
        // Retrieve the first input feature which is an image
        _inputImageDescription =
            _inputFeatures.FirstOrDefault(feature => feature.Kind == LearningModelFeatureKind.Image)
            as ImageFeatureDescriptor;

        // Retrieve the first output feature which is a tensor
        _outputImageDescription =
            _outputFeatures.FirstOrDefault(feature => feature.Kind == LearningModelFeatureKind.Tensor)
            as TensorFeatureDescriptor;

        // Create output frame based on expected image width and height
        _outputFrame = new VideoFrame(
            BitmapPixelFormat.Bgra8, 
            (int)_inputImageDescription.Width, 
            (int)_inputImageDescription.Height);

        // Create binding and then bind input/output features
        _binding = new LearningModelBinding(_session);

        _binding.Bind(_inputImageDescription.Name, _inputFrame);
        _binding.Bind(_outputImageDescription.Name, _outputFrame);

        // Evaluate and get the results
        var results = await _session.EvaluateAsync(_binding, "test");
    }
    catch (Exception ex)
    {
        StatusBlock.Text = $"error: {ex.Message}";
        _model = null;
    }
}

注解

Windows Server

若要在 Windows Server 上使用此 API，必须使用带桌面体验的 Windows Server 2019。

线程安全

此 API 是线程安全的。

Bind(String, Object, IPropertySet)

使用属性将值绑定到命名功能以控制绑定。

public:
 virtual void Bind(Platform::String ^ name, Platform::Object ^ value, IPropertySet ^ props) = Bind;

/// [Windows.Foundation.Metadata.Overload("BindWithProperties")]
void Bind(winrt::hstring const& name, IInspectable const& value, IPropertySet const& props);

[Windows.Foundation.Metadata.Overload("BindWithProperties")]
public void Bind(string name, object value, IPropertySet props);

function bind(name, value, props)

Public Sub Bind (name As String, value As Object, props As IPropertySet)

参数

name

String

Platform::String

winrt::hstring

要绑定到的功能的名称。

value

Object

Platform::Object

IInspectable

要绑定到功能的值。

props

IPropertySet

具有键值对的属性映射，这些键值对描述绑定的张量化和去限制化行为。 有关详细信息，请参阅 “备注 ”部分。

属性

OverloadAttribute

注解

以下是 props 参数的有效键值对：

名称	值	说明
BitmapBounds	PropertyType.UInt32Array	绑定输入时，BitmapBounds 属性指定裁剪边界。 将提取裁剪的图像并用作执行推理的输入。 绑定输出时，BitmapBounds 属性指定目标输出区域的边界。 推理结果将写入绑定映像内的目标输出区域。 BitmapBounds 属性指定为值为 [left, top, width, height]的 UInt32 数组。 此属性仅在绑定 ImageFeatureValue 时生效。
BitmapPixelFormat	PropertyType.Int32	绑定输入或输出时，BitmapPixelFormat 属性指定模型作者针对特定特征值的像素格式。 当 ONNX 模型的 Image 元数据中缺少 Image.BitmapPixelFormat元数据时，可以使用此属性在运行时指定该元数据。 绑定图像将自动转换为指定的像素格式，供模型使用。 必须将 BitmapPixelFormat 指定为对应于 Windows.Graphics.Imaging.BitmapPixelFormat 枚举中的值的 Int32 值。 目前支持以下值： BitmapPixelFormat.Rgba8 BitmapPixelFormat.Bgra8 BitmapPixelFormat.Gray8 此属性仅在绑定 ImageFeatureValue 时生效。
DisableTensorCpuSync	PropertyType.Boolean	绑定 ID3D12Resource 支持的输出张量时，DisableTensorCpuSync 属性可用于防止将 GPU/NPU 输出复制回 CPU 张量。 默认情况下， LearningModelSession.Evaluate API 调用是阻止调用，它将确保推理结果在完成后在 CPU 上可用。 在某些 GPU/NPU 评估方案中，需要将推理结果保留在 GPU/NPU 上;将结果复制回 CPU 是不必要的且速度较慢。 若要避免该复制，请在绑定期间启用 DisableTensorCpuSync 属性。 仅当绑定 ITensor 或其具体类型 (即 TensorFloat) 时，此属性才会生效。 此属性是在 Windows 11 版本 21H2 (10.0 中引入的;内部版本 22000) 。
PixelRange	PropertyType.Int32	绑定输入或输出时，PixelRange 属性指定模型作者针对特定特征值的规范化范围。 当 ONNX 模型的 Image 元数据中缺少 Image.NominalPixelRange 元数据时，可以使用此属性在运行时指定该 元数据。 绑定图像将自动转换为指定的规范化范围供模型使用。 必须将 PixelRange 指定为对应于 Windows.AI.MachineLearning.LearningModelPixelRange 枚举中的值的 Int32 值。 此属性仅在绑定 ImageFeatureValue 时生效。

Windows Server

若要在 Windows Server 上使用此 API，必须使用带桌面体验的 Windows Server 2019。

线程安全

此 API 是线程安全的。