Mayaku

The computer vision library that learns your data fastest.

Mayaku trains detection, instance segmentation, and keypoint models on your own data. It's built around UniQuery — a query-based head — on a ConvNeXt backbone, and its base models are purpose-pretrained on Objects365 (365 classes) for fast fine-tuning, so they transfer to your classes quickly. Pure Python, zero custom CUDA kernels: one pip install mayaku trains on CUDA, Apple Silicon, ROCm, or CPU, and exports to ONNX, CoreML, OpenVINO, and TensorRT. Apache 2.0.

On RF100-VL — 100 real, custom datasets, not another COCO split — Mayaku's nano model reaches the highest mean AP of the three, and gets to the others' accuracy in a fraction of their training time.

Every AP below is COCO AP@[.50:.95], scored by pycocotools and averaged across datasets.

On speed, read the chart at equal accuracy. YOLO26n is quickest to finish — and finishes lowest. Mayaku passes yolo26n's final AP after 9.0 minutes of its own training, where yolo26n takes 19.1; it passes rfdetr-n's after 14.3 minutes, where rfdetr-n takes almost 2 hours.

Benchmark scope: nano tier, all 100 RF100-VL datasets, single RTX 3060. Each library runs its own default recipe to completion. No tuned hyperparameters and every checkpoint is scored by the same pycocotools evaluator on the same val split, so the AP numbers are identical in definition across libraries. The s/m/l tiers are still training and will be published as they finish, whatever they show.

Built for developers with a few hundred images of their own thing — retail shelves, defects on a line, insect wings — not another COCO leaderboard entry.

Highlights

• Fine-tunes fast. Highest mean AP on RF100-VL's 100 custom datasets, reaching the other libraries' accuracy in a fraction of their training time — see above. auto_config adapts the recipe (schedule, LR, augmentation) to your dataset size automatically.
• Objects365-pretrained. Base models are pretrained on a large, detection-native dataset (365 classes), a broad starting point for transfer.
• UniQuery head. Anchor-free, NMS-free, with image-conditioned query generation (QGN) and train-with-N / deploy-with-fewer refinement stages — a built-in speed/accuracy dial with no retraining. Detection and instance segmentation share one query representation; keypoints ride the same detector.
• Six sizes, three tasks. mayaku-n through mayaku-xxl, each in detection, instance-segmentation, and keypoint variants.
• Runs everywhere. Pure Python: no wheel chase, no ABI mismatches, no custom ops. CUDA / Apple Silicon (MPS) / ROCm / CPU from a single install.
• Deploys everywhere. Parity-tested exports to onnx, coreml, openvino, tensorrt.

Install

pip install mayaku

That covers training, inference, evaluation, and model download. Export targets are optional extras — install only what you need:

pip install mayaku[onnx]       # ONNX export
pip install mayaku[coreml]     # CoreML export (macOS)
pip install mayaku[openvino]   # OpenVINO export (Intel CPU/iGPU/NPU)
pip install mayaku[tensorrt]   # TensorRT export (CUDA Linux)

Quickstart

Fine-tune on your own dataset. Point at COCO-format splits — a train annotation JSON and its image directory; add a val split to get final eval. Pass a bundled model name as weights and it fetches the pretrained checkpoint on first use; the class-specific head re-initialises automatically when your class count differs.

from pathlib import Path

from mayaku import train

result = train(
    weights="mayaku-n-det",
    train_annotations=Path("data/train/_annotations.coco.json"),
    train_images=Path("data/train"),
    val_annotations=Path("data/valid/_annotations.coco.json"),
    val_images=Path("data/valid"),
)
print(result["final_box_ap"], result["final_weights"])

Same thing from the CLI:

mayaku train --weights mayaku-n-det \
  --annotations data/train/_annotations.coco.json --images data/train \
  --val-annotations data/valid/_annotations.coco.json --val-images data/valid

Predict:

from mayaku import from_pretrained

predictor = from_pretrained("mayaku-n-det")   # config + weights + device, auto
instances = predictor("photo.jpg")
print(instances.pred_boxes.tensor, instances.scores, instances.pred_classes)

mayaku predict mayaku-n-det photo.jpg --output result.json

Throughput

Measured on a single NVIDIA RTX 3060 — the most commonly owned GPU among Hugging Face users (HF hardware) — at 640px, TensorRT FP16, back-to-back with no cooldown pauses between timed inferences. CUDA numbers first; MPS and CPU figures will follow.

Two throughput numbers are reported: engine is the model forward pass alone, end-to-end is the full path you actually run (decode → preprocess → inference → post-process). The end-to-end number is the one that predicts your application's frame rate.

Model zoo

Base models are hosted and fetched on first use — pass a name instead of a path. Every size ships in three task variants, mayaku-<size>-{det,seg,key} (e.g. mayaku-m-seg).

List available names:

mayaku download --list

Machine-readable index: manifest.json (size + SHA256 per file). Cached under <project>/cache/mayaku/ (override with MAYAKU_CACHE_DIR).

Why Mayaku

Query-based, without DETR's slow convergence. UniQuery keeps the clean query-based design — no anchors, no NMS — but reaches its accuracy in a fraction of the training time DETR-style detectors need. An image-conditioned query generator (QGN) seeds queries from FPN features instead of learning them from scratch, so the model starts from meaningful proposals on epoch one. Train with N refinement stages, deploy with fewer — a speed/accuracy dial with no retraining.

Detection, segmentation, and keypoints from one family. Detection and instance segmentation are driven by a single shared query representation (the mask head is conditioned on the same per-object query features); keypoints run on the same detector. One architecture, one training path, three tasks.

Portability by design. No deformable conv, no custom CUDA/C++ ops, RGB-native end-to-end — the same code path runs on every backend and survives the trip through ONNX → CoreML / OpenVINO / TensorRT.

Deploy anywhere

mayaku export onnx     mayaku-n-det --output model.onnx
mayaku export coreml   mayaku-n-det --output model.mlpackage
mayaku export openvino mayaku-n-det --output model.xml      # .bin alongside
mayaku export tensorrt mayaku-n-det --output model.engine   # CUDA host

All four are parity-tested. On Intel CPU targets OpenVINO measurably beats PyTorch eager; on GPU targets the export artifact is the value.

Built on

UniQuery stands on a line of query-based detection work: Sparse R-CNN (iterative dynamic refinement), QueryInst (query-conditioned dynamic mask heads), Featurized Query R-CNN (image-conditioned query generation), and DN-DETR (denoising for stable early box regression). The backbone is ConvNeXt, with several sizes built on torchvision's implementation. What Mayaku adds is the unified head family, the Objects365 pretraining recipe, and the fine-tuning defaults that make them converge quickly on small datasets.

Roadmap

• Full RF100-VL results — the nano tier is complete above; s/m/l are training.
• Curated custom-class models — ready-to-use weights on a hand-picked set of common real-world classes (people, vehicles, and more), for projects that don't want to start from the Objects365 base.
• Documentation — a proper docs site, coming soon.

License

Apache 2.0 — see LICENSE. Applies to the full library and every published model weight.