Начало работы с Windows ML

• .NET 8 или более поздней версии для использования всех API машинного обучения Windows
  • С помощью .NET 6 можно установить поставщиков выполнения с помощью Microsoft.Windows.AI.MachineLearning API, но использовать Microsoft.ML.OnnxRuntime API нельзя.
• Ориентация на конкретный TFM для Windows 10, например net8.0-windows10.0.19041.0 или более поздней версии.

C++20 или более поздней версии.

• Visual Studio 2022 с рабочей нагрузкой C++ (включает компилятор C)
• CMake 3.21 или более поздней версии

Python версии 3.10 до 3.13 на устройствах x64 и ARM64.

Windows ML включается в пакет SDK для приложений Windows 1.8.1 или более поздней версии.

Самый простой способ использовать Windows ML — установить Microsoft.WindowsAppSDK.ML пакет NuGet, который использует автономное развертывание по умолчанию. Дополнительные сведения о параметрах развертывания см. в статье "Развертывание приложения ".

dotnet add package Microsoft.WindowsAppSDK.ML

Windows ML включается в пакет SDK для приложений Windows 1.8.1 или более поздней версии.

Обратитесь к руководству по использованию Windows App SDK в существующем проекте, чтобы добавить его в свой проект, или, если вы уже используете Windows App SDK, обновите пакеты SDK.

Windows ML C API включены в Microsoft.WindowsAppSDK.ML версию 1.8.2141 пакета NuGet или более позднюю. Пакет NuGet поставляет файлы конфигурации CMake в build/cmake/, которые можно использовать напрямую. Маркер @WINML_VERSION@ разрешается на этапе сборки NuGet, поэтому дополнительная обработка не требуется.

Использование пакета NuGet...

1. Скачайте или восстановите пакет NuGet (например, с помощью nuget restore или вручную)
2. Извлечение или ссылка на корневой каталог пакета
3. Установите CMAKE_PREFIX_PATH в подкаталог build/cmake пакета

Пример CMakeLists.txt

cmake_minimum_required(VERSION 3.21)
project(MyApp LANGUAGES CXX)

# C++20 standard for modern features (std::format, etc.)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(microsoft.windows.ai.machinelearning CONFIG REQUIRED)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE WindowsML::Api WindowsML::OnnxRuntime)

add_custom_command(TARGET MyApp POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        $<TARGET_RUNTIME_DLLS:MyApp> $<TARGET_FILE_DIR:MyApp>
    COMMAND_EXPAND_LISTS
    VERBATIM
)

Примеры команд сборки

# Point CMAKE_PREFIX_PATH to the NuGet package's cmake directory
cmake -B build -S . -DCMAKE_PREFIX_PATH="C:/packages/Microsoft.WindowsAppSDK.ML/build/cmake"
cmake --build build --config Release

Пакет NuGet включает собственную конфигурацию cmake под build/cmake/, которая понимает структуру каталогов NuGet (каталоги, относящиеся к архитектуре, находятся под lib/native/ и runtimes/). Архитектура определяется из CMAKE_GENERATOR_PLATFORM, CMAKE_VS_PLATFORM_NAMEили CMAKE_SYSTEM_PROCESSOR.

Файл порта vcpkg создает отдельный упрощенный файл конфигурации, который сопоставляется со стандартной структурой vcpkg (lib/ и bin/). Обе конфигурации используют один и тот же целевой файл (microsoft.windows.ai.machinelearning-targets.cmake), который определяет целевые объекты IMPORTED.

Одни и те же целевые объекты (WindowsML::WindowsML, WindowsML::Api, WindowsML::OnnxRuntime) WindowsML::DirectMLдоступны в обоих режимах потребления. Используйте стандартное выражение генератора CMake 3.21 $<TARGET_RUNTIME_DLLS> для копирования библиотек DLL среды выполнения в выходной каталог сборки.

Привязка Python использует проект pywinrt для проекции пакета SDK для приложений Windows. Убедитесь, что ваша версия Python не установлена из Microsoft Store (вы можете установить распакованную версию с python.org или через winget). Пример зависит от использования API динамической зависимости пакета SDK для приложений Windows, который действителен только для распакованных приложений.

Установите пакеты Python с помощью следующих команд:

pip install wasdk-Microsoft.Windows.AI.MachineLearning[all] wasdk-Microsoft.Windows.ApplicationModel.DynamicDependency.Bootstrap onnxruntime-windowsml

Убедитесь, что wasdk- версия пакетов соответствует версии WindowsAppRuntime.

Самый простой способ начать работу — разрешить Windows ML автоматически обнаруживать, скачивать и регистрировать последнюю версию всех совместимых поставщиков выполнения. Прежде чем использовать их, поставщики выполнения должны быть зарегистрированы в среде выполнения ONNX в Windows ML. И если они еще не скачаны, их необходимо сначала скачать. Вызов EnsureAndRegisterCertifiedAsync() выполняет оба из этих действий на одном шаге.

using Microsoft.ML.OnnxRuntime;
using Microsoft.Windows.AI.MachineLearning;

// First we create a new instance of EnvironmentCreationOptions
EnvironmentCreationOptions envOptions = new()
{
    logId = "WinMLDemo", // Use an ID of your own choice
    logLevel = OrtLoggingLevel.ORT_LOGGING_LEVEL_ERROR
};

// And then use that to create the ORT environment
using var ortEnv = OrtEnv.CreateInstanceWithOptions(ref envOptions);

// Get the default ExecutionProviderCatalog
var catalog = ExecutionProviderCatalog.GetDefault();

// Ensure and register all compatible execution providers with ONNX Runtime
// This downloads any necessary components and registers them
await catalog.EnsureAndRegisterCertifiedAsync();

Самый простой способ начать работу — разрешить Windows ML автоматически обнаруживать, скачивать и регистрировать последнюю версию всех совместимых поставщиков выполнения. Прежде чем использовать их, поставщики выполнения должны быть зарегистрированы в среде выполнения ONNX в Windows ML. И если они еще не скачаны, их необходимо сначала скачать. Вызов EnsureAndRegisterCertifiedAsync() выполняет оба из этих действий на одном шаге.

#include <winrt/Microsoft.Windows.AI.MachineLearning.h>
#include <winml/onnxruntime_cxx_api.h>

// First we need to create an ORT environment
Ort::Env env(ORT_LOGGING_LEVEL_ERROR, "WinMLDemo"); // Use an ID of your own choice

// Get the default ExecutionProviderCatalog
winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog catalog =
    winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();

// Ensure and register all compatible execution providers with ONNX Runtime
catalog.EnsureAndRegisterCertifiedAsync().get();

С помощью API для C необходимо скачать конкретного провайдера исполнения и затем вручную зарегистрировать его путь в ONNX Runtime.

#include <WinMLEpCatalog.h>
#include <onnxruntime_cxx_api.h> // Or <onnxruntime_c_api.h> if just using C
#include <filesystem>
#include <string>

// Initialize ONNX Runtime
Ort::Env env(ORT_LOGGING_LEVEL_ERROR, "WinMLDemo"); // Use an ID of your own choice

// --- Windows ML: Get EP catalog handle ---
WinMLEpCatalogHandle catalog = nullptr;
HRESULT hr = WinMLEpCatalogCreate(&catalog);
if (FAILED(hr))
{
    // Handle error
    return;
}

// --- Windows ML: Find, download, and register a specific EP (in this case, QNN) ---
WinMLEpHandle ep = nullptr;
hr = WinMLEpCatalogFindProvider(catalog, "QNN", NULL, &ep);
if (SUCCEEDED(hr))
{
    // Windows ML: Download the EP if it isn't already downloaded
    WinMLEpEnsureReady(ep);

    // Windows ML: Get the EP library path
    size_t pathSize = 0;
    WinMLEpGetLibraryPathSize(ep, &pathSize);
    std::string libraryPathUtf8(pathSize, '\0');
    WinMLEpGetLibraryPath(ep, pathSize, libraryPathUtf8.data(), nullptr);

    // Register the EP with ONNX Runtime using the C++ API
    std::filesystem::path libraryPath(libraryPathUtf8);
    env.RegisterExecutionProviderLibrary("QNN", libraryPath.wstring());
}

// --- Windows ML: Release the EP catalog handle ---
WinMLEpCatalogRelease(catalog);

С помощью API Python можно перечислить все совместимые поставщики выполнения, а затем вручную зарегистрировать пути в onNX Runtime.

import sys
from pathlib import Path
import traceback

_winml_instance = None

class WinML:
    def __new__(cls, *args, **kwargs):
        global _winml_instance
        if _winml_instance is None:
            _winml_instance = super(WinML, cls).__new__(cls, *args, **kwargs)
            _winml_instance._initialized = False
        return _winml_instance

    def __init__(self):
        if self._initialized:
            return
        self._initialized = True

        self._fix_winrt_runtime()
        from winui3.microsoft.windows.applicationmodel.dynamicdependency.bootstrap import (
            InitializeOptions,
            initialize
        )
        import winui3.microsoft.windows.ai.machinelearning as winml
        self._win_app_sdk_handle = initialize(options=InitializeOptions.ON_NO_MATCH_SHOW_UI)
        self._win_app_sdk_handle.__enter__()
        catalog = winml.ExecutionProviderCatalog.get_default()
        self._providers = catalog.find_all_providers()
        self._ep_paths : dict[str, str] = {}
        for provider in self._providers:
            provider.ensure_ready_async().get()
            if provider.library_path == '':
                continue
            self._ep_paths[provider.name] = provider.library_path
        self._registered_eps : list[str] = []

    def __del__(self):
        self._providers = None
        self._win_app_sdk_handle.__exit__(None, None, None)

    def _fix_winrt_runtime(self):
        """
        This function removes the msvcp140.dll from the winrt-runtime package.
        So it does not cause issues with other libraries.
        """
        from importlib import metadata
        site_packages_path = Path(str(metadata.distribution('winrt-runtime').locate_file('')))
        dll_path = site_packages_path / 'winrt' / 'msvcp140.dll'
        if dll_path.exists():
            dll_path.unlink()

    def register_execution_providers_to_ort(self) -> list[str]:
        import onnxruntime as ort
        for name, path in self._ep_paths.items():
            if name not in self._registered_eps:
                try:
                    ort.register_execution_provider_library(name, path)
                    self._registered_eps.append(name)
                except Exception as e:
                    print(f"Failed to register execution provider {name}: {e}", file=sys.stderr)
                    traceback.print_exc()
        return self._registered_eps

WinML().register_execution_providers_to_ort()