Awesome

Machine Learning Model Extension Specification

• Title: Machine Learning Model Extension
• Identifier: https://stac-extensions.github.io/mlm/v1.3.0/schema.json
• Field Name Prefix: mlm
• Scope: Collection, Item, Asset, Links
• Extension Maturity Classification: Pilot
• Owner:
  • @fmigneault
  • @rbavery
  • @ymoisan
  • @sfoucher

Contributors

Description

The STAC Machine Learning Model (MLM) Extension provides a standard set of fields to describe machine learning models trained on overhead imagery and enable running model inference.

The main objectives of the extension are:

1. to enable building model collections that can be searched alongside associated STAC datasets
2. record all necessary bands, parameters, modeling artifact locations, and high-level processing steps to deploy an inference service.

Specifically, this extension records the following information to make ML models searchable and reusable:

1. Sensor band specifications
2. Model input transforms including resize and normalization
3. Model output shape, data type, and its semantic interpretation
4. An optional, flexible description of the runtime environment to be able to run the model
5. Scientific references

The MLM specification is biased towards providing metadata fields for supervised machine learning models. However, fields that relate to supervised ML are optional and users can use the fields they need for different tasks.

Francis Charette-Migneault, Ryan Avery, Brian Pondi, Joses Omojola, Simone Vaccari, Parham Membari, Devis Peressutti, Jia Yu, and Jed Sundwall. 2024. Machine Learning Model Specification for Cataloging Spatio-Temporal Models (Demo Paper). In 3rd ACM SIGSPATIAL International Workshop on Searching and Mining Large Collections of Geospatial Data (GeoSearch’24), October 29–November 1 2024, Atlanta, GA, USA. ACM, New York, NY, USA, 4 pages. https://doi.org/10.1145/3681769.3698586

See Best Practices for guidance on what other STAC extensions you should use in conjunction with this extension.

The Machine Learning Model Extension purposely omits and delegates some definitions to other STAC extensions to favor reusability and avoid metadata duplication whenever possible. A properly defined MLM STAC Item/Collection should almost never have the Machine Learning Model Extension exclusively in stac_extensions.

For details about the earlier (legacy) version of the MLM Extension, formerly known as the Deep Learning Model Extension (DLM), please refer to the DLM LEGACY document. DLM was renamed to the current MLM Extension and refactored to form a cohesive definition across all machine learning approaches, regardless of whether the approach constitutes a deep neural network or other statistical approach. It also combines multiple definitions from the predecessor ML-Model extension to synthesize common use cases into a single reference for Machine Learning Models.

For more details about the stac-model Python package, which provides definitions of the MLM extension using both Pydantic and PySTAC connectors, please refer to the STAC Model document.

Resources

• Examples:
  • Item examples for scene-classification, object detection, and semantic segmentation: Shows real world use of the extension for describing models run on WherobotsAI Raster Inference
  • Collection example: Shows the basic usage of the extension in a STAC Collection
• JSON Schema
• Changelog
• Open access paper describing version 1.3.0 of the extension
• SigSpatial 2024 GeoSearch Workshop presentation

Item Properties and Collection Fields

The fields in the table below can be used in these parts of STAC documents:

• Catalogs
• Collections
• Item Properties (incl. Summaries in Collections)
• Assets (for both Collections and Items, incl. Item-Assets definitions in Collections)
• Links

Notes

<b>¹ Fields allowed only in Item properties<b>

[!NOTE] Unless stated otherwise by ^[1] in the table, fields can be used at either the Item or Asset level. <br><br> To decide whether above fields should be applied under Item properties or under respective Assets, the context of each field must be considered. For example, the mlm:name should always be provided in the Item properties, since it relates to the model as a whole. In contrast, some models could support multiple mlm:accelerator, which could be handled by distinct source code represented by different Assets. In such case, mlm:accelerator definitions should be nested under their relevant Asset. If a field is defined both at the Item and Asset level, the value at the Asset level would be considered for that specific Asset, and the value at the Item level would be used for other Assets that did not override it for their respective reference. For some of the fields, further details are provided in following sections to provide more precisions regarding some potentially ambiguous use cases.

In addition, fields from the multiple relevant extensions should be defined as applicable. See Best Practices - Recommended Extensions to Compose with the ML Model Extension for more details.

For the Extent Object in STAC Collections and the corresponding spatial and temporal fields in Items, please refer to section Best Practices - Using STAC Common Metadata Fields for the ML Model Extension.

Model Architecture

