安裝 Windows ML 執行提供者

在 Windows ML 中，某些執行提供者（EP）會透過 Windows ML ExecutionProviderCatalog API 動態下載、安裝並全系統共享，並自動 更新。 想了解有哪些 EP，請參閱 Windows ML 執行提供者。

本頁說明如何使用 EP 目錄將 Windows ML EP 安裝到使用者的裝置上。 關於直接在應用程式中打包EP的替代方式，請參見「自帶EP」。 要在這些選項中做選擇，請參考 Windows ML EP 和自行選擇的解決方案。

安裝完成後，你需要先在 ONNX 執行時環境中註冊 Windows ML 執行提供器，然後再使用它們。

Note

當您的應用程式呼叫 EnsureReadyAsync() 或 EnsureAndRegisterCertifiedAsync() 時，Windows 會下載 Windows ML EPs。 對於離線、受限網路、受管理或嚴格固定版本的環境，請參閱 自備 EP 和 Windows ML EP 與自備 EP 的比較。

安裝所有相容的 EP

最簡單的方法是呼叫 EnsureAndRegisterCertifiedAsync()，它會下載並安裝使用者裝置上所有可用的 EP，然後在一次通話中將所有 EP 註冊到 ONNX 執行時。 如果您的應用程式需要更多對提供者發現、下載或註冊的控制，請參閱下方「 尋找所有相容的 EP 並 安裝特定 EP 」。

Note

第一次執行時，這種方法可能需要數秒甚至幾分鐘，視網路速度和需要下載的 EP 而定。

// 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();

尋找所有相容的 EP

你可以呼叫該方法 FindAllProviders()，來查看使用者裝置上可用的EP（包括未安裝的EP）。

ExecutionProviderCatalog catalog = ExecutionProviderCatalog.GetDefault();

// Find all available EPs (including non-installed EPs)
ExecutionProvider[] providers = catalog.FindAllProviders();

foreach (var provider in providers)
{
    Console.WriteLine($"{provider.Name}: {provider.ReadyState}");
}

回傳的執行提供者會依使用者的裝置及可用的執行提供者而有所不同。 在一台尚未安裝任何執行服務供應商的相容高通裝置上，上述程式碼輸出如下......

QNNExecutionProvider: NotPresent

每個 ExecutionProvider 都有一個 ReadyState 屬性，顯示其在裝置上的當前狀態。 了解這些狀態有助於你判斷應用程式需要採取哪些行動。

ReadyState Definition 後續步驟
NotPresent EP 並未安裝在用戶端裝置上。 呼叫 EnsureReadyAsync() 下載並安裝 EP，並將其加入你應用程式的執行時相依圖。
NotReady EP 安裝在用戶端裝置上，但尚未被加入應用程式的執行時相依性圖中。 呼叫 EnsureReadyAsync() 將 EP 加入你的應用程式的運行時相依關係圖。
Ready EP 已安裝在用戶端裝置上，並已加入你應用程式的執行時相依圖中。 呼叫 TryRegister() 以註冊 EP 使用 ONNX 執行時。

安裝特定的 EP

如果你的應用程式想使用特定的 ExecutionProvider ，且其 ReadyState 是 NotPresent，你可以透過呼叫 EnsureReadyAsync()來下載並安裝。

您將先使用 FindAllProviders() 來取得所有相容的執行提供者，然後您可以呼叫EnsureReadyAsync()以針對特定的ExecutionProvider下載該執行提供者，並且呼叫 TryRegister()來註冊該特定的執行提供者。

// Download and install a NotPresent EP
var result = await provider.EnsureReadyAsync();

// Check that the download and install was successful
bool installed = result.Status == ExecutionProviderReadyResultState.Success;

處理安裝結果

EnsureReadyAsync() 回傳 ExecutionProviderReadyResult。 在建立會話或註冊提供者前，請先確認其 狀態 。 若狀態為 Failure，請檢查 ExtendedError （HRESULT）及 DiagnosticText，並參見 「故障排除執行提供者下載問題」。 如果狀態是 InProgress，行動尚未完成;請等待結果後再進行。

安裝中，顯示進度

下載與安裝 EP 的 API 包含回調，提供進度更新，讓您能顯示進度指示器，讓使用者隨時掌握最新資訊。

進度條截圖，反映下載進度 

// Start the download and install of a NotPresent EP
var operation = provider.EnsureReadyAsync();

// Listen to progress callback
operation.Progress = (asyncInfo, progressInfo) =>
{
    // Dispatch to UI thread (varies based on UI platform)
    _dispatcherQueue.TryEnqueue(() =>
    {
        // progressInfo is out of 100, convert to 0-1 range
        double normalizedProgress = progressInfo / 100.0;

        // Display the progress to the user
        Progress = normalizedProgress;
    };
};

// Await for the download and install to complete
var result = await operation;

// Check that the download and install was successful
bool installed = result.Status == ExecutionProviderReadyResultState.Success;

後續步驟

現在你已經安裝了執行提供程式，請參考 註冊 Windows ML EPs， 了解如何將它們註冊以供 ONNX Runtime 使用。

生產應用程式範例

對於生產應用程式，這裡有一個範例，說明你的應用程式可能想做些什麼，讓自己和使用者掌控下載的時間。 你可以查詢是否有新的執行服務提供者可用，並在註冊前有條件地下載：

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();
    }
}

另請參閱

  • 上次更新時間：