Implantar seu modelo de ML.NET em um aplicativo do Windows com as APIs do Windows Machine Learning

Na parte anterior deste tutorial, você aprendeu a criar e exportar um modelo de ML.NET no formato ONNX. Agora que você tem esse modelo, pode inserê-lo em um aplicativo do Windows e executá-lo localmente em um dispositivo chamando APIs WinML.

Quando terminarmos, você terá um aplicativo UWP (WinML) classificador de imagem funcional.

Dica

Este artigo aborda o caminho da classificação de imagens com ML.NET. Se o modelo ONNX for proveniente de outro caminho de tutorial do Windows ML, consulte Implantar seu modelo de Visão Personalizada em um aplicativo Windows ou implantar seu modelo PyTorch em um aplicativo Windows.

Sobre o aplicativo de exemplo

Usando nosso modelo, criaremos um aplicativo que pode classificar imagens de alimentos. Ele permite que você selecione uma imagem do seu dispositivo local e processe-a por um modelo ONNX de classificação armazenado localmente criado e treinado na parte anterior. As marcas retornadas são exibidas ao lado da imagem, bem como a probabilidade de confiança da classificação.

Se você estiver seguindo este tutorial até agora, já deverá ter os pré-requisitos necessários para o desenvolvimento de aplicativos preparados. Se você precisar de um atualizador, consulte a primeira parte deste tutorial.

Observação