In most cases, this should correspond to common architecture names defined in the literature, such as ResNet, VGG, GAN or Vision Transformer. For more examples of proper names (including casing), the Papers With Code - Computer Vision Methods can be used. Note that this field is not an explicit "Enum", and is used only as an indicator of common architecture occurrences. If no specific or predefined architecture can be associated with the described model, simply employ unknown or another custom name as deemed appropriate.

Task Enum

It is recommended to define mlm:tasks of the entire model at the STAC Item level, and tasks of respective Model Output Object with the following values. Although other values are permitted to support more use cases, they should be used sparingly to allow better interoperability of models and their representation.

As a general rule of thumb, if a task is not represented below, an appropriate name can be formulated by taking definitions listed in Papers With Code. The names should be normalized to lowercase and use hyphens instead of spaces.

If the task falls within the category of supervised machine learning and uses labels during training, this should align with the label:tasks values defined in STAC Label Extension for relevant STAC Collections and Items published with the model described by this extension.

It is to be noted that multiple "generic" tasks names (classification, detection, etc.) are defined to allow correspondance with label:tasks, but these can lead to some ambiguity depending on context. For example, a model that supports classification could mean that the model can predict patch-based classes over an entire scene (i.e.: scene-classification for a single prediction over an entire area of interest as a whole), or that it can predict pixel-wise "classifications", such as land-cover labels for every single pixel coordinate over the area of interest. Maybe counter-intuitively to some users, such a model that produces pixel-wise "classifications" should be attributed the segmentation task (and more specifically semantic-segmentation) rather than classification. To avoid this kind of ambiguity, it is strongly recommended that tasks always aim to provide the most specific definitions possible to explicitly describe what the model accomplishes.

Framework

This should correspond to the common library name of a well-established ML framework. No "Enum" are enforced to allow easy addition of newer frameworks, but it is STRONGLY recommended to use common names when applicable. Below are a few notable entries.

• PyTorch
• TensorFlow
• scikit-learn
• Hugging Face
• Keras
• ONNX
• rgee
• spatialRF
• JAX
• MXNet
• Caffe
• PyMC
• Weka

Accelerator Type Enum

It is recommended to define accelerator with one of the following values:

• amd64 models compatible with AMD or Intel CPUs (no hardware specific optimizations)
• cuda models compatible with NVIDIA GPUs
• xla models compiled with XLA. Models trained on TPUs are typically compiled with XLA.
• amd-rocm models trained on AMD GPUs
• intel-ipex-cpu for models optimized with IPEX for Intel CPUs
• intel-ipex-gpu for models optimized with IPEX for Intel GPUs
• macos-arm for models trained on Apple Silicon

[!WARNING] If mlm:accelerator = amd64, this explicitly indicates that the model does not (and will not try to) use any accelerator, even if some are available from the runtime environment. This is to be distinguished from the value mlm:accelerator = null, which means that the model could make use of some accelerators if provided, but is not constrained by any specific one. To improve comprehension by users, it is recommended that any model using mlm:accelerator = amd64 also set explicitly mlm:accelerator_constrained = true to illustrate that the model WILL NOT use accelerators, although the hardware resolution should be identical nonetheless.

When mlm:accelerator = null is employed, the value of mlm:accelerator_constrained can be ignored, since even if set to true, there would be no accelerator to contain against. To avoid confusion, it is suggested to set the mlm:accelerator_constrained = false or omit the field entirely in this case.

Model Input Object

Fields that accept the null value can be considered null when omitted entirely for parsing purposes. However, setting null explicitly when this information is known by the model provider can help users understand what is the expected behavior of the model. It is therefore recommended to provide null explicitly when applicable.

Bands and Statistics

Depending on the supported stac_version and other stac_extensions employed by the STAC Item using MLM, the STAC 1.1 - Band Object, the STAC Raster - Band Object or the STAC EO - Band Object can be used for representing bands information, including notably the nodata value, the data_type (see also Data Type Enum), and Common Band Names.

[!WARNING] Only versions v1.x of eo and raster are supported to provide mlm:input band references. Versions 2.x of those extensions rely on the STAC 1.1 - Band Object instead. If those versions are desired, consider migrating your MLM definition to use STAC 1.1 - Band Object as well for referencing mlm:input with band names.

[!NOTE] Due to how the schema for eo:bands is defined, it is not sufficient to only provide the eo:bands property at the STAC Item level. The schema validation of the EO extension explicitly looks for a corresponding set of bands under an Asset, and if none is found, it disallows eo:bands in the Item properties. Therefore, eo:bands should either be specified only under the Asset containing the mlm:model role (see Model Asset), or define them both under the Asset and Item properties. If the second approach is selected, it is recommended that the eo:bands under the Asset contains only the name or the common_name property, such that all other details about the bands are defined and cross-referenced by name with the Item-level band definitions. An example of such representation is provided in examples/item_eo_bands_summarized.json. For an example where eo:bands are entirely defined in the Asset on their own, please refer to examples/item_eo_bands.json instead. <br><br> For more details, refer to stac-extensions/eo#12. <br>

[!NOTE] When using raster:bands, and additional name parameter MUST be provided for each band. This parameter is not defined in raster extension itself, but is permitted. This addition is required to ensure that mlm:input bands referenced by name can be associated to their respective raster:bands definitions.

Only bands used as input to the model should be included in the MLM bands field. To avoid duplicating the information, MLM only uses the name of whichever "Band Object" is defined in the STAC Item. An input's bands definition can either be a plain string or a Model Band Object. When a string is employed directly, the value should be implicitly mapped to the name property of the explicit object representation.

One distinction from the STAC 1.1 - Band Object in MLM is that Band Statistics object (or the corresponding STAC Raster - Statistics for STAC 1.0) are not defined at the "Band Object" level, but at the Model Input level. This is because, in machine learning, it is common to need overall statistics for the dataset used to train the model to normalize all bands, rather than normalizing the values over a single product. Furthermore, statistics could be applied differently for distinct Model Input definitions, in order to adjust for intrinsic properties of the model.

Another distinction is that, depending on the model, statistics could apply to some inputs that have no reference to any bands definition. In such case, defining statistics under bands would not be possible, or would intrude ambiguous definitions.

Finally, contrary to the "statistics" property name employed by Band Statistics, MLM employs the distinct name value_scaling, although similar minimum, maximum, etc. sub-fields are employed. This is done explicitly to disambiguate "informative" band statistics from "applied scaling operations" required by the model inputs. This highlights the fact that value_scaling are not necessarily equal to Band Statistics values, although they are often equal in practice due to the applicable value-range domains they represent. Also, this allows addressing special scaling cases, using additional properties unavailable from Band Statistics, such as value-specific scaling (see Value Scaling Object for more details).

Model Band Object

[!NOTE] Although format and expression are not required in this context, they are mutually dependent on each other. <br> See also Processing Expression for more details and examples.

The format and expression properties can serve multiple purpose.

1. Applying a band-specific pre-processing step, in contrast to pre_processing_function applied over all bands. For example, reshaping a band to align its dimensions with other bands before stacking them.

2. Defining a derived-band operation or a calculation that produces a virtual band from other band references. For example, computing an indice that applies an arithmetic combination of other bands.

For a concrete example, see examples/item_bands_expression.json.

Data Type Enum

When describing the data_type provided by a Band, whether for defining the Input Structure or the Result Structure, the Data Types from the STAC Raster extension should be used if using STAC 1.0 or earlier, and can use Data Types from STAC 1.1 Core for later versions. Both definitions should define equivalent values.

Input Structure Object

A common use of -1 for one dimension of shape is to indicate a variable batch-size. However, this value is not strictly reserved for the b dimension. For example, if the model is capable of automatically adjusting its input layer to adapt to the provided input data, then the corresponding dimensions that can be adapted can employ -1 as well.

Dimension Order

Recommended values should use common names as much as possible to allow better interpretation by users and scripts that could need to resolve the dimension ordering for reshaping requirements according to the ML framework employed.

Below are some notable common names recommended for use, but others can be employed as needed.

• batch
• channel
• time
• height
• width
• depth
• token
• class
• score
• confidence

For example, a tensor of multiple RBG images represented as $B \times C \times H \times W$ should indicate dim_order = ["batch", "channel", "height", "width"].

Value Scaling Object

Select one option from:

When a scaling type approach is specified, it is expected that the parameters necessary to perform their calculation are provided for the corresponding input dimension data.

If none of the above values applies for a given dimension, type: null (literal null, not string) should be used instead. If none of the input dimension require scaling, the entire definition can be defined as value_scaling: null or be omitted entirely.

When value_scaling is specified, the amount of objects defined in the array must match the size of the bands/channels/dimensions described by the Model Input. However, the value_scaling array is allowed to contain a single object if the entire input must be rescaled using the same definition across all dimensions. In such case, implicit broadcasting of the unique Value Scaling Object should be performed for all applicable dimensions when running inference with the model.

If a custom scaling operation, or a combination of more complex operations (with or without Resize), must be defined instead, a Processing Expression reference can be specified in place of the Value Scaling Object of the respective input dimension, as shown below.

{
  "value_scaling": [
    {"type": "min-max", "minimum": 0, "maximum": 255},
    {"type": "clip", "minimum": 0, "maximum": 255},
    {"type": "processing", "format": "gdal-calc", "expression": "A * logical_or( A<=177, A>=185 )"}
  ]
}

