Menginisialisasi penyedia eksekusi dengan Windows ML

Halaman ini membahas cara yang lebih canggih untuk menangani pengunduhan dan pendaftaran penyedia eksekusi (PS) menggunakan Windows ML dengan lancar. Bahkan jika EP sudah diunduh di perangkat, Anda harus mendaftarkan EPs setiap kali aplikasi Anda berjalan sehingga EP akan muncul di ONNX Runtime.

Mengunduh dan mendaftar dalam satu panggilan

Untuk pengembangan awal, ada baiknya untuk hanya memanggil EnsureAndRegisterCertifiedAsync(), yang akan memastikan EP yang kompatibel dengan perangkat Anda ada (dan akan mengunduh EP jika tidak ada), dan kemudian mendaftarkan semua EP yang ada dengan ONNX Runtime. Perhatikan bahwa pada eksekusi pertama, metode ini dapat memakan waktu beberapa detik atau bahkan menit tergantung pada kecepatan jaringan dan IP Anda yang perlu diunduh.

C#

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

// Ensure execution providers compatible with device are present (downloads if necessary)
// and then registers all present execution providers with ONNX Runtime
await catalog.EnsureAndRegisterCertifiedAsync();

C++

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

// Ensure execution providers compatible with device are present (downloads if necessary)
// and then registers all present execution providers with ONNX Runtime
catalog.EnsureAndRegisterCertifiedAsync().get();

Python

# Please DO NOT use this API. It won't register EPs to the python ort env.

Petunjuk / Saran

Dalam aplikasi produksi, bungkus EnsureAndRegisterCertifiedAsync() panggilan dalam blok try-catch untuk menangani potensi kegagalan jaringan atau unduhan dengan anggun.

Daftarkan penyedia yang ada saja

Jika Anda ingin menghindari pengunduhan dan hanya mendaftarkan penyedia eksekusi yang sudah ada di komputer:

C#

var catalog = ExecutionProviderCatalog.GetDefault();

// Register only providers already present on the machine
// This avoids potentially long download times
await catalog.RegisterCertifiedAsync();

C++

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

// Register only providers already present on the machine
catalog.RegisterCertifiedAsync().get();

Python

# Please DO NOT use this API. It won't register EPs to the python ort env.

Temukan apakah ada EP (tanpa mengunduh)

Jika Anda ingin melihat apakah ada EP yang tidak hadir yang kompatibel dengan perangkat dan driver Anda, tetapi tidak ingin memulai pengunduhan, Anda dapat menggunakan metode FindAllProviders() dan melihat apakah ada penyedia yang memiliki ReadyState dari TidakHadir. Anda kemudian dapat memutuskan untuk menangani ini sesuka Anda (meluncurkan pengguna Anda ke "Layar penginstalan", menanyakan apakah mereka ingin menginstal, dll). Anda dapat memilih untuk terus menggunakan EPs yang sudah diunduh (dengan memanggil seperti yang RegisterCertifiedAsync() ditunjukkan di atas) jika Anda tidak ingin membuat pengguna Anda menunggu sekarang.

C#

var catalog = ExecutionProviderCatalog.GetDefault();

// Check if there are new EPs that need to be downloaded
if (catalog.FindAllProviders().Any(provider => provider.ReadyState == ExecutionProviderReadyState.NotPresent))
{
    // TODO: There are new EPs, decide how your app wants to handle that
}
else
{
    // All EPs are already present, just register them
    await catalog.RegisterCertifiedAsync();
}

C++

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

// Check if any providers need to be downloaded
bool needsDownload = false;
for (const auto& provider : providers)
{
    if (provider.ReadyState() == winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderReadyState::NotPresent)
    {
        needsDownload = true;
        break;
    }
}

if (needsDownload)
{
    // TODO: There are new EPs, decide how your app wants to handle that
}
else
{
    // All EPs are already present, just register them
    catalog.RegisterCertifiedAsync().get();
}

Python

