Skip to content

Commit d568f02

Browse files
fmigneaultfmigneault
committed
add ML-Model migration guide (relates to stac-extensions/ml-model#16)
1 parent 2e81485 commit d568f02

File tree

4 files changed

+90
-4
lines changed

4 files changed

+90
-4
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### Added
1111

12+
- Add [ML-Model Legacy](./docs/legacy/ml-model.md) document providing migration guidance
13+
from the deprecated [ML-Model](https://github.com/stac-extensions/ml-model) extension
14+
(relates to [stac-extensions/ml-model#16](https://github.com/stac-extensions/ml-model/pull/16)).
15+
- Move [DLM Legacy](./docs/legacy/dlm.md) document.
1216
- Add `embedding` as suggested dimension name
1317
(relates to [#77](https://github.com/stac-extensions/mlm/discussions/77)).
1418
- Add [`huggingface/safetensors`](https://github.com/huggingface/safetensors)

‎README.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,11 +82,12 @@ reusability and avoid metadata duplication whenever possible. A properly defined
8282
never have the Machine Learning Model Extension exclusively in `stac_extensions`.
8383

8484
For details about the earlier (legacy) version of the MLM Extension, formerly known as
85-
the *Deep Learning Model Extension* (DLM), please refer to the [DLM LEGACY](README_DLM_LEGACY.md) document.
85+
the *Deep Learning Model Extension* (DLM), please refer to the [DLM LEGACY](./docs/legacy/dlm.md) document.
8686
DLM was renamed to the current MLM Extension and refactored to form a cohesive definition across all machine
8787
learning approaches, regardless of whether the approach constitutes a deep neural network or other statistical approach.
8888
It also combines multiple definitions from the predecessor [ML-Model](https://github.com/stac-extensions/ml-model)
89-
extension to synthesize common use cases into a single reference for Machine Learning Models.
89+
extension to synthesize common use cases into a single reference for "*Machine Learning Models*". For migration
90+
details from `ml-model` to `mlm`, please refer to the [ML-Model Legacy](./docs/legacy/ml-model.md) document.
9091

9192
For more details about the [`stac-model`](./stac_model) Python package, which provides definitions of the MLM extension
9293
using both [`Pydantic`](https://docs.pydantic.dev/latest/) and [`PySTAC`](https://pystac.readthedocs.io/en/stable/)

‎README_DLM_LEGACY.md renamed to ‎docs/legacy/dlm.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
<!-- lint disable no-undefined-references -->
44

5-
> [!NOTE]
6-
> This is legacy documentation references of [Deep Learning Model extension](https://github.com/crim-ca/dlm-extension)
5+
> [!WARNING]
6+
> This is legacy documentation reference of [Deep Learning Model extension](https://github.com/crim-ca/dlm-extension)
77
> preceding the current Machine Learning Model (MLM) extension.
88
99
<!-- lint enable no-undefined-references -->

‎docs/legacy/ml-model.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# ML Model Extension Specification
2+
3+
<!-- lint disable no-undefined-references -->
4+
5+
> [!WARNING]
6+
> This is legacy documentation reference of [ML-Model](https://github.com/stac-extensions/ml-model)
7+
> preceding the current Machine Learning Model (MLM) extension.
8+
9+
<!-- lint enable no-undefined-references -->
10+
11+
## Migration Table
12+
13+
Following are the corresponding fields between the legacy DLM and the current MLM extension, which can be used to
14+
completely migrate to the newer MLM extension providing enhanced feature and interconnectivity with other STAC
15+
extensions (see also [Best Practices][mlm-bp]).
16+
17+
<!-- lint disable no-undefined-references -->
18+
19+
> [!NOTE]
20+
> Only the limited set of `ml-model` fields are listed below for migration guidelines.
21+
> See the full [MLM Specification](../README.md) for all additional fields provided to further describe models.
22+
23+
<!-- lint enable no-undefined-references -->
24+
25+
26+
### Item Properties
27+
28+
| ML-Model Field | MLM Field | Migration Details |
29+
|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
30+
| `ml-model:type` <br> (`"ml-model"` constant) | *n/a* | Including the MLM URI in `stac_extensions` is sufficient to indicate that the Item is a Model. |
31+
| `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. |
32+
| `ml-model:prediction_type` <br> (`string`) | `mlm:tasks` <br> (`[string]`) | ML-Model limited to a single task. MLM allows multiple. Use `["<original-mlm-task>"]` to migrate directly. |
33+
| `ml-model:architecture` | `mlm:architecture` | Direct mapping. |
34+
| `ml-model:training-processor-type` <br> `ml-model:training-os` | `mlm:framework` <br> `mlm:framework_version` <br> `mlm:accelerator` <br> `mlm:accelerator_constrained` <br> `mlm:accelerator_summary` <br> `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][acc-type]. |
35+
36+
37+
[acc-type]: ../README.md#accelerator-type-enum
38+
[mlm-bp]: ../best-practices.md
39+
40+
41+
### Asset Objects
42+
43+
#### Roles
44+
45+
All [ML-Model Asset Roles](https://github.com/stac-extensions/ml-model/blob/main/README.md#roles)
46+
are available with a prefix change with the same sematic meaning.
47+
48+
Further roles are also proposed in [MLM Asset Roles](../README.md#mlm-asset-roles).
49+
50+
| ML-Model Field | MLM Field | Migration Details |
51+
|------------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
52+
| `ml-model:inference-runtime` | `mlm:inference-runtime` | Prefix change. |
53+
| `ml-model:training-runtime` | `mlm:training-runtime` | Prefix change. |
54+
| `ml-model:checkpoint` | `mlm:checkpoint` | Prefix change. Recommended addition of further `mlm` properties for [Model Asset](../README.md#model-asset) to describe the artifact. |
55+
56+
57+
<!-- lint disable no-undefined-references -->
58+
59+
> [!NOTE]
60+
> In the context of ML-Model, Assets providing [Inference/Training Runtimes][ml-model-runtimes]
61+
> are strictly provided as [Docker Compose][docker-compose-file] definitions. While this is still permitted,
62+
> the MLM extension offers alternatives using any relevant definition for the model, as long as it is properly
63+
> identified by its applicable media-type. Additional recommendations and Asset property fields are provided
64+
> under [MLM Assets Objects](../README.md#assets-objects) for specific cases.
65+
66+
<!-- lint enable no-undefined-references -->
67+
68+
[ml-model-runtimes]: https://github.com/stac-extensions/ml-model/blob/main/README.md#inferencetraining-runtimes
69+
[docker-compose-file]: https://github.com/compose-spec/compose-spec/blob/master/spec.md#compose-file
70+
71+
72+
### Relation Types
73+
74+
75+
| ML-Model Field | MLM Field | Migration Details |
76+
|-------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
77+
| `ml-model:inferencing-image` | *n/a* | Deemed redundant with `mlm:inference-runtime` Asset Role. |
78+
| `ml-model:training-image` | *n/a* | Deemed redundant with `mlm:training-runtime` Asset Role. |
79+
| `ml-model:train-data` <br> `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]). |
80+
81+
[mlm-ml-aoi]: ../README.md#ml-aoi-and-label-extensions

0 commit comments

Comments
 (0)