Skip to content

README.md

Latest commit

 

History

History
118 lines (87 loc) · 5.92 KB

README.md

File metadata and controls

118 lines (87 loc) · 5.92 KB
Raw

Windows ML Samples

This repository contains comprehensive samples demonstrating how to use Windows ML and ONNX Runtime for machine learning inference on Windows. These samples emphasize Windows ML integration with various Windows technologies via the Windows App SDK. Samples for the ONNX Runtime can be found in this repository.

Overview

Windows ML enables high-performance, reliable inferencing of machine learning models on Windows devices. These samples demonstrate key concepts including:

  • Execution Provider Selection - Automatic discovery and acquisition of execution providers for hardware-accelerated inference
  • Model Compilation - Optimize models for specific hardware during first run
  • Compiled Model Compatibility - Validate cached compiled models against the current execution provider and devices before reuse
  • Windows App SDK Deployment Types - Use models in a variety of different Windows App SDK deployment modes (e.g., self-contained, framework-based deployment)

Prerequisites

  • Windows 11 PC running version 24H2 (build 26100) or greater
  • Visual Studio 2022 with the following workloads:
    • Desktop development with C++ (required for C++ samples)
    • .NET desktop development (required for C# samples)
  • Windows App SDK 2.1.3 or later
  • CMake 3.21 or later (required for CMake samples)
  • NuGet CLI (nuget.exe on PATH, required for CMake samples)
  • Python 3.10-3.13 for Python samples on x64 and ARM64 devices

Sample Categories

C++ Samples

Sample Description Key Features
CppConsoleDesktop Basic C++ console application EP discovery, command-line options, model compilation
CppConsoleDesktop.FrameworkDependent Framework-dependent deployment variant Shared runtime, smaller deployment footprint
CppConsoleDesktop.SelfContained Self-contained deployment variant Standalone deployment, no runtime dependencies

C++ CMake Samples

Sample Description Key Features
WinMLEpCatalog CMake-based EP catalog sample using the WinML C API CMake build system, automatic NuGet restore, EP discovery and registration

C++ ABI Samples

Sample Description Key Features
cpp-abi Direct ABI implementation using raw COM interfaces Automatic ABI header generation, no projections

C# Samples

Console Applications

Sample Description Key Features
CSharpConsoleDesktop Basic C# console application Shared helper usage, command-line interface

GUI Applications

Sample UI Framework Description
cs-wpf WPF Image classification example
cs-winforms Windows Forms Image classification example
cs-winui WinUI 3 Image classification example

Python Samples

Sample Description Key Features
SqueezeNetPython Python image classification WinML Python bindings, batch image processing

Common Workflow

Most samples follow this pattern:

  1. Initialize Environment - Create ONNX Runtime environment
  2. Register Execution Providers - Discover and register available hardware accelerators
  3. Validate Cached Model - Extract compatibility metadata from an existing compiled model and validate it against devices from the matching execution provider
  4. Compile or Load Model - Reuse only an optimal compiled model; otherwise compile when requested or use the original ONNX model
  5. Preprocess Input - Convert images to model input format
  6. Run Inference - Execute model and get predictions
  7. Process Results - Apply softmax and display top predictions

Compatibility is reported through OrtCompiledModelCompatibility. The samples reuse a compiled model only for EP_SUPPORTED_OPTIMAL; EP_SUPPORTED_PREFER_RECOMPILATION, EP_UNSUPPORTED, EP_NOT_APPLICABLE, and missing compatibility metadata trigger recompilation or fallback. For automatic policy selection, the samples mirror ONNX Runtime's device ordering so compatibility is checked only for the preferred and fallback devices that the policy selects. Because GetModelCompatibilityForEpDevices requires devices from a single execution provider, those devices are validated one EP group at a time. The preferred group must have matching, optimal metadata; fallback groups without metadata are ignored, while any fallback group with non-optimal metadata rejects the cache.

Model Files

Samples use these pre-trained models:

  • SqueezeNet - Lightweight image classification (included)
  • ResNet-50 - High-accuracy image classification (requires AI Toolkit conversion)

Hardware Support

These samples detect and utilize the CPU, GPU, and NPU.

Diagnostics

Resource Description
capture-logs Scripts and profiles for capturing Windows ML diagnostic logs (docs)

Getting Help