Faça previsões com um modelo AutoML ONNX em .NETMake predictions with an AutoML ONNX model in .NET

Neste artigo, aprende-se a utilizar um modelo automatizado de ML (AutoML) Open Neural Network Exchange (ONNX) para fazer previsões numa aplicação de consola C# .NET Core com ML.NET.In this article, you learn how to use an Automated ML (AutoML) Open Neural Network Exchange (ONNX) model to make predictions in a C# .NET Core console application with ML.NET.

ML.NET é um quadro de aprendizagem automática de código aberto, transversal para o ecossistema .NET que permite treinar e consumir modelos de aprendizagem automática personalizados utilizando uma abordagem de código em C# ou F# bem como através de ferramentas de baixo código como Model Builder e o ML.NET CLI.ML.NET is an open-source, cross-platform, machine learning framework for the .NET ecosystem that allows you to train and consume custom machine learning models using a code-first approach in C# or F# as well as through low-code tooling like Model Builder and the ML.NET CLI. A estrutura também é extensível e permite-lhe alavancar outros quadros populares de aprendizagem automática como o TensorFlow e o ONNX.The framework is also extensible and allows you to leverage other popular machine learning frameworks like TensorFlow and ONNX.

O ONNX é um formato de código aberto para modelos de IA.ONNX is an open-source format for AI models. A ONNX apoia a interoperabilidade entre quadros.ONNX supports interoperability between frameworks. Isto significa que você pode treinar um modelo em um dos muitos quadros populares de aprendizagem de máquinas como PyTorch, convertê-lo em formato ONNX, e consumir o modelo ONNX em um quadro diferente como ML.NET.This means you can train a model in one of the many popular machine learning frameworks like PyTorch, convert it into ONNX format, and consume the ONNX model in a different framework like ML.NET. Para saber mais, visite o site da ONNX.To learn more, visit the ONNX website.

Pré-requisitosPrerequisites

Criar uma aplicação de consola C#Create a C# console application

Nesta amostra, utiliza o CLI .NET Core para construir a sua aplicação, mas pode fazer as mesmas tarefas utilizando o Visual Studio.In this sample, you use the .NET Core CLI to build your application but you can do the same tasks using Visual Studio. Saiba mais sobre o .NET Core CLI.Learn more about the .NET Core CLI.

  1. Abra um terminal e crie uma nova aplicação de consola C# .NET Core.Open a terminal and create a new C# .NET Core console application. Neste exemplo, o nome da aplicação é AutoMLONNXConsoleApp .In this example, the name of the application is AutoMLONNXConsoleApp. Um diretório é criado com o mesmo nome com o conteúdo da sua aplicação.A directory is created by that same name with the contents of your application.

    dotnet new console -o AutoMLONNXConsoleApp
    
  2. No terminal, navegue para o diretório AutoMLONNXConsoleApp.In the terminal, navigate to the AutoMLONNXConsoleApp directory.

    cd AutoMLONNXConsoleApp
    

Adicionar pacotes de softwareAdd software packages

  1. Instale os pacotes nuGet do Microsoft.ML, Microsoft.ML.OnnxRuntime e Microsoft.ML.OnnxTransformer NuGet utilizando o .NET Core CLI.Install the Microsoft.ML, Microsoft.ML.OnnxRuntime, and Microsoft.ML.OnnxTransformer NuGet packages using the .NET Core CLI.

    dotnet add package Microsoft.ML
    dotnet add package Microsoft.ML.OnnxRuntime
    dotnet add package Microsoft.ML.OnnxTransformer
    

    Estas embalagens contêm as dependências necessárias para utilizar um modelo ONNX numa aplicação .NET.These packages contain the dependencies required to use an ONNX model in a .NET application. ML.NET fornece uma API que usa o tempo de execução ONNX para previsões.ML.NET provides an API that uses the ONNX runtime for predictions.

  2. Abra o ficheiro .cs Programa e adicione as using seguintes declarações no topo para fazer referência aos pacotes apropriados.Open the Program.cs file and add the following using statements at the top to reference the appropriate packages.

    using System.Linq;
    using Microsoft.ML;
    using Microsoft.ML.Data;
    using Microsoft.ML.Transforms.Onnx;
    

Adicione uma referência ao modelo ONNXAdd a reference to the ONNX model

Uma forma de a aplicação da consola aceder ao modelo ONNX é adicioná-la ao diretório de saída de construção.A way for the console application to access the ONNX model is to add it to the build output directory. Para saber mais sobre os itens comuns da MSBuild, consulte o guia MSBuild.To learn more about MSBuild common items, see the MSBuild guide.

Adicione uma referência ao seu ficheiro modelo ONNX na sua aplicaçãoAdd a reference to your ONNX model file in your application

  1. Copie o seu modelo ONNX para o diretório de raiz AutoMLONNXConsoleApp da sua aplicação.Copy your ONNX model to your application's AutoMLONNXConsoleApp root directory.

  2. Abra o ficheiro AutoMLONNXConsoleApp.csproj e adicione o seguinte conteúdo dentro do Project nó.Open the AutoMLONNXConsoleApp.csproj file and add the following content inside the Project node.

    <ItemGroup>
        <None Include="automl-model.onnx">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
    </ItemGroup>
    

    Neste caso, o nome do ficheiro modelo ONNX é automl-model.onnx.In this case, the name of the ONNX model file is automl-model.onnx.

  3. Abra o ficheiro .cs Programa e adicione a seguinte linha dentro da Program classe.Open the Program.cs file and add the following line inside the Program class.

    static string ONNX_MODEL_PATH = "automl-model.onnx";
    

Inicializar O Texto MLContextoInitialize MLContext

Dentro do Main método da sua Program classe, crie um novo exemplo de MLContext .Inside the Main method of your Program class, create a new instance of MLContext.

MLContext mlContext = new MLContext();

A MLContext classe é um ponto de partida para todas as operações ML.NET, e a inicialização cria mlContext um novo ambiente ML.NET que pode ser partilhado através do ciclo de vida do modelo.The MLContext class is a starting point for all ML.NET operations, and initializing mlContext creates a new ML.NET environment that can be shared across the model lifecycle. É semelhante, conceptualmente, ao DbContext no Quadro de Entidades.It's similar, conceptually, to DbContext in Entity Framework.

Definir o esquema de dados do modeloDefine the model data schema

O seu modelo espera os seus dados de entrada e saída num formato específico.Your model expects your input and output data in a specific format. ML.NET permite definir o formato dos seus dados através das aulas.ML.NET allows you to define the format of your data via classes. Às vezes já se sabe como é o formato.Sometimes you may already know what that format looks like. Nos casos em que não conhece o formato de dados, pode utilizar ferramentas como o Netron para inspecionar o seu modelo ONNX.In cases when you don't know the data format, you can use tools like Netron to inspect your ONNX model.

O modelo utilizado nesta amostra utiliza dados do conjunto de dados da NyC TLC Taxi Trip.The model used in this sample uses data from the NYC TLC Taxi Trip dataset. Uma amostra dos dados pode ser vista abaixo:A sample of the data can be seen below:

vendor_idvendor_id rate_coderate_code passenger_countpassenger_count trip_time_in_secstrip_time_in_secs trip_distancetrip_distance payment_typepayment_type fare_amountfare_amount
VTSVTS 11 11 11401140 3,753.75 CRDCRD 15,515.5
VTSVTS 11 11 480480 2.722.72 CRDCRD 10,010.0
VTSVTS 11 11 16801680 7.87.8 CSHCSH 26,526.5

Inspecione o modelo ONNX (opcional)Inspect the ONNX model (optional)

Utilize uma ferramenta como a Netron para inspecionar as entradas e saídas do seu modelo.Use a tool like Netron to inspect your model's inputs and outputs.

  1. Abre o Netron.Open Netron.

  2. Na barra de menu superior, selecione 'Arquivo > Abra e use o navegador de ficheiros para selecionar o seu modelo.In the top menu bar, select File > Open and use the file browser to select your model.

  3. O teu modelo abre.Your model opens. Por exemplo, a estrutura do modelo automl.onnx parece o seguinte:For example, the structure of the automl-model.onnx model looks like the following:

    Netron AutoML ONNX Modelo

  4. Selecione o último nó na parte inferior do gráfico variable_out1 (neste caso) para visualizar os metadados do modelo.Select the last node at the bottom of the graph (variable_out1 in this case) to display the model's metadata. As entradas e saídas na barra lateral mostram-lhe as entradas, saídas e tipos de dados esperados do modelo.The inputs and outputs on the sidebar show you the model's expected inputs, outputs, and data types. Utilize estas informações para definir o esquema de entrada e saída do seu modelo.Use this information to define the input and output schema of your model.

Definir esquema de entrada de modeloDefine model input schema

Crie uma nova classe chamada OnnxInput com as seguintes propriedades dentro do ficheiro Program.cs.Create a new class called OnnxInput with the following properties inside the Program.cs file.

public class OnnxInput
{
    [ColumnName("vendor_id")]
    public string VendorId { get; set; }

    [ColumnName("rate_code"),OnnxMapType(typeof(Int64),typeof(Single))]
    public Int64 RateCode { get; set; }

    [ColumnName("passenger_count"), OnnxMapType(typeof(Int64), typeof(Single))]
    public Int64 PassengerCount { get; set; }

    [ColumnName("trip_time_in_secs"), OnnxMapType(typeof(Int64), typeof(Single))]
    public Int64 TripTimeInSecs { get; set; }

    [ColumnName("trip_distance")]
    public float TripDistance { get; set; }

    [ColumnName("payment_type")]
    public string PaymentType { get; set; }
}

Cada uma das propriedades mapeia para uma coluna no conjunto de dados.Each of the properties maps to a column in the dataset. As propriedades são anotadas com atributos.The properties are further annotated with attributes.

O ColumnName atributo permite especificar como ML.NET deve referenciar a coluna ao operar os dados.The ColumnName attribute lets you specify how ML.NET should reference the column when operating on the data. Por exemplo, embora a TripDistance propriedade siga as convenções de nomeação padrão .NET, o modelo só sabe de uma coluna ou característica conhecida como trip_distance .For example, although the TripDistance property follows standard .NET naming conventions, the model only knows of a column or feature known as trip_distance. Para resolver esta discrepância de nomeação, o ColumnName atributo mapeia a TripDistance propriedade a uma coluna ou característica pelo nome trip_distance .To address this naming discrepancy, the ColumnName attribute maps the TripDistance property to a column or feature by the name trip_distance.

Para valores numéricos, ML.NET funciona apenas com Single tipos de valor.For numerical values, ML.NET only operates on Single value types. No entanto, o tipo de dados original de algumas das colunas são inteiros.However, the original data type of some of the columns are integers. Os OnnxMapType tipos de mapas de atributos entre ONNX e ML.NET.The OnnxMapType attribute maps types between ONNX and ML.NET.

Para saber mais sobre os atributos de dados, consulte o guia de dados de ML.NET carregar.To learn more about data attributes, see the ML.NET load data guide.

Definir esquema de saída de modeloDefine model output schema

Uma vez processados os dados, produz uma saída de um determinado formato.Once the data is processed, it produces an output of a certain format. Defina o seu esquema de saída de dados.Define your data output schema. Crie uma nova classe chamada OnnxOutput com as seguintes propriedades dentro do ficheiro Program.cs.Create a new class called OnnxOutput with the following properties inside the Program.cs file.

public class OnnxOutput
{
    [ColumnName("variable_out1")]
    public float[] PredictedFare { get; set; }
}

Semelhante a OnnxInput , use o atributo para ColumnName mapear a variable_out1 saída para um nome mais descritivo PredictedFare .Similar to OnnxInput, use the ColumnName attribute to map the variable_out1 output to a more descriptive name PredictedFare.

Definir um oleoduto de previsãoDefine a prediction pipeline

