diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d50d11..ab92fe6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Add [ML-Model Legacy](./docs/legacy/ml-model.md) document providing migration guidance + from the deprecated [ML-Model](https://github.com/stac-extensions/ml-model) extension + (relates to [stac-extensions/ml-model#16](https://github.com/stac-extensions/ml-model/pull/16)). +- Move [DLM Legacy](./docs/legacy/dlm.md) document. - Add `embedding` as suggested dimension name (relates to [#77](https://github.com/stac-extensions/mlm/discussions/77)). - Add [`huggingface/safetensors`](https://github.com/huggingface/safetensors) diff --git a/README.md b/README.md index 7e5448f..38ad7a4 100644 --- a/README.md +++ b/README.md @@ -82,11 +82,12 @@ reusability and avoid metadata duplication whenever possible. A properly defined 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](README_DLM_LEGACY.md) document. +the *Deep Learning Model Extension* (DLM), please refer to the [DLM LEGACY](./docs/legacy/dlm.md) 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](https://github.com/stac-extensions/ml-model) -extension to synthesize common use cases into a single reference for Machine Learning Models. +extension to synthesize common use cases into a single reference for "*Machine Learning Models*". For migration +details from `ml-model` to `mlm`, please refer to the [ML-Model Legacy](./docs/legacy/ml-model.md) document. For more details about the [`stac-model`](./stac_model) Python package, which provides definitions of the MLM extension using both [`Pydantic`](https://docs.pydantic.dev/latest/) and [`PySTAC`](https://pystac.readthedocs.io/en/stable/) @@ -116,7 +117,7 @@ connectors, please refer to the [STAC Model](./README_STAC_MODEL.md) document. version [`1.3.0`](https://github.com/stac-extensions/mlm/blob/main/CHANGELOG.md#v130) of the extension. - [SigSpatial 2024 GeoSearch Workshop presentation](/docs/static/sigspatial_2024_mlm.pdf) - **Tools**: - - [MLM Form Filler](https://mlm-form.vercel.app/) a two page app to fill out and validate MLM STAC Item metadata.
+ - [MLM Form Filler](https://mlm-form.vercel.app/) a two-page app to fill out and validate MLM STAC Item metadata.
Check out the [wherobots/mlm-form](https://github.com/wherobots/mlm-form) repository if you have questions, issues, or want to contribute. diff --git a/README_DLM_LEGACY.md b/docs/legacy/dlm.md similarity index 74% rename from README_DLM_LEGACY.md rename to docs/legacy/dlm.md index b002c8c..3b94abd 100644 --- a/README_DLM_LEGACY.md +++ b/docs/legacy/dlm.md @@ -2,8 +2,8 @@ -> [!NOTE] -> This is legacy documentation references of [Deep Learning Model extension](https://github.com/crim-ca/dlm-extension) +> [!WARNING] +> This is legacy documentation reference of [Deep Learning Model extension](https://github.com/crim-ca/dlm-extension) > preceding the current Machine Learning Model (MLM) extension. diff --git a/docs/legacy/ml-model.md b/docs/legacy/ml-model.md new file mode 100644 index 0000000..56c9784 --- /dev/null +++ b/docs/legacy/ml-model.md @@ -0,0 +1,128 @@ +# ML Model Extension Specification + + + +> [!WARNING] +> This is legacy documentation reference of [ML-Model][ml-model] +> preceding the current Machine Learning Model ([MLM][mlm-spec]) extension. + + + +## Notable Differences + +- The [MLM][mlm-spec] extension covers more details at both the [Item](#item-properties) and [Asset](#asset-objects) + levels, making it easier to describe and use model metadata. + +- The [MLM][mlm-spec] extension covers runtime requirements using distinct [Asset Roles](#roles) + ([Model][mlm-asset-model], [Container][mlm-asset-container] and [Source Code][mlm-asset-code]) which allows + for more flexibility in describing how and which operations are performed by a given model. + This is in contrast to the [ML-Model][ml-model] extension that records [similar information][ml-model-runtimes] + in `ml-model:inference-runtime` or `ml-model:training-runtime` __*all at once*__, which leads to runtime ambiguities + and limited reusability. + +- The [MLM][mlm-spec] extension provides additional fields to better describe the model properties, such as + the [Model Inputs][mlm-inputs] to describe the input features, bands, data transforms, or any + other relevant data sources and preparation steps required by the model, the [Model Outputs][mlm-outputs] to describe + the output predictions, regression values, classes or other relevant information about what the model produces, and + the [Model Hyperparameters][mlm-hyperparam] to better describe training configuration + that lead to the model definition. All of these fields are __*undefined*__ in the [ML-Model][ml-model] extension. + +- The [MLM][mlm-spec] extension has a corresponding Python library [`stac-model`][mlm-stac-model], + which can be used to create and validate MLM metadata using [pydantic][pydantic]. + An example of the library in action is [provided in examples](./../../stac_model/examples.py). + The extension also provides [pystac MLM][pystac-mlm] for easier integration with the STAC ecosystem. + The [MLM Form Filler][mlm-form] is also available to help users create valid MLM metadata in a no-code fashion. + In contrast, [ML-Model][ml-model] extension does not provide any support for Python integration and requires the JSON + to be written manually. + +## Migration Tables + +Following are the corresponding fields between the legacy [ML-Model][ml-model] and the current [MLM][mlm-spec] +extension, which can be used to completely migrate to the newer *Machine Leaning Model* extension providing +enhanced features and interconnectivity with other STAC extensions (see also [Best Practices][mlm-bp]). + + + +> [!IMPORTANT] +> Only the limited set of [`ml-model`][ml-model] fields are listed below for migration guidelines. +> See the full [MLM Specification](./../../README.md) for all additional fields provided to further describe models. + + + +### Item Properties + +| ML-Model Field | MLM Field | Migration Details | +|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `ml-model:type`
(`"ml-model"` constant) | *n/a* | Including the MLM URI in `stac_extensions` is sufficient to indicate that the Item is a model. | +| `ml-model:learning_approach` | *n/a* | No direct mapping. Machine Learning training approaches can be very convoluted to describe. Instead, it is recommended to employ `derived_from` collection and other STAC Extension references to describe explicitly how the model was obtained. See [Best Practices][mlm-bp] for more details. | +| `ml-model:prediction_type`
(`string`) | `mlm:tasks`
(`[string]`) | ML-Model limited to a single task. MLM allows multiple. Use `[""]` to migrate directly. | +| `ml-model:architecture` | `mlm:architecture` | Direct mapping. | +| `ml-model:training-processor-type`
`ml-model:training-os` | `mlm:framework`
`mlm:framework_version`
`mlm:accelerator`
`mlm:accelerator_constrained`
`mlm:accelerator_summary`
`mlm:accelerator_count` | More fields are provided to describe the subtleties of compute hardware and ML frameworks that can be intricated between them. If compute hardware imposes OS dependencies, they are typically reflected through the framework version and/or the specific accelerator. Further subtleties are permitted with [complex accelerator values][mlm-acc-type]. | + +### Asset Objects + +#### Roles + +All [ML-Model Asset Roles](https://github.com/stac-extensions/ml-model/blob/main/README.md#roles) +are available with a prefix change with the same sematic meaning. + +Further roles are also proposed in [MLM Asset Roles](./../../README.md#mlm-asset-roles). + +| ML-Model Field | MLM Field | Migration Details | +|------------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `ml-model:inference-runtime` | `mlm:inference-runtime` | Prefix change. | +| `ml-model:training-runtime` | `mlm:training-runtime` | Prefix change. | +| `ml-model:checkpoint` | `mlm:checkpoint` | Prefix change. Recommended addition of further `mlm` properties for [Model Asset](./../../README.md#model-asset) to describe the artifact. | + + + +> [!TIP] +> In the context of [ML-Model][ml-model], Assets providing [Inference/Training Runtimes][ml-model-runtimes] +> are strictly provided as [Docker Compose][docker-compose-file] definitions. While this is still permitted, +> the MLM extension offers alternatives using any relevant definition for the model, as long as it is properly +> identified by its applicable media-type. Additional recommendations and Asset property fields are provided +> under [MLM Assets Objects](./../../README.md#assets-objects) for specific cases. + + + +### Relation Types + +| ML-Model Field | MLM Field | Migration Details | +|-------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `ml-model:inferencing-image` | *n/a* | Deemed redundant with `mlm:inference-runtime` Asset Role. | +| `ml-model:training-image` | *n/a* | Deemed redundant with `mlm:training-runtime` Asset Role. | +| `ml-model:train-data`
`ml-model:test-data` | `derived_from` | Use one or more `derived_from` links (as many as needed with regard to data involved during the model creation. Linked data should employ `ml-aoi` as appropriate (see [ML-AOI Best Practices][mlm-ml-aoi]). | + +[mlm-acc-type]: ./../../README.md#accelerator-type-enum + +[mlm-asset-model]: ./../../README.md#model-asset + +[mlm-asset-container]: ./../../README.md#container-asset + +[mlm-asset-code]: ./../../README.md#source-code-asset + +[mlm-inputs]: ./../../README.md#model-input-object + +[mlm-outputs]: ./../../README.md#model-output-object + +[mlm-hyperparam]: ./../../README.md#model-hyperparameters-object + +[mlm-stac-model]: https://pypi.org/project/stac-model/ + +[mlm-form]: https://mlm-form.vercel.app/ + +[mlm-spec]: ./../../README.md + +[mlm-bp]: ./../../best-practices.md + +[mlm-ml-aoi]: ./../../best-practices.md#ml-aoi-and-label-extensions + +[ml-model]: https://github.com/stac-extensions/ml-model + +[ml-model-runtimes]: https://github.com/stac-extensions/ml-model/blob/main/README.md#inferencetraining-runtimes + +[pydantic]: https://docs.pydantic.dev/latest/ + +[pystac-mlm]: https://github.com/stac-utils/pystac/blob/main/pystac/extensions/mlm.py + +[docker-compose-file]: https://github.com/compose-spec/compose-spec/blob/master/spec.md#compose-file