Windows 机器学习

⚠️ 重要提示
有关 Windows 机器学习的最新文档，请参阅什么是 Windows ML。该文档介绍了位于 Microsoft.Windows.AI.MachineLearning 命名空间中的 API，这些 API 随 Windows 应用程序 SDK 一起提供。这些 API 取代了此处记录的、位于 Windows.AI.MachineLearning 命名空间中的 API，后者于 2018 年发布。

Windows 机器学习是一个高性能的机器学习推理 API，由 ONNX Runtime 和 DirectML 提供支持。

Windows ML API 是一个 Windows 运行时组件，适用于高性能、低延迟的应用程序，例如框架、游戏和其他实时应用，以及使用高级语言构建的应用程序。

此仓库包含 Windows 机器学习示例和工具，演示如何将机器学习功能集成到 Windows 应用程序中。

• Windows ML 入门
• 模型示例
• 高级场景示例
• 开发者工具
• 反馈
• 外部链接
• 贡献

有关 Windows ML 的更多信息，包括分步教程和操作指南，请访问 Windows ML 文档。

示例/工具	状态
所有示例
WinmlRunner
WinML 仪表板	?branchName=master)

Windows ML 入门

先决条件

• Visual Studio 2017 版本 15.7.4 或更高版本

Windows ML 通过预装的 Windows SDK 以及可再分发的 NuGet 包提供机器学习推理功能。下表重点介绍了 Windows ML 的预装版本和 NuGet 包在可用性、分发方式、语言支持、服务更新以及向前兼容性方面的差异。

	预装版	NuGet
可用性	Windows 10 - 构建 17763 (RS5) 或更高版本 有关版本支持的详细信息，请参阅我们的文档。	Windows 8.1 或更高版本 注意: 某些 API（如 VideoFrame）在较旧的操作系统上不可用。
Windows SDK	Windows SDK - 构建 17763 (RS5) 或更高版本	Windows SDK - 构建 17763 (RS5) 或更高版本
分发方式	内置于 Windows 中	作为应用程序的一部分打包并分发
服务更新	由 Microsoft 主导（客户自动受益）	由开发者负责
向前兼容性 自动随新功能更新	开发者需要手动更新包

了解更多信息请点击这里。

模型示例

在本节中，您将找到适用于不同 Windows ML API 产品线中各种场景的多种模型示例。

图像分类

计算机视觉的一个子领域，其中算法会查看一张图像，并根据其训练过的预定义标签或类别集合为其分配一个标签。

Windows 应用类型 分发方式	UWP 内置	UWP NuGet	桌面 内置	桌面 NuGet
AlexNet				✔️C# .NET5 - 示例库
CaffeNet				✔️C# .NET5 - 示例库
DenseNet				✔️C# .NET5 - 示例库
EfficientNet				✔️C# .NET5 - 示例库
GoogleNet				✔️C# .NET5 - 示例库
InceptionV1				✔️C# .NET5 - 示例库
InceptionV2				✔️C# .NET5 - 示例库
MNIST	✔️C++/CX ✔️C#
MobileNetV2				✔️C# .NET5 - 示例库
RCNN				✔️C# .NET5 - 示例库
ResNet50				✔️C# .NET5 - 示例库
ShuffleNetV1				✔️C# .NET5 - 示例库
ShuffleNetV2				✔️C# .NET5 - 示例库
SqueezeNet	✔️C# ✔️JavaScript		✔️C++/WinRT ✔️C# .NET5 ✔️C# .NET Core 2	✔️C++/WinRT ✔️C# .NET5 - 示例库 ✔️Rust
VGG19				✔️C# .NET5 - 示例库
VGG19bn				✔️C# .NET5 - 示例库
ZFNet512				✔️C# .NET5 - 示例库

风格迁移

一种计算机视觉技术，允许我们以另一幅图像的风格重新构图一幅图像的内容。

Windows 应用类型 分发方式	UWP 内置	UWP NuGet	桌面 内置	桌面 NuGet
FNSCandy	✔️C# - FNS 风格迁移 ✔️C# - 实时风格迁移

高级场景示例

这些高级示例展示了如何在 Windows ML 中使用各种绑定和评估功能：

• 自定义张量化：一个 Windows 控制台应用程序（C++/WinRT），演示如何进行自定义张量化。

• 自定义算子（CPU）：一个桌面应用，定义了多个自定义 CPU 算子。其中一个为调试算子，我们邀请您将其集成到自己的工作流中。

• 适配器选择：一个桌面应用，演示如何为运行模型选择特定的设备适配器。

