Pretrained models, sizes and downloads

Hosted pretrained models

Pass a model name wherever Mayaku takes weights (train(weights=...), from_pretrained(...), mayaku predict, mayaku eval, mayaku export). The checkpoint downloads the first time it is used.

The pattern is mayaku-<size>-<task>. To see what is currently hosted:

mayaku download --list

No oriented-box or classification models are hosted. Train those from the detector weights of the size you want: oriented boxes, classification.

Sizes

All four sizes share one architecture and differ in width and depth. Larger is more accurate and slower.

Figures are for a detection model with 80 classes in its exported form. A mask or keypoint branch adds about 0.1 to 0.4 M parameters and 1 to 1.4 GMACs. The class count changes the parameter count slightly. Compute grows with the canvas: a 576×1024 canvas costs about 1.44 times what 640×640 costs.

How to choose:

• Start with nano to check your data and pipeline. It trains fastest and runs in real time on CPUs and edge devices.
• Move up a size when accuracy matters more than speed, especially for small objects and many classes.
• Changing the canvas (--size-budget) is the other speed and accuracy dial, and it does not need a different pretrained model.

The architecture:

• A convolutional backbone, a three-level feature pyramid at strides 8, 16 and 32, and an anchor-free detection head that predicts each box side as a distribution (DFL).
• Masks, keypoints and oriented boxes are extra branches on the same detector.
• Overlapping detections are removed by NMS in post-processing, not inside the network.
• The deployed network uses only 1×1 and 3×3 convolutions, ReLU, addition, nearest upsampling and max-pooling (see Export).

Downloads

Where files go

A hosted model downloads to <name>.pth in the current working directory, for example ./mayaku-n-det.pth. Set the environment variable MAYAKU_CACHE_DIR to download to a fixed directory instead, which is useful for shared machines, CI and containers:

export MAYAKU_CACHE_DIR=~/.cache/mayaku

• A file already present is used as is. No network access, no update check, no re-verification. This makes later runs fast and offline.
• Models never update automatically. Delete the .pth file to get the latest revision on the next use.
• Every download is checked against the size and SHA256 listed in the hosted manifest. A partial or corrupt download is deleted and raises DownloadError.

How a weights argument is resolved

For a weights value:

1. If a file exists at that path, it is used. This includes mayaku-n-det.pth already in the download directory.
2. Otherwise, if the value contains a / or \, it was meant as a path, and Mayaku raises FileNotFoundError: weights file not found: ....
3. Otherwise it is treated as a model name and downloaded. A trailing .pth is ignored, so mayaku-n-det and mayaku-n-det.pth are the same name.

The download command

mayaku download mayaku-m-det                 # one model
mayaku download --list                       # list hosted models by task
mayaku download --all                        # every hosted model
mayaku download mayaku-m-det --cache-dir weights/

From Python

from pathlib import Path
from mayaku.utils.download import download_model, list_models, list_revisions

list_models()                          # {"detection": ["mayaku-l-det", ...], "segmentation": [...], ...}
list_revisions("mayaku-n-det")         # ["2026-07-02", ...], oldest first
path = download_model("mayaku-n-det")  # Path to the .pth
path = download_model("mayaku-n-det", revision="2026-07-02", cache_dir=Path("weights"))

cache_dir must be a pathlib.Path.

revision pins a dated snapshot. It only takes effect when the file isn't already present, because the local file name has no revision in it. Use a separate cache_dir per revision if you need several.

Offline machines and mirrors

Download on a connected machine, copy the .pth files, and pass their paths. A local file never touches the network. To serve your own mirror, host the files with a manifest.json in the same layout and point mayaku download --manifest-url at it.

Checkpoint compatibility

Checkpoints and exported files record the format version they were written with. Mayaku 3 reads only Mayaku 3 files. A model trained with Mayaku 2.x fails with:

<file> was trained with mayaku 2.x (sidecar schema 1); run it with `pip install 'mayaku<3'`

A file that wasn't written by Mayaku, or whose metadata was stripped, fails with <file> carries no mayaku sidecar.