class NatSuite.ML.MLModelData

The MLModelData class is a self-contained archive containing an MLModel along with supplemental data that is useful to make predictions with the model.

Fetching Model Data

NatML supports fetching model data from multiple sources.

From NatML Hub

/// <summary>
/// Fetch ML model data from NatML hub.
/// </summary>
/// <param name="tag">Model tag.</param>
/// <param name="accessKey">Hub access key.</param>
/// <returns>ML model data.</returns>
static Task<MLModelData> FromHub (string tag, string accessKey = ...);

NatML provides a model hosting, delivery, and analytics service called NatML Hub. Hub is crucial when taking ML into production, because embedding ML models in the app can very quickly explode the bundle size. Furthermore, Hub is able to deliver models optimized specifically for individual devices, and provide important analytics on model performance.

NatML caches models that are loaded from Hub, meaning that a user only has to download the model once.

From File

/// <summary>
/// Fetch ML model data from a local file.
/// </summary>
/// <param name="path">Path to ONNX model file.</param>
/// <returns>ML model data.</returns>
static Task<MLModelData> FromFile (string path);

NatML allows for loading ML model data from files. Currently, only .onnx model files are supported.

Model data loaded from a file will contain no supplemental data. As such, it is highly recommended to use NatML Hub instead.

From StreamingAssets

/// <summary>
/// Fetch ML model data from StreamingAssets.
/// </summary>
/// <param name="path">Relative path to ONNX model file in `StreamingAssets` folder.</param>
/// <returns>ML model data.</returns>
static Task<MLModelData> FromStreamingAssets (string relativePath);

ML model data can also be loaded from StreamingAssets. This function accepts the relative path of the model file.

Model data loaded from StreamingAssets will contain no supplemental data. As such, it is highly recommended to use NatML Hub instead.

Creating a Model

/// <summary>
/// Deserialize the model data to create an ML model that can be used for prediction.
/// You MUST dispose the model once you are done with it.
/// </summary>
/// <returns>ML model.</returns>
MLModel Deserialize ();

An MLModel is created from model data. The model can then be used with a predictor to make predictions.

You must Dispose the model when you are done with it. Failing to do so will result in severe resource leaks.

Using Supplemental Data

Model data contains additional information needed to make a prediction with a model.

Classification Labels

/// <summary>
/// Model classification labels.
/// This is `null` if the model does not have any classification labels.
/// </summary>
string[] labels { get; }

For classification and detection models, this field contains the list of class labels associated with each class in the output distribution. If class labels don't apply to the model, it will return null.

Image Normalization

/// <summary>
/// Expected image feature normalization for predictions with this model.
/// </summary>
Normalization normalization { get; }

Vision models often require that images be normalized to a specific mean and standard deviation. As such, MLModelData includes an opaque normalization struct that can be deconstructed like so:

// Get the model's preferred image normalization
Vector3 mean, std;
(mean, std) = modelData.normalization;

Image Aspect Mode

/// <summary>
/// Expected image aspect mode for predictions with this model.
/// </summary>
MLImageFeature.AspectMode aspectMode { get; }

Vision models might require that input image features be scaled a certain way when they are resized to fit the model's input size. The aspectMode can be passed directly to an MLImageFeature.