# winml: winui3.microsoft.windows.ai.machinelearning
catalog = winml.ExecutionProviderCatalog.get_default()
providers = catalog.find_all_providers()
if any(provider.ready_state == winml.ExecutionProviderReadyState.NOT_PRESENT for provider in providers):
    # TODO: There are new EPs, decide how your app wants to handle that
    pass
else:
    # Register the providers one by one
    for provider in providers:
        provider.ensure_ready_async().get()
        ort.register_execution_provider_library(provider.name, provider.library_path)

Mengunduh dan mendaftarkan EP tertentu

Jika ada penyedia eksekusi tertentu yang ingin digunakan oleh aplikasi Anda, Anda dapat mengunduh dan mendaftarkan penyedia eksekusi tersebut tanpa mengunduh semua penyedia eksekusi yang kompatibel.

Anda akan terlebih dahulu menggunakan FindAllProviders() untuk mendapatkan semua EP yang kompatibel, lalu Anda dapat memanggil EnsureReadyAsync() pada ExecutionProvider untuk mengunduh penyedia eksekusi, dan memanggil TryRegister() untuk mendaftarkan penyedia eksekusi tersebut.

C#

var catalog = ExecutionProviderCatalog.GetDefault();

// Get the QNN provider, if present
var qnnProvider = catalog.FindAllProviders()
    .FirstOrDefault(i => i.Name == "QNNExecutionProvider");

if (qnnProvider != null)
{
    // Download it
    var result = await qnnProvider.EnsureReadyAsync();

    // If download succeeded
    if (result != null && result.Status == ExecutionProviderReadyResultState.Success)
    {
        // Register it
        bool registered = qnnProvider.TryRegister();
    }
}

C++

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

// Get the QNN provider, if present
auto providers = catalog.FindAllProviders();
winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProvider qnnProvider{ nullptr };
for (auto const& p : providers)
{
    if (p.Name() == L"QNNExecutionProvider")
    {
        qnnProvider = p;
        break;
    }
}

if (qnnProvider)
{
    // Download required components for this provider (if not already present)
    auto result = qnnProvider.EnsureReadyAsync().get();

    if (result && result.Status() == winrt::Microsoft::Windows::AI::MachineLearning::ExecutionProviderReadyResultState::Success)
    {
        // Register the provider with ONNX Runtime
        bool registered = qnnProvider.TryRegister();
    }
}

Python

catalog = winml.ExecutionProviderCatalog.get_default()
providers = catalog.find_all_providers()

qnn_provider = next((provider for provider in providers if provider.name == 'QNNExecutionProvider'), None)
if qnn_provider is not None:
    # Download required components for this provider (if not already present)
    result = qnn_provider.ensure_ready_async().get()
    if result == winml.ExecutionProviderReadyResultState.SUCCESS:
        # Register the provider with ONNX Runtime
        ort.register_execution_provider_library(qnn_provider.name, qnn_provider.library_path)

Contoh aplikasi produksi

Untuk aplikasi produksi, berikut adalah contoh apa yang mungkin ingin dilakukan aplikasi Anda untuk memberi diri Anda dan pengguna Anda mengontrol kapan unduhan terjadi. Anda dapat memeriksa apakah penyedia eksekusi baru tersedia dan mengunduhnya secara kondisional:

C#

using Microsoft.Windows.AI.MachineLearning;

var catalog = ExecutionProviderCatalog.GetDefault();

// Filter to the EPs our app supports/uses
var providers = catalog.FindAllProviders().Where(p =>
    p.Name == "MIGraphXExecutionProvider" ||
    p.Name == "VitisAIExecutionProvider" ||
    p.Name == "OpenVINOExecutionProvider" ||
    p.Name == "QNNExecutionProvider" ||
    p.Name == "NvTensorRtRtxExecutionProvider"
);

if (providers.Any(p => p.ReadyState == ExecutionProviderReadyState.NotPresent))
{
    // Show UI to user asking if they want to download new execution providers
    bool userWantsToDownload = await ShowDownloadDialogAsync();

    if (userWantsToDownload)
    {
        // Download all EPs
        foreach (var p in providers)
        {
            if (p.ReadyState == ExecutionProviderReadyState.NotPresent)
            {
                // Ignore result handling here; production code could inspect status
                await p.EnsureReadyAsync();
            }
        }

        // And register all EPs
        await catalog.RegisterCertifiedAsync();
    }
    else
    {
        // Register only already-present EPs
        await catalog.RegisterCertifiedAsync();
    }
}

C++

using namespace winrt::Microsoft::Windows::AI::MachineLearning;

auto catalog = ExecutionProviderCatalog::GetDefault();
auto allProviders = catalog.FindAllProviders();

// Filter to the EPs our app supports/uses
std::vector<ExecutionProvider> targetProviders;
for (auto const& p : allProviders)
{
    auto name = p.Name();
    if (name == L"VitisAIExecutionProvider" ||
        name == L"OpenVINOExecutionProvider" ||
        name == L"QNNExecutionProvider" ||
        name == L"NvTensorRtRtxExecutionProvider")
    {
        targetProviders.push_back(p);
    }
}

bool needsDownload = false;
for (auto const& p : targetProviders)
{
    if (p.ReadyState() == ExecutionProviderReadyState::NotPresent)
    {
        needsDownload = true;
        break;
    }
}

if (needsDownload)
{
    // Show UI to user or check application settings to confirm download
    bool userWantsToDownload = ShowDownloadDialog();
    if (userWantsToDownload)
    {
        // Download only the missing target providers
        for (auto const& p : targetProviders)
        {
            if (p.ReadyState() == ExecutionProviderReadyState::NotPresent)
            {
                // Ignore result handling here; production code could inspect status
                p.EnsureReadyAsync().get();
            }
        }
        // Register all (both previously present and newly downloaded) providers
        catalog.RegisterCertifiedAsync().get();
    }
    else
    {
        // User deferred download; register only already-present providers
        catalog.RegisterCertifiedAsync().get();
    }
}
else
{
    // All target EPs already present
    catalog.RegisterCertifiedAsync().get();
}

Python

# remove the msvcp140.dll from the winrt-runtime package.
# So it does not cause issues with other libraries.
from pathlib import Path
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()

from winui3.microsoft.windows.applicationmodel.dynamicdependency.bootstrap import (
    InitializeOptions,
    initialize
)
import winui3.microsoft.windows.ai.machinelearning as winml
import onnxruntime as ort

with initialize(options=InitializeOptions.ON_NO_MATCH_SHOW_UI):
    catalog = winml.ExecutionProviderCatalog.get_default()
    # Filter EPs that the app supports
    providers = [provider for provider in catalog.find_all_providers() if provider.name in [
        'VitisAIExecutionProvider',
        'OpenVINOExecutionProvider',
        'QNNExecutionProvider',
        'NvTensorRtRtxExecutionProvider'
    ]]

    # Download and make ready missing EPs if the user wants to
    if any(provider.ready_state == winml.ExecutionProviderReadyState.NOT_PRESENT for provider in providers):
        # Ask the user if they want to download the missing packages
        if user_wants_to_download:
            for provider in [provider for provider in providers if provider.ready_state == winml.ExecutionProviderReadyState.NOT_PRESENT]:
                provider.ensure_ready_async().get()

    # Make ready the existing EPs
    for provider in [provider for provider in providers if provider.ready_state == winml.ExecutionProviderReadyState.NOT_READY]:
        provider.ensure_ready_async().get()

    # Register all ready EPs
    for provider in [provider for provider in providers if provider.ready_state == winml.ExecutionProviderReadyState.READY]:
        ort.register_execution_provider_library(provider.name, provider.library_path)

Lihat juga

• Penyedia eksekusi dan riwayat rilis yang didukung
• Memperbarui penyedia eksekusi
• Periksa versi penyedia eksekusi
• Masalah pengunduhan penyedia eksekusi yang umum