11.1.2. Adding Models to ModelZoo
This page is a short reference for registering your own model in Tiny ML ModelZoo. The validated step-by-step walk-through, with a worked example and troubleshooting, is Bring Your Own Model (BYOM). The full reference is ADDING_NEW_MODELS.md in the repository.
Note
This page describes the permanent route, which edits the ModelZoo source and so needs the clone install
(clone tinyml-modelzoo and run pip install -e .). See
Clone Installation. You only change files in tinyml-modelzoo; nothing in ModelMaker or
TinyVerse has to change, because models are discovered automatically from tinyml_modelzoo.
To use a model without editing ModelZoo (any install), see Quick start: a custom model file below.
11.1.2.1. Quick start: a custom model file
Put the model class in your own Python file and point the config at it:
training:
model_name: MyModel # must equal the class name in the file
custom_model_path: /path/to/my_model.py # absolute path recommended
No registration is needed. There is no description,
__all__entry orenabled_models_listentry for such a model. ModelMaker builds a stub description from the path, and the full pipeline (training, ONNX export, compilation) runs.Two styles are detected automatically. A
GenericModelWithSpecsubclass is created withconfig=dict(variables=..., num_classes=..., input_features=..., dual_op=...). A plaintorch.nn.Moduleis created with the keyword argumentsvariables,num_classesandinput_features; give its__init__those parameters (and**kwargs), otherwise it is created with no arguments and a warning is raised.A
get_model(model_name)function in the file takes priority over looking up a class namedmodel_name.Output shape. The model must return
(batch, num_classes). Input is(batch, variables, input_features, 1).Errors.
training.custom_model_path does not exist or is not a file(wrong path) andBYOM: model '<name>' not found in '<file>'(class name differs frommodel_name).Requires a
tinyml-modelmakerrelease that supportscustom_model_path. With an older one the run stops withplease check if the given model_name is a supported one.Quantization. With
training.quantizationunset the run is float only. Usequantization: 2for a quantized, hardware-NPU compile on NPU devices.
The complete worked example, with both styles in full, is in Bring Your Own Model (BYOM).
11.1.2.2. The two names
A model has two different names. Mixing them up is the most common cause of “model not found” errors.
Name |
Where it is defined |
Where it is used |
|---|---|---|
Description name (for example |
Key of the model description dict in |
|
Class name (for example |
Python class in |
|
config.yaml: training.model_name --> model_descriptions/<task>.py: description[<name>] (in enabled_models_list)
`-- training.model_training_id --> models/<task>.py: class <name> (in __all__)
If no enabled description matches training.model_name, the run stops with
please check if the given model_name is a supported one: <name>.
11.1.2.3. Files per task type
Task type |
Model classes ( |
Descriptions ( |
|---|---|---|
Time series classification |
|
|
Time series regression |
|
|
Time series anomaly detection |
|
|
Time series forecasting |
|
|
Image, audio, radar classification |
|
no description files in 1.5.0 (see the repository reference) |
11.1.2.4. Writing the model class
Both styles work:
Spec-based: inherit from
GenericModelWithSpecand describe the network as an ordered dictionary of layers ingen_model_spec(). This is the style used by most ModelZoo models.Plain
torch.nn.Module: write the network directly in PyTorch.
Keep the constructor signature __init__(self, config, input_features=..., variables=..., num_classes=...). The
pipeline fills in these values from your dataset and feature extraction settings, so do not hard-code them. Time
series input reaches the model as (batch, variables, input_features, 1).
Add the class name to the __all__ list of the model file.
11.1.2.5. Writing the description
Add an entry to the descriptions dict, starting from template_model_description and overriding only what is
specific to your model. The important training fields are:
model_name: the description name, equal to the dict key.model_training_id: the class name, exactly as in the model file.target_devices: the devices the model can be compiled for.
Then append the description name to enabled_models_list at the bottom of the file. Check that the previous entry ends
with a comma; otherwise Python silently joins the two strings and the model is reported as unsupported.
11.1.2.6. Using the model
Copy an example config and set the model name:
training:
model_name: 'MY_CLS_2k_NPU'
Then run it as any other example (see Running Examples). For NPU devices, follow the design guidelines in NPU Configuration Guidelines for TI Neural Network Compiler and check the footprint early with Memory Estimation.
11.1.2.7. Next steps
Bring Your Own Model (BYOM) for the step-by-step guide
Compilation Only to compile a model that is already trained
Quantization for quantizing your model