Se você preferir baixar o código de exemplo completo, poderá clonar o arquivo de solução. Clone o repositório, navegue até este exemplo e abra o arquivo classifierMLNETModel.sln com o Visual Studio. Em seguida, você pode pular para a etapa [Iniciar o aplicativo](#Iniciar-o-aplicativo).

Crie um aplicativo UWP com WinML (C#)

Abaixo, mostraremos como criar seu aplicativo e código WinML do zero. Você aprenderá a:

  • Carregar um modelo de machine learning.
  • Carregue uma imagem no formato necessário.
  • Associe as entradas e saídas do modelo.
  • Avaliar o modelo e exibir os resultados significativos.

Você também usará XAML básico para criar uma GUI simples, para que você possa testar o classificador de imagem.

Criar o aplicativo

  1. Abra o Visual Studio e escolha create a new project.

Criar um novo projeto do Visual Studio

  1. Na barra de pesquisa, digite UWP e selecione Blank APP (Universal Windows). Isso abre um novo projeto em C# para um aplicativo UWP (Plataforma Universal do Windows) de página única que não tem controles ou layout predefinidos. Selecione Next para abrir uma janela de configuração para o projeto.

Criar um aplicativo UWP

  1. Na janela de configuração:
  • Escolha um nome para seu projeto. Aqui, usamos classifierMLNETModel.
  • Escolha o local do projeto.
  • Se você estiver usando o VS 2019, certifique-se de que Place solution and project in the same directory está desmarcado.
  • Se você estiver usando o VS 2017, certifique-se de que Create directory for solution está marcado.

Configurar seu aplicativo

Pressione create para criar o projeto. A janela de versão de destino mínima pode aparecer. Verifique se sua versão mínima está definida como o Windows 10 build 17763 ou posterior.

Para criar um aplicativo e implantar um modelo com um aplicativo WinML, você precisará do seguinte:

  1. Depois que o projeto foi criado, navegue até a pasta do projeto, abra a pasta de ativos [....\classifierMLNETModel\Assets] e copie o bestModel.onnx arquivo para esse local.

Explorar a solução do projeto

Vamos explorar sua solução de projeto.

O Visual Studio criou automaticamente vários arquivos cs-code dentro do Gerenciador de Soluções. MainPage.xaml contém o código XAML para sua GUI e MainPage.xaml.cs contém o código do aplicativo. Se você já criou um aplicativo UWP, esses arquivos devem ser muito familiares.

Criar a GUI do aplicativo

Primeiro, vamos criar uma GUI simples para o aplicativo.

  1. Clique duas vezes no MainPage.xaml arquivo. No aplicativo em branco, o modelo XAML da GUI do aplicativo está vazio, de modo que precisaremos adicionar alguns recursos da interface do usuário.

  2. Substitua o código de MainPage.xaml pelo seguinte.

<Page
    x:Class="classifierMLNETModel.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:classifierMLNETModel"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

       <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

	
        <StackPanel Margin="1,0,-1,0">
            <TextBlock x:Name="Menu" 
                       FontWeight="Bold" 
                       TextWrapping="Wrap"
                       Margin="10,0,0,0"
                       Text="Image Classification"/>
            <TextBlock Name="space" />
            <Button Name="recognizeButton"
                    Content="Pick Image"
                    Click="OpenFileButton_Click" 
                    Width="110"
                    Height="40"
                    IsEnabled="True" 
                    HorizontalAlignment="Left"/>
            <TextBlock Name="space3" />
            <Button Name="Output"
                    Content="Result is:"
                    Width="110"
                    Height="40"
                    IsEnabled="True" 
                    HorizontalAlignment="Left" 
                    VerticalAlignment="Top">
            </Button>
            <!--Dispaly the Result-->
            <TextBlock Name="displayOutput" 
                       FontWeight="Bold" 
                       TextWrapping="Wrap"
                       Margin="25,0,0,0"
                       Text="" Width="1471" />
            <TextBlock Name="space2" />
            <!--Image preview -->
            <Image Name="UIPreviewImage" Stretch="Uniform" MaxWidth="300" MaxHeight="300"/>
        </StackPanel>
    </Grid> 
</Page>

Adicionar o modelo ao projeto usando o Gerador de Código do Windows Machine Learning

O Gerador de Código do Windows Machine Learning, ou mlgen, é uma extensão do Visual Studio para ajudá-lo a começar a usar APIs WinML em aplicativos UWP. Ele gera código de template quando você adiciona um arquivo ONNX treinado ao projeto UWP.

O gerador de código do Windows Machine Learning, mlgen, cria uma interface (para C#, C++/WinRT e C++/CX) com classes wrapper que chamam a API do Windows ML para você. Assim, você pode carregar, associar e avaliar facilmente um modelo em seu projeto. Vamos usá-lo neste tutorial para lidar com muitas dessas funções para nós.

O gerador de código está disponível para o Visual Studio 2017 e versões posteriores. Observe que, no Windows 10 versão 1903 e posterior, o mlgen não está mais incluído no SDK do Windows 10, de modo que você precisa baixar e instalar a extensão. Se você estiver acompanhando este tutorial a partir da introdução, já terá lidado com isso, mas caso contrário, deverá baixar para o VS 2019 ou para o VS 2017.

Observação

Para saber mais sobre mlgen, confira a documentação do mlgen

  1. Caso ainda não tenha feito isso, instale o mlgen.

  2. Clique com o botão direito do mouse na pasta Assets no Gerenciador de Soluções no Visual Studio e selecione Add > Existing Item.

  3. Navegue até a pasta de ativos dentro de ImageClassifierAppUWP [….\ImageClassifierAppUWP\Assets], localize o modelo ONNX que você copiou nela e selecione add.

  4. Depois de adicionar um modelo ONNX (nome: "classificador") à pasta de ativos no gerenciador de soluções no VS, o projeto agora deve ter dois novos arquivos:

  • bestModel.onnx – este é o seu modelo no formato ONNX.
  • bestModel.cs – arquivo de código WinML gerado automaticamente.

Estrutura do projeto com o modelo ONNX adicionado

  1. Para garantir que o modelo seja compilado quando você compilar o aplicativo, selecione o arquivo bestModel.onnx e escolha Properties. Para Build Action, selecione Content.

Agora, vamos explorar o código recém-gerado no bestModel.cs arquivo.

O código gerado inclui três classes:

  • bestModelModel: essa classe inclui dois métodos para instanciação de modelo e avaliação de modelo. Ele nos ajudará a criar a representação do modelo de machine learning, criar uma sessão no dispositivo padrão do sistema, associar as entradas e saídas específicas ao modelo e avaliar o modelo de maneira assíncrona.
  • bestModelInput: essa classe inicializa os tipos de entrada que o modelo espera. A entrada de modelo depende dos requisitos de modelo para dados de entrada.
  • bestModelOutput: essa classe inicializa os tipos que o modelo terá como saída. A saída do modelo depende de como ela é definida pelo modelo.

Agora você usará essas classes para carregar, associar e avaliar o modelo em nosso projeto.

Conversão do tensor

Para facilitar o tratamento da tensorização, altere a classe de entrada TensorFloat para ImageFeatureValue.

  1. Faça as seguintes alterações no arquivo bestModel.cs:

O código:

public sealed class bestModelInput
    {
        public TensorFloat input; // shape(-1,3,32,32)
    }

Será:

public sealed class bestModelInput
    {
        public ImageFeatureValue input; // shape(-1,3,32,32)
    }

Carregar o modelo e as entradas

Carregar o modelo

  1. Clique duas vezes no MainPage.xaml.cs arquivo de código para abrir o código do aplicativo.

  2. Substitua as instruções "using" pelo indicado a seguir para ter acesso a todas as APIs que serão necessárias.

// Specify all the using statements which give us the access to all the APIs that you'll need
using System;
using System.Threading.Tasks;
using Windows.AI.MachineLearning;
using Windows.Graphics.Imaging;
using Windows.Media;
using Windows.Storage;
using Windows.Storage.Pickers;
using Windows.Storage.Streams;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Media.Imaging;
  1. Adicione as declarações de variável a seguir após as instruções using dentro da classe MainPage no namespace classifierMLNETModel.
		// All the required fields declaration
		private bestModelModel modelGen;
		private bestModelInput image = new bestModelInput();
		private bestModelOutput results;
		private StorageFile selectedStorageFile;
		private string label = "";
		private float probability = 0;
		private Helper helper = new Helper();

		public enum Labels
		{
			desert,
			soup,
			vegetable_fruit,
		}

Agora, você vai implementar o método LoadModel. O método acessará o modelo ONNX e o armazenará na memória. Em seguida, você usará o método CreateFromStreamAsync para criar uma instância do modelo como um objeto LearningModel. A classe LearningModel representa um modelo de machine learning treinado. Uma vez instanciado, o LearningModel é o objeto inicial usado para interagir com o Windows ML.

Para carregar o modelo, você pode usar vários métodos estáticos na classe LearningModel. Nesse caso, você usará o método CreateFromStreamAsync.

O método CreateFromStreamAsync foi criado automaticamente com mlgen, portanto, você não precisa implementá-lo. Você pode examiná-lo clicando duas vezes no arquivo bestModel.cs gerado por mlgen.

Para saber mais sobre a classe LearningModel, examine a documentação da classe LearningModel.

Para saber mais sobre maneiras adicionais de carregar o modelo, examine a documentação Carregar um modelo

  1. Vamos definir o método principal.
// The main page to initialize and execute the model.
public MainPage()
{
	this.InitializeComponent();
	loadModel();
}
  1. Adicione a implementação do loadModel método ao MainPage.xaml.cs arquivo de código dentro da MainPage classe.
private async Task loadModel()
{
// Get an access the ONNX model and save it in memory. 
	StorageFile modelFile = await StorageFile.GetFileFromApplicationUriAsync(new Uri($"ms-appx:///Assets/bestModel.onnx"));
// Instantiate the model. 
	modelGen = await bestModelModel.CreateFromStreamAsync(modelFile);
}

Carregar a imagem

  1. Precisamos definir um evento de clique para iniciar a sequência de quatro chamadas de método para execução do modelo: conversão, associação e avaliação, extração de saída e exibição de resultados. Adicione o seguinte método ao seu arquivo de código MainPage.xaml.cs dentro da classe MainPage.
        // Waiting for a click event to select a file 
        private async void OpenFileButton_Click(object sender, RoutedEventArgs e)
        {
            if (!await getImage())
            {
                return;
            }
            // After the click event happened and an input selected, begin the model execution. 
            // Bind the model input
            await imageBind();
            // Model evaluation
            await evaluate();
            // Extract the results
            extractResult();
            // Display the results  
            await displayResult();
        }
  1. Agora, você vai implementar o método getImage(). Esse método vai selecionar um arquivo de imagem de entrada e salvá-lo na memória. Adicione o método a seguir ao seu arquivo de código MainPage.xaml.cs dentro da classe MainPage.
        // A method to select an input image file
        private async Task<bool> getImage()
        {
            try
            {
                // Trigger file picker to select an image file
                FileOpenPicker fileOpenPicker = new FileOpenPicker();
                fileOpenPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
                fileOpenPicker.FileTypeFilter.Add(".jpg");
                fileOpenPicker.FileTypeFilter.Add(".png");
                fileOpenPicker.ViewMode = PickerViewMode.Thumbnail;
                selectedStorageFile = await fileOpenPicker.PickSingleFileAsync();
                if (selectedStorageFile == null)
                {
                    return false;
                }
            }
            catch (Exception)
            {
                return false;
            }
            return true;
        }

Em seguida, você implementará um método Bind() de imagem para obter a representação do arquivo no formato BGRA8 de bitmap. Porém, primeiro vai criar uma classe auxiliar para redimensionar a imagem.

  1. Para criar um arquivo auxiliar, clique com o botão direito do mouse no nome da solução (ClassifierPyTorch) e escolha Add a new item. Na janela aberta, selecione Class e dê um nome a ela. Aqui, nós a chamamos de Helper.

Adicionar um arquivo auxiliar

  1. Um novo arquivo de classe aparecerá dentro do seu projeto. Abra essa classe e adicione o seguinte código:
using System; 
using System.Threading.Tasks; 
using Windows.Graphics.Imaging; 
using Windows.Media; 

namespace classifierPyTorch 
{ 
    public class Helper 
    { 
        private const int SIZE = 32;  
        VideoFrame cropped_vf = null; 
 
        public async Task<VideoFrame> CropAndDisplayInputImageAsync(VideoFrame inputVideoFrame) 
        { 
            bool useDX = inputVideoFrame.SoftwareBitmap == null; 

            BitmapBounds cropBounds = new BitmapBounds(); 
            uint h = SIZE; 
            uint w = SIZE; 
            var frameHeight = useDX ? inputVideoFrame.Direct3DSurface.Description.Height : inputVideoFrame.SoftwareBitmap.PixelHeight; 
            var frameWidth = useDX ? inputVideoFrame.Direct3DSurface.Description.Width : inputVideoFrame.SoftwareBitmap.PixelWidth; 
 
            var requiredAR = ((float)SIZE / SIZE); 
            w = Math.Min((uint)(requiredAR * frameHeight), (uint)frameWidth); 
            h = Math.Min((uint)(frameWidth / requiredAR), (uint)frameHeight); 
            cropBounds.X = (uint)((frameWidth - w) / 2); 
            cropBounds.Y = 0; 
            cropBounds.Width = w; 
            cropBounds.Height = h; 
 
            cropped_vf = new VideoFrame(BitmapPixelFormat.Bgra8, SIZE, SIZE, BitmapAlphaMode.Ignore); 
 
            await inputVideoFrame.CopyToAsync(cropped_vf, cropBounds, null); 
            return cropped_vf; 
        } 
    } 
} 

Agora, vamos converter a imagem no formato apropriado.

A classe bestModelInput inicializa os tipos de entrada que o modelo espera. Em nosso caso, configuramos o código para esperar um ImageFeatureValue.

A classe ImageFeatureValue descreve as propriedades da imagem usada para ser passada a um modelo. Para criar umImageFeatureValue, você usa o método CreateFromVideoFrame. Para obter detalhes mais específicos sobre por que esse é o caso e como essas classes e métodos funcionam, consulte a documentação da classe ImageFeatureValue.

Observação

Neste tutorial, usamos a classe ImageFeatureValue em vez de um tensor. Se o Windows ML não oferecer suporte ao formato de cor do modelo, essa não será uma opção. Para obter um exemplo de como trabalhar com conversões de imagem e tensorização, consulte o Exemplo de Tensorização Personalizada.

  1. Adicione a implementação do método convert() ao seu arquivo de código MainPage.xaml.cs dentro da classe MainPage. O método convert nos fornecerá uma representação do arquivo de entrada em um formato BGRA8.
// A method to convert and bind the input image.  
        private async Task imageBind()
        {
            UIPreviewImage.Source = null;
            try
            {
                SoftwareBitmap softwareBitmap;
                using (IRandomAccessStream stream = await selectedStorageFile.OpenAsync(FileAccessMode.Read))
                {
                    // Create the decoder from the stream 
                    BitmapDecoder decoder = await BitmapDecoder.CreateAsync(stream);
                    // Get the SoftwareBitmap representation of the file in BGRA8 format
                    softwareBitmap = await decoder.GetSoftwareBitmapAsync();
                    softwareBitmap = SoftwareBitmap.Convert(softwareBitmap, BitmapPixelFormat.Bgra8, BitmapAlphaMode.Premultiplied);
                }
                // Display the image
                SoftwareBitmapSource imageSource = new SoftwareBitmapSource();
                await imageSource.SetBitmapAsync(softwareBitmap);
                UIPreviewImage.Source = imageSource;

				// Encapsulate the image within a VideoFrame to be bound and evaluated
            	VideoFrame inputImage = VideoFrame.CreateWithSoftwareBitmap(softwareBitmap);
              	// Resize the image size to 224x224 
              	inputImage=await helper.CropAndDisplayInputImageAsync(inputImage);
              	// Bind the model input with image
              	ImageFeatureValue imageTensor = ImageFeatureValue.CreateFromVideoFrame(inputImage);
				image.input1 = imageTensor;

				// Encapsulate the image within a VideoFrame to be bound and evaluated
				VideoFrame inputImage = VideoFrame.CreateWithSoftwareBitmap(softwareBitmap);
				// Bind the input image
				ImageFeatureValue imageTensor = ImageFeatureValue.CreateFromVideoFrame(inputImage);
				image.modelInput = imageTensor;

            }
            catch (Exception e)
            {
            }
        }

Associar e avaliar o modelo

A seguir, você criará uma sessão com base no modelo, associará a entrada e a saída da sessão e avaliará o modelo.

Criar uma sessão para associar o modelo:

Para criar uma sessão, use a classe LearningModelSession. Essa classe é usada para avaliar modelos de machine learning e associa o modelo a um dispositivo que, em seguida, executa e avalia o modelo. Você pode selecionar um dispositivo ao criar uma sessão para executar o modelo em um dispositivo específico da sua máquina. O dispositivo padrão é a CPU.

Observação

Para saber mais sobre como escolher um dispositivo, examine a documentação Criar uma sessão .

Associar entradas e saídas do modelo:

Para associar entrada e saída, use a LearningModelBinding classe. Um modelo de machine learning tem recursos de entrada e saída, que transmitem informações para dentro e para fora do modelo. Lembre-se de que os recursos necessários devem ter suporte nas APIs do Windows ML. A LearningModelBinding classe é aplicada em um LearningModelSession para associar valores a recursos de entrada e saída nomeados.

A implementação do binding é gerada automaticamente pelo mlgen, portanto, você não precisa cuidar dela. A associação é implementada chamando os métodos predefinidos da classe LearningModelBinding. Em nosso caso, ela usa o método Bind para associar um valor ao tipo de recurso nomeado.

Avaliar o modelo:

Depois de criar uma sessão para associar o modelo e de associar valores às entradas e saídas do modelo, você pode avaliar as entradas do modelo e obter as previsões. Para executar o modelo, chame um dos métodos de avaliação predefinidos em LearningModelSession. Em nosso caso, usaremos o EvaluateAsync método.

Semelhante a CreateFromStreamAsync, o método EvaluateAsync também foi gerado automaticamente pelo Gerador de Código do WinML, portanto, você não precisa implementá-lo. Examine esse método no arquivo bestModel.cs.

O método EvaluateAsync avaliará de modo assíncrono o modelo de machine learning usando os valores de características já associados nos bindings. Ele criará uma sessão com LearningModelSession, associará a entrada e a saída com LearningModelBinding, executará a avaliação do modelo e obterá as características de saída do modelo usando a classe LearningModelEvaluationResult.

Observação

Para saber mais sobre outros métodos de avaliação para executar o modelo, verifique quais métodos podem ser implementados no LearningModelSession examinando a documentação da Classe LearningModelSession.

  1. Adicione o seguinte método ao arquivo de código MainPage.xaml.cs dentro da classe MainPage para criar uma sessão, associar e avaliar o modelo.
        // A method to evaluate the model
        private async Task evaluate()
        {
            results = await modelGen.EvaluateAsync(image);
        }

Extrair e exibir os resultados

Agora, você precisará extrair a saída do modelo e exibir o resultado certo, o que você fará implementando os métodos extractResult e displayResult. Você precisará encontrar a probabilidade mais alta para retornar o rótulo correto.

  1. Adicione o método extractResult ao seu arquivo de código MainPage.xaml.cs dentro da classe MainPage.
        // A method to extract output from the model 
        private void extractResult()
        {
            // Retrieve the results of evaluation
            var mResult = results.modelOutput as TensorFloat;
            // convert the result to vector format
            var resultVector = mResult.GetAsVectorView();
            
            probability = 0;
            int index = 0;
            // find the maximum probability
            for(int i=0; i<resultVector.Count; i++)
            {
                var elementProbability=resultVector[i];
                if (elementProbability > probability)
                {
                    index = i;
                }
            }
            label = ((Labels)index).ToString();
        }
  1. Adicione o método displayResult ao seu arquivo de código MainPage.xaml.cs dentro da classe MainPage.
        private async Task displayResult() 
        {
            displayOutput.Text = label; 
        }

Pronto! Você criou com êxito o aplicativo Windows Machine Learning com uma GUI básica para testar o modelo de classificação. A próxima etapa é iniciar o aplicativo e executá-lo localmente em seu dispositivo Windows.

Iniciar o aplicativo

Depois de concluir a interface do aplicativo, adicionar o modelo e gerar o código do Windows ML, você poderá testar o aplicativo.

Habilite o modo de desenvolvedor e teste seu aplicativo no Visual Studio. Verifique se os menus suspensos na barra de ferramentas superior estão definidos como Debug. Altere a Plataforma de Solução para x64 para executar o projeto no computador local se seu dispositivo for de 64 bits ou x86 se for de 32 bits.

Para testar nosso aplicativo, vamos usar a imagem abaixo da sopa. Vamos ver como o aplicativo classifica o conteúdo da imagem.

Imagem para teste de aplicativo

  1. Salve essa imagem em seu dispositivo local para testar o aplicativo. Altere o formato da imagem para .jpg, se necessário. Você também pode adicionar qualquer outra imagem relevante de seu dispositivo local em um .jpg ou .png formato.

  2. Para executar o projeto, selecione o botão Start Debugging na barra de ferramentas ou pressione F5.

  3. Quando o aplicativo for iniciado, pressione Pick Image e selecione a imagem no dispositivo local.

Interface do aplicativo

O resultado será exibido na tela imediatamente. Como você pode ver, nosso aplicativo do Windows ML classificou com êxito a imagem como uma sopa.

Classificação bem-sucedida em seu aplicativo

Resumo

Você acabou de criar seu primeiro aplicativo do Windows Machine Learning, desde a criação de modelos até a execução bem-sucedida.

Recursos adicionais

Para saber mais sobre os tópicos mencionados neste tutorial, visite os seguintes recursos: