Erstellen eines WinML-Add-Ons

In diesem Handbuch erfahren Sie, wie Sie ein systemeigenes C#-Addon erstellen, das Windows Machine Learning (WinML) in Ihrer Electron-App verwendet. Mit WinML können Sie machine learning Modelle (ONNX-Format) lokal auf Windows-Geräten für Aufgaben wie Bildklassifizierung, Objekterkennung und vieles mehr ausführen.

Voraussetzungen

Bevor Sie diesen Leitfaden starten, stellen Sie sicher, dass Sie folgendes haben:

• Einrichtung der Entwicklungsumgebung abgeschlossen
• Windows 11 oder Windows 10 (Version 1809 oder höher)

Schritt 1: Erstellen eines nativen C#-Add-Ons

Erstellen wir nun ein systemeigenes Addon, das WinML-APIs verwendet. Wir verwenden eine C#-Vorlage, die node-api-dotnet nutzt, um JavaScript und C# zu überbrücken.

npx winapp node create-addon --template cs --name winMlAddon

Dadurch wird ein winMlAddon/ Ordner mit:

• addon.cs – Ihr C#-Code, der WinML-APIs aufruft
• winMlAddon.csproj – Project Datei mit Verweisen auf Windows SDK und Windows App SDK
• README.md - Dokumentation zur Verwendung des Add-Ons

Der Befehl fügt Ihrem Addon ein build-winMlAddon-Skript zum Erstellen des Addons und ein clean-winMlAddon-Skript zum Bereinigen von Build-Artefakten hinzu.

{
  "scripts": {
    "build-winMlAddon": "dotnet publish ./winMlAddon/winMlAddon.csproj -c Release",
    "clean-winMlAddon": "dotnet clean ./winMlAddon/winMlAddon.csproj"
  }
}

Die Vorlage enthält automatisch Verweise auf beide SDKs, sodass Sie sofort mit dem Aufrufen Windows APIs beginnen können!

Überprüfen wir, ob alles ordnungsgemäß eingerichtet ist, indem wir das Add-On erstellen:

# Build the C# addon
npm run build-winMlAddon

Schritt 2: Herunterladen des SqueezeNet-Modells und Abrufen von Beispielcode

Wir verwenden das Beispiel zum Klassifizieren von Bildern aus der AI Dev Gallery als Referenz. In diesem Beispiel wird das SqueezeNet 1.1-Modell für die Bildklassifizierung verwendet.

2.1. Herunterladen des Modells

1. Installieren des AI Dev Gallery
2. Navigieren Sie zum Beispiel "Klassifizieren von Bildern" .
3. Herunterladen des SqueezeNet 1.1-Modells (es unterstützt CPU, GPU und NPU)
4. Klicken Sie auf "Enthaltenden Ordner öffnen ", um die .onnx Datei zu suchen.

5. Kopieren Sie die Datei squeezenet1.1.onnx in einen models/ Ordner im Projektstammverzeichnis.

Schritt 3: Hinzufügen erforderlicher NuGet-Pakete

Bevor Sie den WinML-Code hinzufügen, müssen wir zusätzliche NuGet-Pakete hinzufügen, die für die Bildverarbeitung, ONNX-Runtime und GenAI-Unterstützung erforderlich sind.

3.1. Update Directory.packages.props

Fügen Sie die folgenden Paketversionen zur Directory.packages.props Datei im Stammverzeichnis Ihres Projekts hinzu (sollte erstellt worden sein, wenn Sie das Addon erstellt haben):

<Project>
  <PropertyGroup>
    <!-- Enable central package versioning -->
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Microsoft.JavaScript.NodeApi" Version="0.9.17" />
    <PackageVersion Include="Microsoft.JavaScript.NodeApi.Generator" Version="0.9.17" />
    <!-- Add these packages for WinML -->
+   <PackageVersion Include="Microsoft.ML.OnnxRuntime.Extensions" Version="0.14.0" />
+   <PackageVersion Include="System.Drawing.Common" Version="9.0.9" />
+   <PackageVersion Include="Microsoft.Extensions.AI" Version="9.9.1" />
+   <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI.Managed" Version="0.10.1" />
+   <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI.WinML" Version="0.10.1" />
    
    <!-- These versions may be updated automatically during restore to match yaml -->
    <PackageVersion Include="Microsoft.WindowsAppSDK" Version="2.0.0-experimental3" />
    <PackageVersion Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.26100.7175" />
  </ItemGroup>
</Project>

3.2. WinMlAddon.csproj aktualisieren

Öffnen Sie winMlAddon/winMlAddon.csproj und fügen Sie die Paketverweise zu <ItemGroup> hinzu.

<ItemGroup>
  <PackageReference Include="Microsoft.JavaScript.NodeApi" />
  <PackageReference Include="Microsoft.JavaScript.NodeApi.Generator" />
  <!-- Add these packages for WinML -->
+ <PackageReference Include="Microsoft.ML.OnnxRuntime.Extensions" />
+ <PackageReference Include="System.Drawing.Common" />
+ <PackageReference Include="Microsoft.Extensions.AI" />
+ <PackageReference Include="Microsoft.ML.OnnxRuntimeGenAI.Managed" />
+ <PackageReference Include="Microsoft.ML.OnnxRuntimeGenAI.WinML" />
  
  <PackageReference Include="Microsoft.Windows.SDK.BuildTools" />
  <PackageReference Include="Microsoft.WindowsAppSDK" />
</ItemGroup>

Was die folgenden Pakete tun:

• Microsoft.ML.OnnxRuntime.Extensions – Stellt zusätzliche Operatoren und Hilfsprogramme für DIE ONNX-Runtime bereit.
• System.Drawing.Common – Ermöglicht das Laden und Bearbeiten von Bildern für die Vorverarbeitung.
• Microsoft. Extensions.AI - KI-Abstraktionen für .NET
• Microsoft.ML.OnnxRuntimeGenAI.Managed – Verwaltete Bindungen für ONNX Runtime GenAI
• Microsoft.ML.OnnxRuntimeGenAI.WinML - WinML-Integration für ONNX Runtime GenAI

Schritt 4: Hinzufügen des Beispielcodes

Die AI Dev Gallery zeigt die vollständige Implementierung für die Bildklassifizierung mit SqueezeNet:

Wir haben diesen Code für Electron angepasst, und Sie finden die vollständige Implementierung im Elektronen-Winml-Beispiel. Der winMlAddon/ Ordner enthält den geänderten Code aus dem AI Dev Gallery.

Kopieren Sie den gesamten winMlAddon/ Ordner aus Samples/electron-winml/winMlAddon/ in Ihr Projektwurzelverzeichnis und ersetzen Sie den in Schritt 1 erstellten Ordner. Das Beispiel enthält mehrere Dateien darüber hinaus addon.cs (Hilfsklassen in Utils/, einen Chatclient usw.), die für das Addon zum Erstellen und Ausführen erforderlich sind.

Wichtige Implementierungsdetails

Lassen Sie uns die wichtigen Teile der Implementierung und der wichtigsten Unterschiede im AI Dev Gallery-Code hervorheben:

1. Project Stammpfadanforderung

Im Gegensatz zum AI Dev Gallery-Code erfordert unser Electron-Addon den JavaScript-Code, um den Projektstammpfad zu übergeben. Dies ist erforderlich, da:

• Das Addon muss die ONNX-Modelldatei im models/ Ordner suchen.
• Systemeigene Abhängigkeiten (DLLs) müssen aus bestimmten Verzeichnissen geladen werden

[JSExport]
public static async Task<Addon> CreateAsync(string projectRoot)
{
    if (!Path.Exists(projectRoot))
    {
        throw new Exception("Project root is invalid.");
    }

    var addon = new Addon(projectRoot);
    addon.PreloadNativeDependencies();

    string modelPath = Path.Join(projectRoot, "models", @"squeezenet1.1-7.onnx");
    await addon.InitModel(modelPath, ExecutionProviderDevicePolicy.DEFAULT, null, false, null);

    return addon;
}

Dadurch wird automatisch der beste Ausführungsanbieter (CPU, GPU oder NPU) basierend auf Gerätefunktionen ausgewählt.

2. Vorabladen nativer Abhängigkeiten

Das Addon enthält eine PreloadNativeDependencies() Methode zum Laden erforderlicher DLLs. Dieser Ansatz funktioniert sowohl für Entwicklungs- als auch für Produktionsszenarien , ohne DLLs in den Projektstamm kopieren zu müssen:

private void PreloadNativeDependencies()
{
    // Loads required DLLs from the winMlAddon build output
    // This ensures dependencies are available regardless of the execution context
}

Dies wird während der Initialisierung aufgerufen, bevor das Modell geladen wird, um sicherzustellen, dass alle systemeigenen Bibliotheken verfügbar sind.

3. Konfigurieren der Elektronenschmiede für Verpackungen

Um sicherzustellen, dass das Addon in Produktionsbuilds ordnungsgemäß funktioniert, müssen Sie den Packager für Folgendes konfigurieren:

1. Entpacken systemeigener Dateien – DLLs, ONNX-Modelle und NODE-Dateien müssen außerhalb des ASAR-Archivs zugänglich sein
2. Unnötige Dateien ausschließen – Halten Sie die Paketgröße klein, indem Sie Buildartefakte und temporäre Dateien ausschließen

Für Electron Forge aktualisieren Sie Ihre forge.config.js:

// From samples/electron-winml/forge.config.js
module.exports = {
  packagerConfig: {
    asar: {
      // Unpack native files so they can be accessed by the addon
      unpack: "**/*.{dll,exe,node,onnx}"
    },
    ignore: [
      // Exclude .winapp folder (SDK packages and headers)
      /^\/.winapp\//,
      // Exclude MSIX packages
      "\\.msix$",
      // Exclude winMlAddon source files, but keep the dist folder
      /^\/winMlAddon\/(?!dist).+/
    ]
  },
  // ... rest of your config
};

Was dies bewirkt:

1. asar.unpack - Extrahiert DLLs, ausführbare Dateien, Node-Binärdateien und ONNX-Modelle in app.asar.unpacked/

   • Dadurch können sie zur Laufzeit über Dateisystempfade zugänglich sein.
   • Der JavaScript-Code passt Pfade automatisch an (siehe app.asar → app.asar.unpacked Ersetzung oben)

2. ignore - Schließt aus dem endgültigen Paket aus:

   • .winapp/ - SDK-Pakete und Header (zur Laufzeit nicht erforderlich)
   • .msix Dateien – Paketierte Ausgaben
   • winMlAddon/ Quelldateien – Behält nur den dist/ Ordner mit kompilierten Binärdateien bei

4. Bildklassifizierung

Die ClassifyImage Methode verarbeitet ein Bild und gibt Vorhersagen zurück:

[JSExport]
public async Task<Prediction[]> ClassifyImage(string imagePath)
{
    // Loads the image, preprocesses it, and runs inference
    // Returns top predictions with labels and confidence scores
}

Die vollständige Implementierung behandelt:

• Laden und Vorverarbeitung von Bildern (Größenänderung, Normalisierung)
• Ausführen der Modellinferenz
• Ergebnisse nach der Verarbeitung, um Topvorhersagen mit Bezeichnungen und Konfidenzergebnissen zu erhalten

Grundlegendes zum Code

Das Addon bietet die folgenden Hauptfunktionen:

1. CreateAsync – Initialisiert das Addon und lädt das SqueezeNet-Modell.
2. ClassificationImage – Übernimmt einen Bildpfad und gibt Klassifizierungsvorhersagen zurück.

WinML wählt automatisch das beste Ausführungsgerät (CPU, GPU oder NPU) basierend auf der Verfügbarkeit aus.

Schritt 5: Erstellen des C#-Add-Ons

Erstellen Sie nun das Addon:

npm run build-winMlAddon

Dadurch wird Ihr C#-Code mithilfe der nativen AOT (Ahead-of-Time-Kompilierung) kompiliert, die:

• Erstellt eine .node Binärdatei (systemeigenes Addon-Format)
• Kürzen von nicht verwendetem Code für eine kleinere Paketgröße
• Erfordert keine .NET-Laufzeitumgebung auf Zielcomputern
• Bietet systemeigene Leistung

Das kompilierte Addon wird in winMlAddon/dist/winMlAddon.node sein.

Schritt 6: Testen des Add-Ons

Jetzt testen wir das Addon, indem wir es aus dem Hauptprozess aufrufen. Öffnen Sie src/main.js und führen Sie dann die folgenden Schritte aus:

6.1. Laden des Add-Ons

Fügen Sie oben die erforderlichen Anweisungen hinzu.

const winMlAddon = require('../winMlAddon/dist/winMlAddon.node');

6.2. Erstellen einer Testfunktion

Fügen Sie diese Funktion zum Testen der Bildklassifizierung hinzu:

const testWinML = async () => {
  console.log('Testing WinML addon...');
  
  try {
    let projectRoot = path.join(__dirname, '..');
    // Adjust path for packaged apps
    if (projectRoot.includes('app.asar')) {
      projectRoot = projectRoot.replace('app.asar', 'app.asar.unpacked');
    }
    
    const addon = await winMlAddon.Addon.createAsync(projectRoot);
    console.log('Model loaded successfully!');
    
    // Classify a sample image
    const imagePath = path.join(projectRoot, 'test-images', 'sample.jpg');
    const predictions = await addon.classifyImage(imagePath);
    
    console.log('Top predictions:');
    predictions.slice(0, 5).forEach((pred, i) => {
      console.log(`${i + 1}. ${pred.label}: ${(pred.confidence * 100).toFixed(2)}%`);
    });
  } catch (error) {
    console.error('Error testing WinML:', error.message);
  }
};

Wichtige Punkte:

• Die Pfadanpassung (app.asar → app.asar.unpacked) stellt sicher, dass der Code sowohl in der Entwicklung als auch in verpackten Apps funktioniert.
• Dadurch wird auf die entpackten nativen Dateien zugegriffen, die in forge.config.js konfiguriert sind.

6.3. Aufrufen der Testfunktion

Fügen Sie diese Zeile am Ende der createWindow() Funktion hinzu:

testWinML();

6.4. Vorbereiten von Testbildern

So testen Sie die Bildklassifizierung:

1. Erstellen eines test-images/ Ordners im Projektstamm
2. Hinzufügen eines Testbilds mit dem Namen sample.jpg (der Code erwartet diesen genauen Dateinamen)
3. Das SqueezeNet-Modell erkennt 1000 verschiedene ImageNet-Klassen (Tiere, Objekte, Szenen usw.)

Wenn Sie die App ausführen, werden die Klassifizierungsergebnisse in der Konsole angezeigt!

Schritt 7: Aktualisieren der Debugidentität

Um sicherzustellen, dass die Windows App SDK geladen und für die Verwendung verfügbar ist, müssen wir sicherstellen, dass die Debugidentität eingerichtet wird, die sicherstellt, dass das Framework bei jeder Ausführung unserer App geladen wird. Ebenso müssen Sie bei jeder Änderung Package.appxmanifest oder Änderung von Ressourcen, auf die im Manifest verwiesen wird (z. B. App-Symbole), die Debugidentität Ihrer App aktualisieren. Laufen:

npx winapp node add-electron-debug-identity

Dieser Befehl:

1. Liest Ihre Package.appxmanifest, um Details und Funktionen der App abzurufen.
2. Registriert electron.exe in Ihrem node_modules mit einer temporären Identität.
3. Ermöglicht es Ihnen, identitätsrelevante APIs ohne vollständige MSIX-Verpackung zu testen.

Führen Sie nun Ihre App aus:

npm start

Überprüfen Sie die Konsolenausgabe – die WinML-Testergebnisse sollten angezeigt werden!

Nächste Schritte

Herzlichen Glückwunsch! Sie haben erfolgreich ein systemeigenes Addon erstellt, das Machine Learning-Modelle mit WinML ausführen kann! 🎉

Jetzt sind Sie bereit für:

• Verpacken Ihrer App für Verteilung – Erstellen Eines MSIX-Pakets, das Sie verteilen können

Oder erkunden Sie andere Guides:

• Erstellen eines Phi-Silica-Addon - Erfahren Sie, wie Sie die Phi-Silica-KI-API verwenden
• Übersicht über erste Schritte – Zurück zum Hauptleitfaden

Anpassen für Ihr Modell

Um Ihr ONNX-Modell vollständig zu integrieren, müssen Sie:

1. Verstehen der Eingaben Ihres Modells – Bilder, Tensoren, Sequenzen usw.
2. Erstellen richtiger Eingabebindungen – Konvertieren Ihrer Daten in das erwartete WinML-Format
3. Verarbeiten der Ausgaben – Analysieren und Interpretieren der Vorhersagen des Modells
4. Fehler ordnungsgemäß behandeln – Modelllade- und Rückschlussfehler können fehlschlagen

Zusätzliche Ressourcen

• WinML-Dokumentation - Offizielle WinML-Dokumentation
• winapp CLI-Dokumentation - Vollständige CLI-Referenz
• Sample Electron App – Vollständiges Arbeitsbeispiel
• AI Dev Gallery – Beispielkatalog aller KI-APIs
• Windows App SDK Samples - Sammlung von Windows App SDK Beispielen
• node-api-dotnet – C# ↔ JavaScript-Interoperabilitätsbibliothek

Problembehandlung

node -e "console.log(process.arch)"

# For x64 Node.js:
dotnet publish ./winMlAddon/winMlAddon.csproj -c Release -r win-x64

# For ARM64 Node.js:
dotnet publish ./winMlAddon/winMlAddon.csproj -c Release -r win-arm64

rm -rf node_modules package-lock.json
npm install

Hilfe

• Ein Fehler gefunden?Ein Problem melden
• WinML-Fragen? Lesen Sie die WinML-Dokumentation

Glückliches maschinelles Lernen! 🤖