Criação de um addon WinML para o Electron

Este guia mostra-lhe como criar um addon nativo de C# que utilize Windows Machine Learning (WinML) na sua aplicação Electron. O WinML permite-lhe executar modelos de machine learning (formato ONNX) localmente em dispositivos Windows para tarefas como classificação de imagens, deteção de objetos e mais.

Pré-requisitos

Observação

O WinML funciona em qualquer dispositivo Windows 10 (1809+) ou Windows 11. Para melhor desempenho, recomendam-se dispositivos com GPUs ou NPUs, mas a API também funciona no CPU.

Passo 1: Criar um addon nativo de C#

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

Isto cria uma pasta winMlAddon/ com um projeto C# configurado com o Windows SDK e referências ao Windows App SDK.

Construa o addon:

npm run build-winMlAddon

Passo 2: Descarregar o modelo SqueezeNet

  1. Instalar a Galeria de Desenvolvimento de IA
  2. Vá para o exemplo Classify Image
  3. Descarregue o modelo SqueezeNet 1.1
  4. Copie o ficheiro .onnx para uma pasta models/ na raiz do seu projeto

Observação

O modelo também pode ser descarregado do ONNX Model Zoo GitHub repositório.

Passo 3: Adicionar os pacotes NuGet obrigatórios

Atualize Directory.packages.props na raiz do seu projeto:

<PackageVersion Include="Microsoft.ML.OnnxRuntime.Extensions" Version="0.14.0" />
<PackageVersion Include="System.Drawing.Common" Version="9.0.9" />

Atualize winMlAddon/winMlAddon.csproj para adicionar as referências dos pacotes:

<PackageReference Include="Microsoft.ML.OnnxRuntime.Extensions" />
<PackageReference Include="System.Drawing.Common" />

Passo 4: Adicionar o código de exemplo

A AI Dev Gallery fornece a implementação completa para classificação de imagens com o SqueezeNet. Podes encontrar o código adaptado na amostra electron-winml.

Copie a winMlAddon/ pasta do exemplo ou atualize winMlAddon/addon.cs manualmente com o código do exemplo.

Principais detalhes da implementação

Project root path: O addon exige que o código JavaScript passe pelo caminho raiz project para poder localizar o modelo ONNX e as dependências nativas.

Pré-carregamento de dependências nativas: O addon inclui um método para carregar as DLLs necessárias que funciona tanto para cenários de desenvolvimento como de produção.

Configuração do Electron Forge: Configure o seu empacotador para desempacotar ficheiros nativos:

module.exports = {
  packagerConfig: {
    asar: {
      unpack: "**/*.{dll,exe,node,onnx}"
    },
    ignore: [
      /^\/.winapp\//,
      "\\.msix$",
      /^\/winMlAddon\/(?!dist).+/
    ]
  },
};

Passo 5: Constrói o addon

npm run build-winMlAddon

Passo 6: Testar o addon

Abra src/index.js e carregue o adddon:

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

Adicionar uma função de teste:

const testWinML = async () => {
  try {
    let projectRoot = path.join(__dirname, '..');
    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!');

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

Prepare imagens de teste criando uma test-images/ pasta com imagens de exemplo, depois execute:

npm start

Passo 7: Atualizar a identidade de depuração

npx winapp node add-electron-debug-identity

Observação

Existe um bug conhecido no Windows com aplicações Electron com empacotamento esparso que pode causar falhas ou janelas em branco. Consulte o guia de configuração para a solução alternativa.

Passos seguintes

  • Last updated on