For operations such as L1 or L2 normalization, Processing Expression should also be employed. This is because, depending on the Model Input dimensions and reference data, there is an ambiguity regarding "how" and "where" such normalization functions must be applied against the input data. A custom mathematical expression should provide explicitly the data manipulation and normalization strategy.

In situations of very complex value_scaling operations, which cannot be represented by any of the previous definition, a pre_processing_function should be used instead (see Model Input Object).

Resize Enum

Select one option from:

• crop
• pad
• interpolation-nearest
• interpolation-linear
• interpolation-cubic
• interpolation-area
• interpolation-lanczos4
• interpolation-max
• wrap-fill-outliers
• wrap-inverse-map

See OpenCV - Interpolation Flags for details about the relevant methods. Equivalent methods from other packages are applicable as well.

If none of the above values applies, null (literal, not string) can be used instead. If a custom rescaling operation, or a combination of operations (with or without Value Scaling), must be defined instead, consider using a Processing Expression reference.

Processing Expression

Taking inspiration from Processing Extension - Expression Object, the processing expression defines at the very least a format and the applicable expression for it to perform pre/post-processing operations on MLM inputs/outputs.

On top of the examples already provided by Processing Extension - Expression Object, the following formats are recommended as alternative scripts and function references.

[!NOTE] Above definitions are only indicative, and more can be added as desired with even more custom definitions. It is left as an implementation detail for users to resolve how these expressions should be handled at runtime.

[!WARNING] See also discussion regarding additional processing expressions: stac-extensions/processing#31

Model Output Object

While only tasks is a required field, all fields are recommended for tasks that produce a fixed shape tensor and have output classes. Outputs that have variable dimensions, can define the result with the appropriate dimension value -1 in the shape field. When the model does not produce specific classes, such as for regression, image-captioning, super-resolution and some generative tasks, to name a few, the classification:classes can be omitted.

Result Structure Object

Class Object

See the documentation for the Class Object.

Model Hyperparameters Object

The hyperparameters are an open JSON object definition that can be used to provide relevant configurations for the model. Those can combine training details, inference runtime parameters, or both. For example, training hyperparameters could indicate the number of epochs that were used, the optimizer employed, the number of estimators contained in an ensemble of models, or the random state value. For inference, parameters such as the model temperature, a confidence cut-off threshold, or a non-maximum suppression threshold to limit proposal could be specified. The specific parameter names, and how they should be employed by the model, are specific to each implementation.

Following is an example of what the hyperparameters definition could look like:

{
  "mlm:hyperparameters": {
    "nms_max_detections": 500,
    "nms_threshold": 0.25,
    "iou_threshold": 0.5,
    "random_state": 12345
  }
}

Assets Objects

It is recommended that the Assets defined in a STAC Item using MLM extension use the above field property names for nesting the Assets in order to improve their quick identification, although the specific names employed are left up to user preference. However, the MLM Asset definitions MUST include the appropriate MLM Asset Roles to ensure their discovery.

A valid STAC MLM Item definition requires at least one Asset with the mlm:model role, as well as, an accompanying mlm:artifact_type property that describes how to employ it. An Asset described with this role is considered the "main" Model Asset being described by the STAC Item definition. Typically, there will be only one asset containing the mlm:model role. However, multiple Assets employing the mlm:model role are permitted to provide alternate interfaces of the same model (e.g.: using different frameworks or compilations), but those assets should have exactly the same model interfaces (i.e.: identical mlm:input, mlm:output, etc.). In such case, the mlm:artifact_type property should be used to distinguish them.

Additional definitions such as the Source Code Asset and the Container Asset are considered "side-car" Assets that help understand how to employ the model, such as through the reference training script that produced the model or a preconfigured inference runtime environment. These additional Assets are optional, but it is STRONGLY RECOMMENDED to provide them in order to help correct adoption and use of the described model by users.

MLM Asset Roles

Asset roles should include relevant names that describe them. This does not only include the Recommended Asset Roles from the core specification, such as data or metadata, but also descriptors such as mlm:model, mlm:weights and so on, as applicable for the relevant MLM Assets being described. Please refer to the following sections for roles requirements by specific MLM Assets.

Note that mlm: prefixed roles are used for identification purpose of the Assets, but non-prefixed roles can be provided as well to offer generic descriptors. For example, ["mlm:model", "model", "data"] could be considered for the Model Asset.

In order to provide more context, the following roles are also recommended were applicable:

[!NOTE] (*) These roles are offered as direct conversions from the previous extension that provided ML-Model Asset Roles to provide easier upgrade to the MLM extension.

Model Asset

Recommended Asset roles include mlm:weights or mlm:checkpoint for model weights that need to be loaded by a model definition and mlm:compiled for models that can be loaded directly without an intermediate model definition. In each case, the mlm:model MUST be applied as well to indicate that this asset represents the model.

It is also recommended to make use of the file extension for this Asset, as it can provide useful information to validate the contents of the model definition, by comparison with fields file:checksum and file:size for example.

Model Artifact Media-Type

Very few ML framework, libraries or model artifacts provide explicit IANA registered media-type to represent the contents they handle. When those are not provided, custom media-types can be considered. However, "unofficial but well-established" parameters should be reused over custom media-types when possible.

For example, the unofficial application/octet-stream; framework=pytorch definition is appropriate to represent a PyTorch .pt file, since its underlying format is a serialized pickle structure, and its framework parameter provides a clearer indication about the targeted ML framework and its contents. Since artifacts will typically be downloaded using a request stream into a runtime environment in order to employ the model, the application/octet-stream media-type is relevant for representing this type of arbitrary binary data. Being an official media-type, it also has the benefit to increase chances that HTTP clients will handle download of the contents appropriately when performing requests. In contrast, custom media-types such as application/x-pytorch have higher chances to be considered unacceptable (HTTP 406 Not Acceptable) by servers, which is why they should preferably be avoided.

Users can consider adding more parameters to provide additional context, such as profile=compiled to provide an additional hint that the specific PyTorch Ahead-of-Time Compilation profile is used for the artifact described by the media-type. However, users need to remember that those parameters are not official. In order to validate the specific framework and artifact type employed by the model, the MLM properties mlm:framework (see MLM Fields) and mlm:artifact_type (see Model Asset) should be employed instead to perform this validation if needed.

Artifact Type

This value can be used to provide additional details about the specific model artifact being described. For example, PyTorch offers various strategies for providing model definitions, such as Pickle (.pt), TorchScript, or PyTorch Ahead-of-Time Compilation (.pt2) approach. Since they all refer to the same ML framework, the Model Artifact Media-Type can be insufficient in this case to detect which strategy should be used to employ the model definition.

Following are some proposed Artifact Type values for corresponding approaches, but other names are permitted as well. Note that the names are selected using the framework-specific definitions to help the users understand the source explicitly, although this is not strictly required either.

Source Code Asset

If the referenced code does not directly offer a callable script to run the model, the mlm:entrypoint field should be added to the Asset Object in order to provide a pointer to the inference function to execute the model. For example, my_package.my_module:predict would refer to the predict function located in the my_module inside the my_package library provided by the repository.

It is strongly recommended to use a specific media-type such as text/x-python if the source code refers directly to a script of a known programming language. Using the HTML rendering of that source file, such as though GitHub for example, should be avoided. Using the "Raw Contents" endpoint for such cases is preferable. The text/html media-type should be reserved for cases where the URI generally points at a Git repository. Note that the URI including the specific commit hash, release number or target branch should be preferred over other means of referring to checkout procedures, although this specification does not prohibit the use of additional properties to better describe the Asset.

Since the source code of a model provides useful example on how to use it, it is also recommended to define relevant references to documentation using the example extension. See the Best Practices - Example Extension section for more details.

Recommended asset roles include code and metadata, since the source code asset might also refer to more detailed metadata than this specification captures.

Container Asset

If you're unsure how to containerize your model, we suggest starting from the latest official container image for your framework that works with your model and pinning the container version.

Examples:

• Pytorch Dockerhub
• Pytorch Docker Run Example
• Tensorflow Dockerhub
• Tensorflow Docker Run Example

Using a base image for a framework looks like:

# In your Dockerfile, pull the latest base image with all framework dependencies including accelerator drivers
FROM pytorch/pytorch:2.1.2-cuda11.8-cudnn8-runtime

### Your specific environment setup to run your model
RUN pip install my_package

You can also use other base images. Pytorch and Tensorflow offer docker images for serving models for inference.

• Torchserve
• TFServing

Relation Types

The following types should be used as applicable rel types in the Link Object of STAC Items describing Band Assets that result from the inference of a model described by the MLM extension.

It is recommended that the link using derived_from referring to another STAC definition using the MLM extension specifies the mlm:name value to make the derived reference more explicit.

Note that a derived product from model inference described by STAC should also consider using additional indications that it came of a model, such as described by the Best Practices - Processing Extension.

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PRs are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First, install everything with npm once. Navigate to the root of this repository and on your command line run:

npm install

Then to check Markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples