API Windows ML

Untuk panduan konseptual, lihat Menjalankan model ONNX dengan Windows ML).

Anda dapat menganggap API dalam paket Microsoft.WindowsAppSDK.ML NuGet sebagai superset dari dua set ini:

• API Windows ML. API ML Windows di namespace Microsoft.Windows.AI.MachineLearning , seperti kelas ExecutionProviderCatalog dan metodenya (yang merupakan API Runtime Windows). API ini didokumenkan dalam topik yang Anda baca sekarang.
• ONNX Runtime API. Implementasi Windows ML (dalam paket Microsoft.WindowsAppSDK.ML NuGet) API tertentu dari ONNX Runtime (ORT). Untuk dokumentasi, lihat dokumen ONNX Runtime API. Misalnya, struktur OrtCompileApi. Untuk contoh kode yang menggunakan API ini, dan tautan lainnya ke dokumentasi, lihat tutorial Menggunakan ML Windows untuk menjalankan model ResNet-50 .

Paket NuGet Microsoft.WindowsAppSDK.ML

Runtime Microsoft Windows ML menyediakan API untuk pembelajaran mesin dan operasi AI di aplikasi Windows. Paket Microsoft.WindowsAppSDK.ML NuGet menyediakan file runtime .winmd Windows ML untuk digunakan dalam proyek C# dan C++.

Roda Pywinrt Python

Runtime Microsoft Windows ML memanfaatkan proyek pywinrt untuk menyediakan akses Python ke API Windows ML yang sama. Nama paketnya adalah winui3-Microsoft.Windows.AI.MachineLearning. Paket tambahan diperlukan untuk menggunakan Windows App SDK di python. Untuk detailnya, lihat topik Jalankan model ONNX dengan Windows ML .

API Windows ML

Kelas ExecutionProviderCatalog

Kelas ExecutionProviderCatalog menyediakan metode untuk menemukan, memperoleh, dan mendaftarkan penyedia eksekusi AI (EPs) untuk digunakan dengan ONNX Runtime. Ini menangani kompleksitas manajemen paket dan pemilihan perangkat keras.

Kelas ini adalah titik masuk bagi aplikasi Anda untuk mengakses akselerasi pembelajaran mesin yang dioptimalkan perangkat keras melalui runtime Windows ML.

C#

// Get the default catalog
var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();

// Ensure and register all compatible execution providers
await catalog.EnsureAndRegisterAllAsync();

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

C++/WinRT

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

// Ensure and register all compatible execution providers
catalog.EnsureAndRegisterAllAsync().get();

// Use ONNX Runtime C API directly for inference

Python

import winui3.microsoft.windows.ai.machinelearning as winml
# Get the default catalog
catalog = winml.ExecutionProviderCatalog.get_default()
# DO NOT call EnsureAndRegisterAllAsync() in Python. That will not work for the onnxruntime Python environment.
# Instead, register execution providers following this pattern:
providers = catalog.find_all_providers()
    for provider in providers:
        provider.ensure_ready_async().get()
        ort.register_execution_provider_library(provider.name, provider.library_path)

Metode ExecutionProviderCatalog

Metode ExecutionProviderCatalog.GetDefault

Mengembalikan instans ExecutionProviderCatalog default yang menyediakan akses ke semua penyedia eksekusi pada sistem.

C#

var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();

C++/WinRT

auto catalog = winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();

Python

catalog = winml.ExecutionProviderCatalog.get_default()

Metode ExecutionProviderCatalog.FindAllProviders

Mengembalikan kumpulan semua penyedia eksekusi yang kompatibel dengan perangkat keras saat ini.

C#

var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();
var providers = catalog.FindAllProviders();

foreach (var provider in providers)
{
    Console.WriteLine($"Found provider: {provider.Name}, Type: {provider.DeviceType}");
}

C++/WinRT

auto catalog = winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();
auto providers = catalog.FindAllProviders();

for (const auto& provider : providers)
{
    std::wcout << L"Found provider: " << provider.Name().c_str() 
              << L", Type: " << static_cast<int>(provider.DeviceType()) << L"\n";
}

