Windows ML API群

概念的なガイダンスについては、「 Windows ML を使用した ONNX モデルの実行」を参照してください。

Microsoft.Windows.AI.MachineLearning NuGet パッケージの API は、次の 3 つのセットのスーパーセットと考えることができます。

• 新しい API。 インフラストラクチャ クラスとそのメソッド (Windows ランタイム API) などの新しい Windows ML API。WinMLInitialize 関数 (フラットな C スタイルの Win32 API であり、Windows ML ブートストラップ API の 1 つです) など。 これらの API は、今読んでいるトピックに記載されています。
• 以前のバージョンの Windows ML の API。 Windows.AI.MachineLearning 名前空間からコピーされた Windows ML API。 そのため、現時点では、これらの API については、Windows.AI.MachineLearning のドキュメントの Microsoft.Windows.AI.MachineLearning にも存在することを理解して学習できます。 Windows.AI.MachineLearning の Windows ML API を参照してください。
• ONNX ランタイム API。 ONNX Runtime (ORT) からの特定の API の Windows ML 実装 ( Microsoft.Windows.AI.MachineLearning NuGet パッケージ内)。 ドキュメントについては、 ONNX Runtime API のドキュメントを参照してください。たとえば、 OrtCompileApi 構造体です。 これらの API を使用するコード例、およびドキュメントへのその他のリンクについては、「 Windows ML を使用して ResNet-50 モデルを実行する 」チュートリアルを参照してください。

Microsoft.Windows.AI.MachineLearning NuGet パッケージ

Microsoft Windows ML ランタイムには、Windows アプリケーションでの機械学習と AI 操作用の API が用意されています。 Microsoft.Windows.AI.MachineLearning NuGet パッケージは、C# プロジェクトと C++ プロジェクトの両方で使用できる Windows ML ランタイム .winmd ファイルを提供します。

新しい Windows ランタイム API

インフラストラクチャ クラス

Infrastructure クラスには、ONNX ランタイムで使用する AI 実行プロバイダー (IP) をダウンロード、構成、登録するメソッドが用意されています。 インフラストラクチャ は、パッケージ管理とハードウェアの選択の複雑さを処理します。

このクラスは、アプリが Windows ML ランタイムを介してハードウェア最適化機械学習アクセラレーションにアクセスするためのエントリ ポイントです。

C#

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

// Download the latest execution provider packages
await infrastructure.DownloadPackagesAsync();

// Register available execution providers with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

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

C++/WinRT

winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

// Download packages
infrastructure.DownloadPackagesAsync().get();

// Register execution providers with ONNX Runtime
infrastructure.RegisterExecutionProviderLibrariesAsync().get();

// Use ONNX Runtime C API directly for inference

インフラストラクチャ クラスメソッド

Infrastructure.DownloadPackagesAsync メソッド

現在のハードウェア構成のパッケージ依存関係をダウンロードします。 これにより、デバイスのハードウェアに適した実行プロバイダーがインストールされ、up-to更新されます。

C#

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

try {
    // This will download the appropriate packages for the current hardware
    await infrastructure.DownloadPackagesAsync();
    Console.WriteLine("Execution provider packages downloaded successfully");
}
catch (Exception ex) {
    Console.WriteLine($"Failed to download execution provider packages: {ex.Message}");
}

C++/WinRT

try {
    winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;
    
    // Download the packages
    infrastructure.DownloadPackagesAsync().get();
    std::wcout << L"Execution provider packages downloaded successfully\n";
}
catch (const winrt::hresult_error& ex) {
    std::wcout << L"Error: " << ex.message().c_str() << L"\n";
}

Infrastructure.RegisterExecutionProviderLibrariesAsync メソッド

現在のハードウェア構成に関連するすべての実行プロバイダー ライブラリを ONNX ランタイムに登録します。 ONNX ランタイム セッションを作成する前に、このメソッドを呼び出す必要があります。

Von Bedeutung

RegisterExecutionProviderLibrariesAsync の呼び出しの後に ONNX ランタイムを使用する場合、インフラストラクチャ インスタンスは有効なままである必要があります。

C#

var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

// Register execution providers with ONNX Runtime
await infrastructure.RegisterExecutionProviderLibrariesAsync();

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

C++/WinRT

winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

// Register execution providers with ONNX Runtime
infrastructure.RegisterExecutionProviderLibrariesAsync().get();

// Use ONNX Runtime C API directly for inference

Infrastructure.GetExecutionProviderLibraryPathsAsync メソッド

実行プロバイダー名とその完全なファイルパスのマップを取得します。 これにより、アプリケーションは、使用可能な実行プロバイダーとその場所に関する情報を取得できます。

C#

// C# example
var infrastructure = new Microsoft.Windows.AI.MachineLearning.Infrastructure();

try {
    // Get the map of execution provider names to paths
    var providerPaths = await infrastructure.GetExecutionProviderLibraryPathsAsync();

    foreach (var provider in providerPaths) {
        Console.WriteLine($"Provider: {provider.Key}, Path: {provider.Value}");
    }
}
catch (Exception ex) {
    Console.WriteLine($"Failed to get execution provider paths: {ex.Message}");
}

C++/WinRT