• 平面识别器：一个 UWP 应用和一个 WPF 应用，通过桌面桥打包在一起，共享使用 Azure Custom Vision 服务 训练的同一模型。有关此示例的分步说明，请参阅博客文章 将您的 WinML 应用程序升级到最新版本。

• Custom Vision 和 Windows ML：本教程演示如何使用 Azure Custom Vision 服务训练一个神经网络模型来分类食物图像，将模型导出为 ONNX 格式，并将其部署到本地 Windows 设备上运行的 Windows Machine Learning 应用程序中。

• ML.NET 和 Windows ML：本教程向您展示如何使用 ML.NET Model Builder 训练一个神经网络模型来分类食物图像，将模型导出为 ONNX 格式，并将其部署到本地 Windows 设备上运行的 Windows Machine Learning 应用程序中。

• PyTorch 数据分析：本教程演示如何使用 PyTorch 库构建神经网络解决分类任务，将模型导出为 ONNX 格式，并使用可在任何 Windows 设备上运行的 Windows Machine Learning 应用程序部署该模型。

• PyTorch 图像分类：本教程演示如何使用 PyTorch 训练一个图像分类神经网络模型，将其导出为 ONNX 格式，并部署到您本地 Windows 设备上运行的 Windows Machine Learning 应用程序中。

• YoloV4 目标检测：本教程演示如何构建一个使用 YOLOv4 模型检测视频流中目标的 UWP C# 应用程序。

开发者工具

• 模型转换

  Windows ML 提供由 ONNX Runtime 引擎驱动的推理能力。因此，在 Windows ML 中运行的所有模型都必须转换为 ONNX 模型格式。在 TensorFlow 或 PyTorch 等源框架中构建和训练的模型必须转换为 ONNX 格式。请参阅以下文档了解如何转换为 ONNX 模型：

  • https://onnxruntime.ai/docs/tutorials/mobile/model-conversion.html
  • https://docs.microsoft.com/en-us/windows/ai/windows-ml/tutorials/pytorch-convert-model
  • WinMLTools：一个用于将来自不同机器学习工具包的模型转换为 ONNX 格式的 Python 工具，以便与 Windows ML 一起使用。

• 模型优化

  模型在转换后可能需要进一步优化，以支持批处理和量化等高级功能。请查看以下工具以优化您的模型：

  • WinML 仪表板（预览版）：一个基于 GUI 的工具，用于查看、编辑、转换和验证适用于 Windows ML 推理引擎的机器学习模型。该工具可用于为使用固定尺寸构建的模型启用自由维度。下载预览版

  • 图优化：图优化本质上是图级别的变换，范围从小型图简化和节点消除，到更复杂的节点融合和布局优化。

  • 图量化：ONNX Runtime 中的量化是指对 ONNX 模型进行 8 位线性量化。

• 模型验证

  • WinMLRunner：一个命令行工具，可运行输入和输出变量为张量或图像的 .onnx 或 .pb 模型。它是一个非常方便的工具，可以快速验证 ONNX 模型。它会尝试加载、绑定和评估模型，并打印出有用的提示信息。同时还会捕获性能测量数据。

    下载 x64 可执行文件

• 模型集成

  • WinML 代码生成器 (mlgen)：一个 Visual Studio 扩展，可通过在 UWP 项目中添加经过训练的 ONNX 文件来生成模板代码，帮助您开始在 UWP 应用程序中使用 WinML API。您可以从模板代码中加载模型、创建会话、绑定输入并使用封装代码进行评估。更多信息请参阅 文档。

    下载适用于 VS 2017 和 VS 2019 的版本

  • WinML 示例库：探索各种 ML 集成场景和模型。

  • 请查看 模型示例 和 高级场景示例，以了解如何在您的应用程序中使用 Windows ML。

反馈

• 如遇问题，请在 GitHub Issues 上提交 bug。
• 如有疑问，请前往 Stack Overflow 提问。
• 在 Windows Developer Feedback 上为热门功能请求投票，或提出您自己的需求。

外部链接

• ONNX Runtime：跨平台、高性能的机器学习推理与训练加速器。
• ONNX：开放神经网络交换项目。

贡献

我们始终欢迎您的帮助，以修复 bug 和改进示例代码。请创建一个拉取请求，我们将非常乐意审阅。

本项目已采纳 Microsoft 开源行为准则。 如需更多信息，请参阅 行为准则常见问题解答；如有任何其他问题或意见，请发送邮件至 opencode@microsoft.com。

Windows Machine Learning 快速上手指南

Windows Machine Learning (WinML) 是一个高性能的机器学习推理 API，基于 ONNX Runtime 和 DirectML 构建，专为低延迟应用（如游戏、实时框架）设计。

⚠️ 重要提示：本文档针对的是旧版 Windows.AI.MachineLearning 命名空间（2018 年发布）。微软推荐使用最新的 Windows App SDK 中的 Microsoft.Windows.AI.MachineLearning 命名空间。本指南主要基于仓库提供的经典示例进行介绍。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • 内置 API 方案：Windows 10 版本 1809 (Build 17763/RS5) 或更高版本。
  • NuGet 包方案：Windows 8.1 或更高版本（部分新特性如 VideoFrame 在旧系统上不可用）。
• 开发工具：
  • Visual Studio 2017 (版本 15.7.4 或更高) 或 Visual Studio 2019/2022。
  • 安装时需勾选 "通用 Windows 平台开发" (UWP) 或 "桌面开发与 C++" 工作负载。
• SDK：
  • Windows SDK (Build 17763/RS5 或更高版本)。

安装步骤

WinML 可以通过两种方式使用：使用 Windows 内置组件（推荐用于 Win10+）或通过 NuGet 包分发。

方式一：使用内置 Windows SDK (推荐)

无需额外安装包，只需在项目配置中引用正确的 Windows 版本。

1. 打开 Visual Studio，创建一个新的 通用 Windows 平台 (UWP) 或 C++ 桌面应用 项目。
2. 右键点击项目 -> 属性。
3. 将 目标版本 (Target Version) 和 最低版本 (Minimum Version) 均设置为 Windows 10, version 1809 (10.0; Build 17763) 或更高。
4. 在代码中直接引用命名空间即可使用：
   • C++/WinRT: #include <winrt/Windows.AI.MachineLearning.h>
   • C#: using Windows.AI.MachineLearning;

方式二：通过 NuGet 包安装 (适用于旧系统或独立分发)

如果您需要支持 Windows 8.1 或将运行时打包分发给用户：

1. 在 Visual Studio 中，右键点击解决方案资源管理器中的项目，选择 管理 NuGet 程序包。
2. 浏览并搜索 Microsoft.AI.MachineLearning。
3. 点击 安装。
   • 注：国内开发者若遇到下载慢的问题，可在 NuGet 设置中添加国内镜像源（如阿里云：https://mirrors.aliyun.com/nuget/v3/index.json）。

基本使用

以下是一个最简单的 C# 示例，展示如何加载一个预训练的 ONNX 模型（例如 MNIST 手写数字识别模型）并执行推理。

1. 准备模型

确保你有一个 .onnx 格式的模型文件（例如 mnist.onnx），并将其添加到项目的 Assets 文件夹中，设置其属性为“内容”且“复制到输出目录”。

2. 代码示例

using Windows.AI.MachineLearning;
using Windows.Storage;
using System.Threading.Tasks;

public async Task RunInferenceAsync()
{
    // 1. 加载模型文件
    StorageFile modelFile = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///Assets/mnist.onnx"));
    
    // 2. 创建学习会话 (LearningSession)
    var learningModel = await LearningModel.LoadFromStorageFileAsync(modelFile);
    var session = new LearningModelSession(learningModel);

    // 3. 准备输入数据 (此处以 MNIST 的 28x28 灰度图为例)
    // 实际使用时需将图像转换为 TensorFloat
    var imageTensor = TensorFloat.Create();
    imageTensor.Shape = new ulong[] { 1, 1, 28, 28 }; // Batch, Channel, Height, Width
    
    // 填充数据 (示例为全零，实际应填入像素值归一化后的数据)
    for (int i = 0; i < 28 * 28; i++)
    {
        imageTensor.Add(0.0f); 
    }

    // 4. 绑定输入
    var binding = new LearningModelBinding(session);
    binding.Bind("Input3", imageTensor); // "Input3" 需替换为你模型实际的输入节点名称

    // 5. 执行评估 (推理)
    var result = await session.EvaluateAsync(binding, "");

    // 6. 获取输出
    var outputTensor = result.Outputs["Plus214_Output_0"] as TensorFloat; // 名称需根据模型调整
    
    // 处理结果...
}

3. 运行示例项目

本仓库提供了大量现成的示例代码，是上手最快的方式：

• 图像分类：查看 Samples/MNIST (C++/CX 或 C#) 或 Samples/SqueezeNetObjectDetection。
• 风格迁移：查看 Samples/StyleTransfer。
• 高级场景：查看 Samples/CustomOperator (自定义算子) 或 Samples/AdapterSelection (指定 GPU/CPU)。

克隆仓库后，直接在 Visual Studio 中打开对应的 .sln 文件即可编译运行：

git clone https://github.com/microsoft/Windows-Machine-Learning.git
cd Windows-Machine-Learning/Samples/MNIST/Tutorial/cs
# 使用 VS 打开该目录下的 .sln 或 .csproj 文件