MLEdgeModel

The MLEdgeModel represents an ML model that makes predictions on the local device. As such, it forms the basis for implementing Edge predictors in code.
Inspecting Feature Types
Edge models provide information about their expected input and output feature types. This type information is crucial for writing Edge predictors.
Input Features
1
/// <summary>
2
/// Model input feature types.
3
/// </summary>
4
MLFeatureType[] inputs { get; }
Copied!
Refer to the Input Features section of the MLModel class for more information.
Output Features
1
/// <summary>
2
/// Model output feature types.
3
/// </summary>
4
MLFeatureType[] outputs { get; }
Copied!
Refer to the Output Features section of the MLModel class for more information.
Inspecting Metadata
1
/// <summary>
2
/// Get the model metadata dictionary.
3
/// </summary>
4
IReadOnlyDictionary<string, string> metadata { get; }
Copied!
Refer to the Inspecting Metadata section of the MLModel class for more information.
Making Edge Predictions
1
/// <summary>
2
/// Make a prediction on one or more Edge ML features.
3
/// Input and output features MUST be disposed when no longer needed.
4
/// </summary>
5
/// <param name="inputs">Input Edge ML features.</param>
6
/// <returns>Output Edge ML features.</returns>
7
MLFeatureCollection<MLEdgeFeature> Predict (params MLEdgeFeature[] inputs);
Copied!
The Edge model exposes a Predict method which makes predictions on one or more MLEdgeFeature instances. It returns a collection of MLEdgeFeature instances, which can then be used with corresponding feature classes (MLArrayFeature, MLAudioFeature, and so on).
The input and output features MUST be disposed when they are no longer needed. Call Dispose on the individual features, or on the returned feature collection to do so.
Disposing the Model
1
/// <summary>
2
/// Dispose the model and release resources.
3
/// </summary>
4
void Dispose ();
Copied!
Refer to the Disposing the Model section of the MLModel class for more information.
Implementing Edge Predictors
As you might have noticed above, MLEdgeModel instances typically won't be used directly. Instead, they will be used through Edge Predictors, which are lightweight classes that can transform input data into the model's expected input features; and can transform the model's output features into easily usable types. Below are the general steps in implementing Edge predictors:
Defining the Predictor
All Edge predictors must inherit from the IMLPredictor<TOutput> interface. The predictor has a single generic type argument, TOutput, which is a developer-friendly type that is returned when a prediction is made. For example, the MobileNetv2Predictor predictor class which classifies an image uses a tuple for its output type:
1
// The MobileNetv2 classification predictor returns a tuple
2
class MobileNetv2Predictor : IMLPredictor<(string label, float confidence)> { ... }
Copied!
Defining Constructors
All Edge predictors must define one or more constructors that accept one or more MLModel instances, along with any other supplemental data needed to make predictions with the model(s). For example:
1
/// <summary>
2
/// Create a custom predictor.
3
/// </summary>
4
/// <param name="model">ML model used to make predictions.</param>
5
public CustomPredictor (MLModel model) { ... }
Copied!
Within the constructor, the model should cast the MLModel to an MLEdgeModel and store a readonly reference to the edge model:
1
// Store a reference to the Edge model
2
private readonly MLEdgeModel model;
Copied!
Making Predictions
All Edge predictors must implement a public Predict method which accepts a params MLFeature[] and returns a TOutput, for example:
1
/// <summary>
2
/// Make a prediction with the model.
3
/// </summary>
4
/// <param name="inputs">Input feature.</param>
5
/// <returns>Output label with unnormalized confidence value.</returns>
6
public (string label, float confidence) Predict (params MLFeature[] inputs);
Copied!
Within the Predict method, the predictor should do three things:
Input Checking
The predictor should check that the client has provided the correct number of input features, and that the features have the model's expected types.
If these checks fail, an appropriate exception should be thrown. Do this instead of returning an un-initialized output.
Prediction
To make predictions, the predictor must create MLEdgeFeature instances from input features. Creating an MLEdgeFeature typically requires a corresponding MLFeatureType which dictates any required pre-processing when creating the edge feature. You will typically use the model's input feature types for this purpose:
1
// Get or create the native feature type which the model expects
2
MLFeatureType inputType = model.inputs[0];
3
// Create an Edge feature from the input feature
4
using MLEdgeFeature edgeFeature = (inputFeature as IMLEdgeFeature).Create(inputType);
Copied!
To check if a feature can be used for Edge predictions, cast it to an IMLEdgeFeature and check that the result of the cast is not null.
Once you have created all the required Edge features, you can then make predictions with the MLEdgeModel:
1
// Make a prediction with one or more native input features
2
using var outputFeatures = model.Predict(edgeFeature);
Copied!
Marshaling
Once you have output Edge features from the model, you can then marshal the feature data into a more developer-friendly type. This is where most of the heavy-lifting happens in a predictor:
1
// Marshal the output feature data into a developer-friendly type
2
var arrayFeature = new MLArrayFeature<float>(outputFeatures[0]);
3
// Do stuff with this data...
4
...
Copied!
Finally, return your predictor's output:
1
// Create the prediction result from the output data
2
TOutput result = ...;
3
// Return it
4
return result;
Copied!
Disposing the Predictor
All Edge predictors must define a Dispose method, because IMLPredictor implements the IDisposable interface. This method should be used to dispose any explicitly-managed resources used by the predictor. If a predictor does not have any explicitly-managed resources to dispose, then the predictor should hide the Dispose method using interface hiding:
1
// Hide the `Dispose` method so that clients cannot use it directly
2
void IDisposable.Dispose () { }
Copied!
The predictor must not Dispose any models provided to it. This is the responsibility of the client.

API Reference - Previous

MLModel

MLCloudModel

Last modified 15d ago

Copy link

Contents

Inspecting Feature Types

Input Features

Output Features

Inspecting Metadata

Making Edge Predictions

Disposing the Model

Implementing Edge Predictors

Defining the Predictor

Defining Constructors

Making Predictions

Disposing the Predictor