Um oleoduto em ML.NET é tipicamente uma série de transformações acorrentadas que operam nos dados de entrada para produzir uma saída.A pipeline in ML.NET is typically a series of chained transformations that operate on the input data to produce an output. Para saber mais sobre as transformações de dados, consulte o guia de transformação de dados ML.NET.To learn more about data transformations, see the ML.NET data transformation guide.

  1. Criar um novo método chamado GetPredictionPipeline dentro da Program classeCreate a new method called GetPredictionPipeline inside the Program class

    static ITransformer GetPredictionPipeline(MLContext mlContext)
    {
    
    }
    
  2. Defina o nome das colunas de entrada e saída.Define the name of the input and output columns. Adicione o seguinte código dentro do GetPredictionPipeline método.Add the following code inside the GetPredictionPipeline method.

    var inputColumns = new string []
    {
        "vendor_id", "rate_code", "passenger_count", "trip_time_in_secs", "trip_distance", "payment_type"
    };
    
    var outputColumns = new string [] { "variable_out1" };
    
  3. Defina o seu oleoduto.Define your pipeline. Um IEstimator fornece uma planta das operações, entradas e esquemas de saída do seu oleoduto.An IEstimator provides a blueprint of the operations, input, and output schemas of your pipeline.

    var onnxPredictionPipeline =
        mlContext
            .Transforms
            .ApplyOnnxModel(
                outputColumnNames: outputColumns,
                inputColumnNames: inputColumns,
                ONNX_MODEL_PATH);
    

    Neste caso, ApplyOnnxModel é a única transformação no pipeline, que requer os nomes das colunas de entrada e saída, bem como o caminho para o ficheiro do modelo ONNX.In this case, ApplyOnnxModel is the only transform in the pipeline, which takes in the names of the input and output columns as well as the path to the ONNX model file.

  4. Um IEstimator apenas define o conjunto de operações a aplicar aos seus dados.An IEstimator only defines the set of operations to apply to your data. O que opera nos seus dados é conhecido como ITransformer .What operates on your data is known as an ITransformer. Utilize o Fit método para criar um a partir do seu onnxPredictionPipeline .Use the Fit method to create one from your onnxPredictionPipeline.

    var emptyDv = mlContext.Data.LoadFromEnumerable(new OnnxInput[] {});
    
    return onnxPredictionPipeline.Fit(emptyDv);
    

    O Fit método espera uma entrada como entrada para realizar as IDataView operações.The Fit method expects an IDataView as input to perform the operations on. Uma IDataView é uma forma de representar dados em ML.NET usando um formato tabular.An IDataView is a way to represent data in ML.NET using a tabular format. Dado que neste caso o gasoduto é utilizado apenas para previsões, pode fornecer um vazio IDataView para fornecer ITransformer a informação necessária sobre o esquema de entrada e saída.Since in this case the pipeline is only used for predictions, you can provide an empty IDataView to give the ITransformer the necessary input and output schema information. O equipado ITransformer é então devolvido para posterior utilização na sua aplicação.The fitted ITransformer is then returned for further use in your application.

    Dica

    Nesta amostra, o gasoduto é definido e utilizado dentro da mesma aplicação.In this sample, the pipeline is defined and used within the same application. No entanto, recomenda-se que utilize aplicações separadas para definir e utilizar o seu pipeline para fazer previsões.However, it is recommended that you use separate applications to define and use your pipeline to make predictions. Na ML.NET os seus oleodutos podem ser serializados e guardados para posterior utilização noutras aplicações de utilizador final .NET.In ML.NET your pipelines can be serialized and saved for further use in other .NET end-user applications. ML.NET suporta vários alvos de implementação, tais como aplicações de desktop, serviços web, aplicações WebAssembly*, e muito mais.ML.NET supports various deployment targets such as desktop applications, web services, WebAssembly applications*, and many more. Para saber mais sobre a poupança de gasodutos, consulte o guia de modelos ML.NET economizadores e de carga.To learn more about saving pipelines, see the ML.NET save and load trained models guide.

    *WebAssembly só é suportado em .NET Core 5 ou superior*WebAssembly is only supported in .NET Core 5 or greater

  5. Dentro do Main método, ligue para o GetPredictionPipeline método com os parâmetros necessários.Inside the Main method, call the GetPredictionPipeline method with the required parameters.

    var onnxPredictionPipeline = GetPredictionPipeline(mlContext);
    

Use o modelo para fazer previsõesUse the model to make predictions

Agora que tens um oleoduto, está na altura de o usares para fazer previsões.Now that you have a pipeline, it's time to use it to make predictions. ML.NET fornece uma API de conveniência para fazer previsões sobre uma única instância de dados chamada PredictionEngine .ML.NET provides a convenience API for making predictions on a single data instance called PredictionEngine.

  1. Dentro do Main método, crie um PredictionEngine utilizando o CreatePredictionEngine método.Inside the Main method, create a PredictionEngine by using the CreatePredictionEngine method.

    var onnxPredictionEngine = mlContext.Model.CreatePredictionEngine<OnnxInput, OnnxOutput>(onnxPredictionPipeline);
    
  2. Crie uma entrada de dados de teste.Create a test data input.

    var testInput = new OnnxInput
    {
        VendorId = "CMT",
        RateCode = 1,
        PassengerCount = 1,
        TripTimeInSecs = 1271,
        TripDistance = 3.8f,
        PaymentType = "CRD"
    };
    
  3. Utilize o predictionEngine para fazer previsões com base nos novos testInput dados utilizando o Predict método.Use the predictionEngine to make predictions based on the new testInput data using the Predict method.

    var prediction = onnxPredictionEngine.Predict(testInput);
    
  4. Desemola o resultado da sua previsão para a consola.Output the result of your prediction to the console.

    Console.WriteLine($"Predicted Fare: {prediction.PredictedFare.First()}");
    
  5. Utilize o CLI .NET Core para executar a sua aplicação.Use the .NET Core CLI to run your application.

    dotnet run
    

    O resultado deve ser semelhante à seguinte saída:The result should look as similar to the following output:

    Predicted Fare: 15.621523
    

Para saber mais sobre fazer previsões em ML.NET, consulte o uso de um modelo para fazer guia de previsões.To learn more about making predictions in ML.NET, see the use a model to make predictions guide.

Passos seguintesNext steps