Windows ML API接口

2025-05-20

可以将 Microsoft.Windows.AI.MachineLearning NuGet 包中的 API 视为这三组的超集：

新 API。新的 Windows ML API，例如 基础结构 类及其方法（即 Windows 运行时 API）：例如 WinMLInitialize 函数（这是一个平面 C 样式的 Win32 API，也是 Windows ML 启动 API 之一）。这些 API 记录在你正在阅读的主题中。
旧版 Windows ML 中的 API。从 Windows.AI.MachineLearning 命名空间复制的 Windows ML API。因此，暂时可以通过 Windows.AI.MachineLearning 的文档了解这些 API，同时要知道它们现在也存在于 Microsoft.Windows.AI.MachineLearning 中。请参阅 Windows.AI.MachineLearning 中的 Windows ML API。
ONNX 运行时 API。 Windows ML 实现在 Microsoft.Windows.AI.MachineLearning NuGet 包中，包含 ONNX 运行时（ORT）的某些 API。有关文档，请参阅 ONNX 运行时 API 文档。例如， OrtCompileApi 结构。有关使用这些 API 的代码示例以及文档的更多链接，请参阅使用 Windows ML 运行 ResNet-50 模型教程。

Microsoft.Windows.AI.MachineLearning NuGet 包

Microsoft Windows ML 运行时为 Windows 应用程序中的机器学习和 AI作提供 API。 Microsoft.Windows.AI.MachineLearning NuGet 包提供 Windows ML 运行时.winmd文件，用于 C# 和C++项目。

新增 Windows 运行时接口

基础结构类

Infrastructure 类提供用于下载、配置和注册 AI 执行提供程序（EP）以用于 ONNX 运行时的方法。 基础结构 处理包管理和硬件选择的复杂性。

此类是应用通过 Windows ML 运行时访问硬件优化机器学习加速的入口点。

C#
C++/WinRT

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

// Download the latest execution provider packages
await infrastructure.DownloadPackagesAsync();

// Register available execution providers with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

// Use ONNX Runtime directly for inference (using Microsoft.ML.OnnxRuntime namespace)

winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

// Download packages
infrastructure.DownloadPackagesAsync().get();

// Register execution providers with ONNX Runtime
infrastructure.RegisterExecutionProviderLibrariesAsync().get();

// Use ONNX Runtime C API directly for inference

基础设施类方法

Infrastructure.DownloadPackagesAsync 方法

下载当前硬件配置的包依赖项。这保证了适合设备硬件的执行提供程序已安装并是最新的 up-to版本。

C#
C++/WinRT

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

try {
    // This will download the appropriate packages for the current hardware
    await infrastructure.DownloadPackagesAsync();
    Console.WriteLine("Execution provider packages downloaded successfully");
}
catch (Exception ex) {
    Console.WriteLine($"Failed to download execution provider packages: {ex.Message}");
}

try {
    winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;
    
    // Download the packages
    infrastructure.DownloadPackagesAsync().get();
    std::wcout << L"Execution provider packages downloaded successfully\n";
}
catch (const winrt::hresult_error& ex) {
    std::wcout << L"Error: " << ex.message().c_str() << L"\n";
}

Infrastructure.RegisterExecutionProviderLibrariesAsync 方法

使用 ONNX 运行时注册与当前硬件配置相关的所有执行提供程序库。在创建 ONNX 运行时会话之前，应调用此方法。

重要

在调用 RegisterExecutionProviderLibrariesAsync 后，基础结构实例在使用 ONNX 运行时时必须保持有效。

C#
C++/WinRT

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

// Register execution providers with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

// Use ONNX Runtime directly for inference (using Microsoft.ML.OnnxRuntime namespace)

winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

// Register execution providers with ONNX Runtime
infrastructure.RegisterExecutionProviderLibrariesAsync().get();

// Use ONNX Runtime C API directly for inference

Infrastructure.GetExecutionProviderLibraryPathsAsync 方法

获取执行提供程序名称与其完整文件路径之间的映射关系。这样，应用程序就可以检索有关可用执行提供程序及其位置的信息。

C#
C++/WinRT

// C# example
var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

try {
    // Get the map of execution provider names to paths
    var providerPaths = await infrastructure.GetExecutionProviderLibraryPathsAsync();

    foreach (var provider in providerPaths) {
        Console.WriteLine($"Provider: {provider.Key}, Path: {provider.Value}");
    }
}
catch (Exception ex) {
    Console.WriteLine($"Failed to get execution provider paths: {ex.Message}");
}

try {
    winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

    // Get the execution provider paths
    auto providerPaths = infrastructure.GetExecutionProviderLibraryPathsAsync().get();

    for (const auto& pair : providerPaths) {
        std::wcout << L"Provider: " << pair.Key().c_str() << L", Path: " << pair.Value().c_str() << L"\n";
    }
}
catch (const winrt::hresult_error& ex) {
    std::wcout << L"Error: " << ex.message().c_str() << L"\n";
}

其他基础结构成员

名称	DESCRIPTION
基础结构（）	初始化 Infrastructure 类实例的默认构造函数

API 详细信息

namespace Microsoft.Windows.AI.MachineLearning
{
    [contract(Windows.Foundation.UniversalApiContract, 1)]
    [threading(both)]
    [marshaling_behavior(agile)]
    runtimeclass Infrastructure
    {
        // Constructor
        Infrastructure();

        // Downloads package dependencies for the current hardware.
        Windows.Foundation.IAsyncAction DownloadPackagesAsync();

        // Registers all execution provider libraries with ONNX Runtime.
        Windows.Foundation.IAsyncAction RegisterExecutionProviderLibrariesAsync();
    }
}

实现说明

Infrastructure 类使用 Microsoft Store InstallControl API 在内部处理包管理，该 API 必须从 Windows ML 主运行时包调用，因为它 Microsoft 签名。这包括：

解析当前硬件配置的可用执行提供程序（EP）。
管理包生命周期和更新。
处理包注册和激活。
支持不同版本的执行提供程序

软件包发现

执行提供程序（EP）被打包为单独的 MSIX 组件，这些组件在其包清单中声明了com.microsoft.windowsmlruntime.executionprovider扩展。此设计允许在不影响 Windows ML 运行时组件的情况下独立更新执行提供程序。

Windows ML 运行时通过 Windows 11 中引入的包扩展基础结构发现这些包。对于每个发现的 EP，运行时都会评估硬件兼容性，并为当前系统加载适当的实现。

将 ONNX 运行时与 Windows ML 运行时配合使用

对于C++应用程序，调用 RegisterExecutionProviderLibrariesAsync后，使用 ONNX 运行时 C API 直接创建会话并运行推理。

对于 C# 应用程序，请直接使用 ONNX 运行时和 Microsoft.ML.OnnxRuntime 命名空间进行推理。

全新扁平化 C 样式 Win32 API 接口（Windows ML 启动 API 接口）

以下要求适用于下面记录的所有 Windows ML 启动函数。

要求	价值
NuGet 包	Microsoft.Windows.AI.MachineLearning
标头	WinMLBootstrap.h
命名空间	没有

WinMLStatusCallback 回调函数

typedef void (*WinMLStatusCallback)(void* context, HRESULT result);

WinMLInitialize 函数

/**
 * Initializes the WinML runtime, and adds dependencies to the current process.
 * You must call this function before you call any other WinML APIs.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 */
HRESULT WinMLInitialize(void);

WinMLUninitialize 函数

/**
 * Uninitializes the WinML runtime, and removes any dependencies in the current process.
 * You must call this function before before the process exits.
 *
 * @return No return value.
 */
void WinMLUninitialize(void);

WinMLGetInitializationStatus 函数

/**
 * Returns the initialization status of the WinML runtime.
 * S_OK indicates that the runtime is initialized and ready to use.
 *
 * @return HRESULT S_OK if the runtime is initialized; an error code otherwise.
 */
HRESULT WinMLGetInitializationStatus(void);

WinMLDownloadExecutionProviders 函数

/**
 * Downloads the execution providers applicable to the current device.
 * This function is asynchronous, and will return immediately.
 * A status result will be returned to the callback when the download is complete or has failed.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 */
HRESULT WinMLDownloadExecutionProviders(
    WinMLStatusCallback onCompletedCallback,
    void* context);

WinMLRegisterExecutionProviders 函数

/**
 * Registers the execution providers applicable to the current device.
 * This function is asynchronous, and will return immediately.
 * A status result will be returned to the callback when the registration is complete or has failed.
 *
 * @return HRESULT S_OK on success, an error code otherwise.
 */
HRESULT WinMLRegisterExecutionProviders(
    WinMLStatusCallback onCompletedCallback,
    void* context);

WinMLDeployMainPackage 函数

/**
 * Deploys the Microsoft.Windows.AI.MachineLearning MSIX package from the
 * msix/win-{arch} directory relative to the application executable.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 * S_OK is also returned if the package is already installed.
 */
HRESULT WinMLDeployMainPackage();

另请参阅

使用 Windows ML 运行 ONNX 模型（Microsoft.Windows.AI.MachineLearning）

通过