try {
    winrt::Microsoft::Windows::AI::MachineLearning::Infrastructure infrastructure;

    // Get the execution provider paths
    auto providerPaths = infrastructure.GetExecutionProviderLibraryPathsAsync().get();

    for (const auto& pair : providerPaths) {
        std::wcout << L"Provider: " << pair.Key().c_str() << L", Path: " << pair.Value().c_str() << L"\n";
    }
}
catch (const winrt::hresult_error& ex) {
    std::wcout << L"Error: " << ex.message().c_str() << L"\n";
}

その他のインフラストラクチャ メンバー

名前	説明
インフラストラクチャ	Infrastructure クラスのインスタンスを初期化する既定のコンストラクター

API の詳細

namespace Microsoft.Windows.AI.MachineLearning
{
    [contract(Windows.Foundation.UniversalApiContract, 1)]
    [threading(both)]
    [marshaling_behavior(agile)]
    runtimeclass Infrastructure
    {
        // Constructor
        Infrastructure();

        // Downloads package dependencies for the current hardware.
        Windows.Foundation.IAsyncAction DownloadPackagesAsync();

        // Registers all execution provider libraries with ONNX Runtime.
        Windows.Foundation.IAsyncAction RegisterExecutionProviderLibrariesAsync();
    }
}

実装に関するメモ

Infrastructure クラスは、Microsoft Store InstallControl API を使用してパッケージ管理を内部的に処理します。これは、Microsoft が署名しているため、メインの Windows ML ランタイム パッケージから呼び出す必要があります。 これには次のものが含まれます。

• 現在のハードウェア構成で使用可能な実行プロバイダー (IP) の解決。
• パッケージの有効期間と更新プログラムの管理。
• パッケージの登録とアクティブ化の処理。
• さまざまなバージョンの実行プロバイダーのサポート

パッケージの検出

実行プロバイダー (EP) は、パッケージ マニフェストで com.microsoft.windowsmlruntime.executionprovider 拡張機能を宣言する個別の MSIX コンポーネントとしてパッケージ化されます。 この設計により、実行プロバイダーを Windows ML ランタイム コンポーネントとは別に更新できます。

Windows ML ランタイムは、Windows 11 で導入されたパッケージ拡張機能インフラストラクチャを介してこれらのパッケージを検出します。 検出された EP ごとに、ランタイムはハードウェアの互換性を評価し、現在のシステムに適した実装を読み込みます。

Windows ML ランタイムでの ONNX ランタイムの使用

C++ アプリケーションの場合、 RegisterExecutionProviderLibrariesAsyncを呼び出した後、ONNX Runtime C API を直接使用してセッションを作成し、推論を実行します。

C# アプリケーションの場合は、 Microsoft.ML.OnnxRuntime 名前空間を使用した推論に ONNX ランタイムを直接使用します。

新規のフラットなCスタイルのWin32 API（Windows MLブートストラップAPI）

以下の要件は、以下に記載されているすべての Windows ML ブートストラップ関数に適用されます。

要件	価値
NuGet パッケージ	Microsoft.Windows.AI.MachineLearning
ヘッダー	WinMLBootstrap.h
名前空間	なし

WinMLStatusCallback コールバック関数

typedef void (*WinMLStatusCallback)(void* context, HRESULT result);

WinMLInitialize 関数

/**
 * Initializes the WinML runtime, and adds dependencies to the current process.
 * You must call this function before you call any other WinML APIs.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 */
HRESULT WinMLInitialize(void);

WinMLUninitialize 関数

/**
 * Uninitializes the WinML runtime, and removes any dependencies in the current process.
 * You must call this function before before the process exits.
 *
 * @return No return value.
 */
void WinMLUninitialize(void);

WinMLGetInitializationStatus 関数

/**
 * Returns the initialization status of the WinML runtime.
 * S_OK indicates that the runtime is initialized and ready to use.
 *
 * @return HRESULT S_OK if the runtime is initialized; an error code otherwise.
 */
HRESULT WinMLGetInitializationStatus(void);

WinMLDownloadExecutionProviders 関数

/**
 * Downloads the execution providers applicable to the current device.
 * This function is asynchronous, and will return immediately.
 * A status result will be returned to the callback when the download is complete or has failed.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 */
HRESULT WinMLDownloadExecutionProviders(
    WinMLStatusCallback onCompletedCallback,
    void* context);

WinMLRegisterExecutionProviders 関数

/**
 * Registers the execution providers applicable to the current device.
 * This function is asynchronous, and will return immediately.
 * A status result will be returned to the callback when the registration is complete or has failed.
 *
 * @return HRESULT S_OK on success, an error code otherwise.
 */
HRESULT WinMLRegisterExecutionProviders(
    WinMLStatusCallback onCompletedCallback,
    void* context);

WinMLDeployMainPackage 関数

/**
 * Deploys the Microsoft.Windows.AI.MachineLearning MSIX package from the
 * msix/win-{arch} directory relative to the application executable.
 *
 * @return HRESULT S_OK on success; an error code otherwise.
 * S_OK is also returned if the package is already installed.
 */
HRESULT WinMLDeployMainPackage();

こちらも参照ください

• Windows ML を使用して ONNX モデルを実行する (Microsoft.Windows.AI.MachineLearning)