Configuration reference

One configuration describes a model and how it is trained. It has five sections: model, input, train, dataloader and auto_config. Every run saves its full resolved configuration to train/config.yaml, and every checkpoint and exported file carries a copy.

Setting fields

Use any of these. They can be combined.

Bash

# command line: --set with the dotted path; the value is parsed as YAML
mayaku train --weights mayaku-n-det --set train.batch=32 --set train.aug.vflip=0.5 \
  --set input.canvas_hw=[640,640] \
  --annotations data/train/_annotations.coco.json --images data/train

Python

# Python: a nested mapping
from mayaku import train

train(weights="mayaku-n-det",
      overrides={"train": {"batch": 32, "aug": {"vflip": 0.5}}, "input": {"canvas_hw": [640, 640]}},
      train_annotations="data/train/_annotations.coco.json", train_images="data/train")

YAML

# a YAML file, passed as the first argument: mayaku train my_run.yaml ...
# list only the fields you change; everything else keeps its default
model:
  tier: s
train:
  batch: 32
  aug:
    vflip: 0.5

To combine a YAML file with extra settings in Python, pass both. overrides is applied on top of the file:

Python

from mayaku import train

train("my_run.yaml", weights="mayaku-s-det", overrides={"train": {"epochs": 50}},
      train_annotations="data/train/_annotations.coco.json", train_images="data/train")

config also accepts a mayaku.config.MayakuConfig object. Prefer overrides or a YAML file, though, because with an object, auto-config treats more fields as set than you might expect:

Every field you pass to the constructor counts as set. In train, every recipe field counts as set as soon as you pass any of them. So MayakuConfig(train={"batch": 32}) also fixes train.epochs at 125 and turns off the fine-tune schedule.
An object returned by merge_overrides counts every field as set. That includes input.canvas_hw: null, so the canvas becomes a plain square at the size budget instead of following your data's aspect ratio.
An object from load_yaml follows the first rule: the fields in the file count as set, plus the whole recipe if the file has a train section.

Passing the YAML path itself, rather than a loaded object, counts exactly the fields written in the file.

Rules:

Unknown fields are errors at every level. --set train.lerning_rate=0.01 fails instead of being ignored.
Values are validated. A wrong type, an out-of-range value, or a size that isn't a multiple of 32 fails before training starts.
A field you set is never changed by auto-config.
There is no YAML inheritance. To combine settings, merge them in Python with merge_overrides.
When resuming a run, the configuration comes from the saved state and can't be changed.

To see the full default configuration:

Python

from mayaku.config import MayakuConfig, to_yaml_string

print(to_yaml_string(MayakuConfig()))

model

Which network: the task, the size, and the heads.

Field	Default	Values	Meaning
`model.task`	`detect`	`detect`, `classify`	`classify` builds an image classifier on the backbone (see Classification). Every detection-family task, including segmentation, keypoints and oriented boxes, is `detect`.
`model.tier`	`n`	`n`, `s`, `m`, `l`	Model size. See Models. Must match the warm-start weights.
`model.num_classes`	`null`	integer > 0	`null` takes it from the training data. Setting it to a different count than the data is an error.
`model.seg`	`false`	bool	Adds the instance mask branch. See Segmentation.
`model.keypoints`	`null`	mapping	Adds the keypoint branch. See below and Keypoints.
`model.obb`	`false`	bool	Predicts oriented boxes. Can't be combined with `seg` or `keypoints`. See Oriented boxes.
`model.mask_stride`	`8`	`4`, `8`	Resolution of the mask features. `4` gives finer masks at more cost.
`model.aux_arm`	`box_tower`	`box_tower`, `tower`	Where the mask and keypoint branches read per-location features from: the detection head's box tower, or a separate small tower per level.
`model.qat`	`true`	bool	Quantization-aware training, so the model can export to int8. See Export.
`model.qat_activations`	`symmetric`	`symmetric`, `affine`	The int8 activation scheme trained for. `symmetric` runs on every int8 runtime, TensorRT included. `affine` uses the int8 range more fully but can't run on TensorRT.

model.keypoints

Field	Default	Meaning
`model.keypoints.num`	required	Keypoints per object (`K`).
`model.keypoints.names`	`[]`	`K` names. Filled from the dataset's categories by auto-config.
`model.keypoints.flip_pairs`	`[]`	Index pairs swapped by a horizontal flip. Derived from `left_` / `right_` names by auto-config.

--set model.keypoints.num=17 is enough to turn the branch on. Names and pairs come from the data.

input

The canvas: the fixed input size every image is letterboxed onto, for training, evaluation, export and deployment.

Field	Default	Meaning
`input.size_budget`	`800`	The canvas has at most `size_budget²` pixels. Must be a multiple of 32. The command-line shortcut is `--size-budget`. For classifiers the default is 224.
`input.canvas_hw`	`null`	The canvas `[height, width]`. `null` lets auto-config pick the shape that fits your data's aspect ratio under the budget. Set it to fix the canvas exactly. Both sides must be multiples of 32.

See Training: input size.

train

The training recipe. The defaults are the tuned recipe. Fine-tuning runs change a few of them through auto-config.

Schedule and optimizer

Field	Default	Meaning
`train.epochs`	`125`	Passes over the training set. Auto-config sets `100` when fine-tuning. Shortcut: `--epochs`.
`train.batch`	`16`	Images per step across all GPUs. Must divide by the GPU count.
`train.optimizer`	`sgd`	`sgd` (Nesterov), `adamw`, or `musgd` (SGD mixed with an orthogonalized Muon step on hidden convolutions).
`train.lr`	`0.01`	Peak learning rate.
`train.lr_final_frac`	`0.01`	The final learning rate as a fraction of `lr`, reached by a cosine schedule.
`train.lr_ref_batch`	`64`	Gradients are accumulated over about this many images per optimizer step, whatever `batch` is, so `lr` doesn't depend on `batch`. Weight decay is scaled to match.
`train.momentum`	`0.937`	SGD and MuSGD momentum.
`train.beta1`	`0.9`	AdamW beta1.
`train.muon_mix`	`0.5`	MuSGD only: the share of each hidden-convolution step taken along the orthogonalized direction. `0` is plain SGD.
`train.weight_decay`	`0.0005`	Applied to weights only, not to normalization layers or biases.
`train.warmup_epochs`	`3.0`	Learning-rate warmup length in epochs.
`train.warmup_iters_min`	`100`	Minimum warmup steps, so tiny datasets still warm up.
`train.warmup_momentum_start`	`0.8`	Momentum at the start of warmup.
`train.warmup_bias_lr_start`	`0.1`	Bias learning rate at the start of warmup. It ramps down to `lr`.
`train.seed`	`0`	Random seed.
`train.amp`	`true`	Mixed-precision training. Applies on CUDA only.
`train.sync_bn`	`true`	Multi-GPU only: BatchNorm statistics over the whole batch rather than each GPU's share.

Final stage, EMA and checkpoint quality

Field	Default	Meaning
`train.final_frac`	`0.16`	Share of epochs, at the end, trained with `train.final_aug`: no mosaic or geometric jitter. Auto-config sets `0.2` when fine-tuning.
`train.ema_decay`	`0.9999`	Decay of the exponential moving average of the weights. The EMA weights are what is evaluated and saved.
`train.ema_tau`	`2000.0`	Ramp of the EMA decay in steps, so the average is useful from the first steps.
`train.recalibrate_images`	`640`	Before each evaluation and checkpoint, BatchNorm statistics of the EMA model are recomputed over this many unaugmented training images. `0` turns it off.
`train.int8_check_images`	`500`	QAT only: each evaluation also scores this many validation images in simulated int8 and logs the gap to float. `0` turns it off.
`train.multiscale`	`0`	Multi-scale training: the smallest size budget to train at, `0` for off. Each batch is downscaled to a random size between this budget and the canvas. Evaluation always uses the canvas. It usually costs accuracy at the canvas size. Use it only if you will deploy smaller than you train.

Loss and label assignment

Field	Default	Meaning
`train.assigner_warmup`	`5`	Epochs of ATSS assignment before switching to task-aligned assignment (TAL). Auto-config sets `0` when fine-tuning.
`train.atss_soft`	`false`	Scale the ATSS class target by the best IoU.
`train.tal_beta`	`6.0`	The IoU exponent in TAL's alignment metric. Lower values let lower-IoU small objects rank.
`train.cls_loss`	`bce`	Classification loss: `bce` or `vfl` (varifocal).
`train.loc_weight_floor`	`0.0`	Minimum weight of the box and DFL loss per positive. `0` is off.
`train.seg_gain`	`2.0`	Weight of the mask (Dice) loss.
`train.seg_cap`	`250`	Maximum positives per batch for the mask loss.

train.aug

Augmentation during training. train.final_aug has the same fields and is used for the final stage.

Field	Default (`aug`)	Default (`final_aug`)	Meaning
`mosaic`	`1.0`	`0.0`	Probability of combining four images into one. Auto-config lowers it for small datasets when fine-tuning.
`mixup`	`0.0`	`0.0`	Probability of blending in a second image.
`scale`	`[0.5, 1.5]`	`[1.0, 1.0]`	Random scale range.
`translate`	`0.1`	`0.0`	Random shift, as a fraction of the canvas.
`hflip`	`0.5`	`0.5`	Horizontal flip probability.
`vflip`	`0.0`	`0.0`	Vertical flip probability, for images with no "up" (aerial, microscopy). Don't use it with keypoints.
`hsv`	`[0.015, 0.7, 0.4]`	`[0.015, 0.7, 0.4]`	Hue, saturation and value jitter strengths.

Classifiers use hflip, vflip and hsv, plus their own random crop, which is turned off when scale is [1.0, 1.0]. They don't use mosaic, mixup or translate.

Decode settings

Post-processing used during evaluation and saved into the checkpoint for prediction and export.

Field	Default	Meaning
`train.decode.conf`	`0.001`	Minimum score. Low, as COCO AP needs. You can override it on each prediction call with `conf=`.
`train.decode.iou`	`0.7`	NMS overlap threshold.
`train.decode.max_det`	`300`	Maximum detections per image.
`train.decode.topk`	`1000`	Candidates kept before NMS.
`train.decode.multi_label`	`true`	Allow one box to be reported under several classes.

See Prediction: the score threshold.

dataloader

Field	Default	Meaning
`dataloader.num_workers`	`8`	Image-loading worker processes. Lower it if you run short of CPU or RAM. `0` loads images in the main process.

auto_config

Field	Default	Meaning
`auto_config.enabled`	`true`	Fill unset fields from the training data. With `false`, only the class count and a square canvas at the size budget are filled.

See Training: auto-config.