Command-line reference

The mayaku command has five subcommands. python -m mayaku.cli is the same program.

Text only
mayaku train    [CONFIG] --images DIR [options]     train a model
mayaku eval     WEIGHTS --images DIR [options]      score a model on a labeled split
mayaku predict  WEIGHTS IMAGE [options]             run a model on one image, print JSON
mayaku export   TARGET WEIGHTS [options]            write a deployment file
mayaku download [NAME] [options]                    fetch hosted pretrained models

WEIGHTS is a checkpoint path, a hosted model name such as mayaku-n-det, or, for eval and predict, an exported file (.onnx, .mlpackage, .xml, .engine). Every subcommand takes --help.

mayaku train

Train a detector, segmentation, keypoint or oriented-box model on COCO data, or a classifier on class folders. The command-line form of mayaku.train.

Bash
mayaku train [CONFIG] [--weights W] --annotations A --images I
             [--val-annotations VA --val-images VI] [--output DIR]
             [--epochs N] [--size-budget S] [--set key=value ...]
             [--device D] [--num-gpus N] [--resume PATH]
Argument / option Meaning
CONFIG Optional YAML config. Without it, --weights defines the architecture, or the defaults apply.
--weights W Checkpoint path or hosted model name to start from.
--annotations A Training COCO JSON. Leave it out for a classifier.
--images I Required. Training image directory, or the class-folder root for a classifier.
--val-annotations VA Validation COCO JSON. Turns on per-epoch evaluation and best.pt.
--val-images VI Validation image directory, or class-folder root.
--output DIR Run directory. Default ./runs/<name>.
--epochs N Sets train.epochs.
--size-budget S Sets input.size_budget, a multiple of 32.
--set key=value Sets any config field by its dotted path. Repeatable. The value is parsed as YAML.
--device D auto (default), cuda, cuda:N, mps or cpu.
--num-gpus N Train on N GPUs of this machine. Default 1.
--resume PATH Continue a run from its state.pt or its train/ directory. Give the same dataset options. Don't combine with CONFIG, --weights, --epochs, --size-budget or --set.

When it finishes, it prints final weights: <path>.

Examples:

Bash
# fine-tune the small detector
mayaku train --weights mayaku-s-det \
  --annotations data/train/_annotations.coco.json --images data/train \
  --val-annotations data/valid/_annotations.coco.json --val-images data/valid

# segmentation from detector weights, 640 budget, batch 8
mayaku train --weights mayaku-n-det --set model.seg=true --size-budget 640 --set train.batch=8 \
  --annotations data/train/_annotations.coco.json --images data/train

# classifier
mayaku train --weights mayaku-n-det --set model.task=classify --epochs 30 \
  --images data/train --val-images data/val

mayaku eval

Score a model on a labeled split and print the metrics as JSON. The command-line form of mayaku.evaluate.

Bash
mayaku eval WEIGHTS [--annotations A] --images I [--output DIR] [--device D]
Argument / option Meaning
WEIGHTS Checkpoint, hosted model name or exported file.
--annotations A COCO JSON. Required for detectors. Leave it out for a classifier.
--images I Required. Image directory, or the class-folder root for a classifier.
--output DIR Also write DIR/metrics.json.
--device D auto (default), cuda, mps or cpu.

mayaku predict

Run a model on one image and print the result as JSON. See Prediction for the format.

Bash
mayaku predict WEIGHTS IMAGE [--conf C] [--output FILE] [--device D]
Argument / option Meaning
WEIGHTS Checkpoint, hosted model name or exported file.
IMAGE Image file.
--conf C Score threshold. Default: the model's recorded one, usually 0.001, which returns many low-score detections. Pass a value such as 0.25 for practical output.
--output FILE Write the JSON to a file instead of printing it.
--device D auto (default), cuda, mps or cpu.

mayaku export

Write a deployment file. The file's outputs are checked against the PyTorch model before the command succeeds. See Export and deployment.

Bash
mayaku export TARGET WEIGHTS [--output FILE] [--precision P]
Argument / option Meaning
TARGET onnx, coreml, openvino or tensorrt.
WEIGHTS Checkpoint or hosted model name. An exported file can't be exported again.
--output FILE Output path. Default: next to the checkpoint, with the target's extension (.onnx, .mlpackage, .xml, .engine).
--precision P fp32, fp16 or int8, as the target supports. Default: fp32 for ONNX and OpenVINO, fp16 for Core ML and TensorRT.

Prints the path written.

mayaku download

Fetch hosted pretrained checkpoints. See Models.

Bash
mayaku download [NAME] [--list] [--all] [--cache-dir DIR] [--manifest-url URL] [--no-verify]
Argument / option Meaning
NAME Model name, for example mayaku-m-seg.
--list List hosted models, grouped by task.
--all Download every hosted model.
--cache-dir DIR Download directory. Default: MAYAKU_CACHE_DIR, else the current directory.
--manifest-url URL Manifest of a mirror.
--no-verify Skip the SHA256 check of new downloads.

Prints <name>: <path> for each model. A model already in the download directory is not downloaded again.

Environment variables

Variable Effect
MAYAKU_CACHE_DIR Directory hosted models download to and are looked up in. Default: the current directory.
PYTORCH_ENABLE_MPS_FALLBACK Set to 1 by Mayaku on import, unless you set it yourself, so operations without an Apple GPU kernel fall back to the CPU.