Python

catalog = winml.ExecutionProviderCatalog.get_default()
providers = catalog.find_all_providers()
for provider in providers:
    print(f"Found provider: {provider.name}, Type: {provider.device_type}")

Metode ExecutionProviderCatalog.EnsureAndRegisterAllAsync

Memastikan semua penyedia eksekusi yang kompatibel siap dan mendaftarkannya dengan ONNX Runtime.

C#

var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();

try
{
    // This will ensure providers are ready and register them with ONNX Runtime
    await catalog.EnsureAndRegisterAllAsync();
    Console.WriteLine("All execution providers are ready and registered");
}
catch (Exception ex)
{
    Console.WriteLine($"Failed to prepare execution providers: {ex.Message}");
}

C++/WinRT

auto catalog = winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();

try 
{
    // This will ensure providers are ready and register them with ONNX Runtime
    catalog.EnsureAndRegisterAllAsync().get();
    std::wcout << L"All execution providers are ready and registered\n";
}
catch (const winrt::hresult_error& ex) 
{
    std::wcout << L"Failed to prepare execution providers: " << ex.message().c_str() << L"\n";
}

Python

# DO NOT call EnsureAndRegisterAllAsync() in Python. 
# Onnxruntime's Python and native environments are separate.
# This method will not work for the onnxruntime Python environment.

Metode RegisterAllAsync pada ExecutionProviderCatalog

Mendaftarkan semua penyedia eksekusi yang kompatibel dengan ONNX Runtime tanpa memastikan mereka siap. Ini hanya mendaftarkan penyedia yang sudah ada di komputer, menghindari waktu unduhan yang berpotensi lama yang mungkin diperlukan oleh EnsureAndRegisterAllAsync.

C#

var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();
await catalog.RegisterAllAsync();

C++/WinRT

auto catalog = winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();
catalog.RegisterAllAsync().get();

Python

# DO NOT call RegisterAllAsync() in Python.

Kelas ExecutionProvider

Kelas ExecutionProvider mewakili akselerator perangkat keras tertentu yang dapat digunakan untuk inferensi pembelajaran mesin.

Metode ExecutionProvider

Metode ExecutionProvider.EnsureReadyAsync

Memastikan penyedia eksekusi siap digunakan dengan mengunduh dan menginstal komponen yang diperlukan.

C#

var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();
var providers = catalog.FindAllProviders();

foreach (var provider in providers)
{
    await provider.EnsureReadyAsync();
    Console.WriteLine($"Provider {provider.Name} is ready");
}

C++/WinRT

auto catalog = winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();
auto providers = catalog.FindAllProviders();

for (const auto& provider : providers)
{
    provider.EnsureReadyAsync().get();
    std::wcout << L"Provider " << provider.Name().c_str() << L" is ready\n";
}

Python

catalog = winml.ExecutionProviderCatalog.get_default()
providers = catalog.find_all_providers()
for provider in providers:
    provider.ensure_ready_async().get()
    print(f"Provider {provider.name} is ready")

Metode ExecutionProvider.TryRegister

Mencoba mendaftarkan penyedia eksekusi dengan ONNX Runtime dan mengembalikan boolean yang menunjukkan keberhasilan.

C#

var catalog = Microsoft.Windows.AI.MachineLearning.ExecutionProviderCatalog.GetDefault();
var providers = catalog.FindAllProviders();

foreach (var provider in providers)
{
    await provider.EnsureReadyAsync();
    bool registered = provider.TryRegister();
    Console.WriteLine($"Provider {provider.Name} registration: {(registered ? "Success" : "Failed")}");
}

C++/WinRT

auto catalog = winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderCatalog::GetDefault();
auto providers = catalog.FindAllProviders();

for (const auto& provider : providers)
{
    provider.EnsureReadyAsync().get();
    bool registered = provider.TryRegister();
    std::wcout << L"Provider " << provider.Name().c_str() 
              << L" registration: " << (registered ? L"Success" : L"Failed") << L"\n";
}

Python

catalog = winml.ExecutionProviderCatalog.get_default()
providers = catalog.find_all_providers()
for provider in providers:
    provider.ensure_ready_async().get()
    # DO NOT call TryRegister() in Python.
    # Use the name and library_path to directly register with onnxruntime.
    ort.register_execution_provider_library(provider.name, provider.library_path)
    print(f"Registered execution provider: {provider.name}")

Properti PenyediaEksekusi

Nama	Tipe	Deskripsi
Nama	string	Mendapatkan nama penyedia eksekusi
Jenis Perangkat	TipePerangkatPenyediaEksekusi	Mendapatkan jenis perangkat (CPU, GPU, NPU, dll.)
IsReady	bool	Memeriksa apakah penyedia eksekusi siap digunakan
LibraryPath	string	Mendapatkan jalur ke pustaka penyedia eksekusi

Catatan implementasi

Runtime Windows ML terintegrasi dengan Windows App SDK dan bergantung pada mekanisme penyebaran dan bootstrapping dari Windows App SDK tersebut:

• Secara otomatis menemukan penyedia eksekusi yang kompatibel dengan perangkat keras saat ini
• Mengelola masa pakai dan pembaruan paket
• Menangani pendaftaran dan aktivasi paket
• Mendukung berbagai versi penyedia eksekusi

Framework-Dependent Penyebaran

Windows ML dikirimkan sebagai komponen yang bergantung pada kerangka kerja . Ini berarti aplikasi Anda harus:

• Referensikan paket Utama Windows App SDK NuGet dengan menambahkan referensi ke Microsoft.WindowsAppSDK (disarankan)
• Atau, mereferensikan baik Microsoft.WindowsAppSDK.ML maupun Microsoft.WindowsAppSDK.Runtime

Untuk informasi selengkapnya tentang penyebaran aplikasi Windows App SDK, lihat dokumentasi Paket dan sebarkan aplikasi Windows .

Menggunakan ONNX Runtime dengan Windows ML

Untuk aplikasi C++, setelah mendaftarkan penyedia eksekusi, gunakan ONNX Runtime C API secara langsung untuk membuat sesi dan menjalankan inferensi.

Untuk aplikasi C#, gunakan ONNX Runtime secara langsung untuk inferensi menggunakan Microsoft.ML.OnnxRuntime namespace.

Untuk aplikasi Python, gunakan roda Runtime ONNX terpisah (onnxruntime) untuk inferensi. Untuk rilis eksperimental, silakan gunakan onnxruntime-winml==1.22.0.post2 paket dari indeks https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/ORT-Nightly/pypi/simple.

Catatan Python

Menginisialisasi Windows App SDK

Semua panggilan Windows ML harus terjadi setelah Windows App SDK diinisialisasi. Ini dapat dilakukan dengan kode berikut:

from winui3.microsoft.windows.applicationmodel.dynamicdependency.bootstrap import (
    InitializeOptions,
    initialize
)
with initialize(options = InitializeOptions.ON_NO_MATCH_SHOW_UI):
    # Your Windows ML code here

Pendaftaran terjadi di luar WinML

Runtime ONNX dirancang sedemikian rupa sehingga lingkungan Python dan lingkungan asli terpisah. Dan panggilan pendaftaran asli dalam proses yang sama tidak akan berfungsi untuk lingkungan Python. Dengan demikian, pendaftaran penyedia eksekusi harus dilakukan dengan Python API secara langsung.

Menggunakan pywinrt dalam proses lain

Karena beberapa keterbatasan dalam proyeksi Python pada WinRT, disarankan untuk mendapatkan informasi penyedia eksekusi dalam proses pekerja terpisah. Untuk contoh lengkapnya, lihat sampel Windows ML Python.

Lihat juga

• Menjalankan model ONNX dengan Windows ML
• Dokumentasi Windows App SDK
• Windows App SDK di GitHub
• Sampel Windows ML
• Dokumentasi API Runtime ONNX
• Mengemas dan menyebarkan aplikasi Windows