Miril-DroneVLM-2B-2-MLX-4bit

Miril-DroneVLM-2B-2-MLX-4bit

The compact Apple Silicon edition of Miril-DroneVLM-2B-2

Drones can talk.

This repository contains the 4-bit MLX-VLM deployment variant of Miril-DroneVLM-2B-2, Miril.ai's open-weight aerial VLM. Give it an overhead image and an ordinary question such as “What am I looking at?”, “Any people?”, “Choose a place for this parcel,” or “Track the white car.” It returns typed JSON that identifies how the answer should be interpreted.

This is the same four-route model interface as the merged checkpoint, converted for compact Apple Silicon experiments. See the primary model card for the caption, answer, location, and pointing responses, fixed system contract, precise-point and coarse-direction rules, runnable validation code, WALDO lineage, limitations, and safety requirements.

Methods and citation: Miril-DroneVLM-2B-2: Turning Aerial Detector Labels into a Structured Vision-Language Interface.

Deployment Profile

<!-- MIRIL_VARIANT_PROFILE_START -->

• Artifact size: 3.34 GiB
• Recommended starting envelope: 6.0 GiB free unified memory
• Estimate covers model weights plus practical single-image runtime headroom; larger images, batching, long generations, and server overhead need more.

<!-- MIRIL_VARIANT_PROFILE_END -->

Use this variant for compact local experiments on Apple Silicon. The deployment profile reports measured artifact size, a recommended unified-memory envelope, and full same-case quality deltas against the merged model.

Known 4-bit Contract Degradation

This artifact is published because it is compact and still produces useful aerial descriptions, answers, spatial statuses, and coordinates. It is not contract-equivalent to the merged or MLX 8-bit checkpoint.

On the complete balanced independent route benchmark:

The failure is narrow but important. In 96.6% of pointing cases, the MLX 4-bit model emitted the location key intent where the pointing schema requires action. It often preserved the requested value (locate, point, or track), the caption, status, and coordinates, but a strict parser must reject the object because the envelope is wrong. Only 0.1% of pointing responses emitted a strictly route-correct action field in this benchmark.

Do not silently treat intent as action in a flight or safety workflow. Use the bundled strict validator, reject malformed envelopes, and prefer the MLX 8-bit or merged model when deterministic route conformance matters.

Our current explanation is a measured hypothesis, not a proven causal result. The uniform affine 4-bit MLX conversion quantizes token embeddings as well as linear layers; the evaluated artifact contains quantized embed_tokens weights. MLX documents that its default quantizer covers both Linear and Embedding. The current MLX-VLM mixed_4_8 recipe keeps token embeddings, the language-model head, and selected projections at 8-bit. The fact that MLX 8-bit and CUDA 4-bit do not show the same collapse makes those sensitive layers the leading explanation, but it does not isolate one layer or rule out runtime-specific effects.

Generation three will test mixed_4_8 against the same cases, add layer-sensitivity ablations, and require action-key, route, and schema recovery before a mixed-bit artifact is called contract-preserving.

Run It

python -m pip install mlx-vlm huggingface_hub pillow
hf download MirilAI/Miril-DroneVLM-2B-2 mlx_inference.py inference.py router_contract.py --local-dir miril-drone-runtime
python miril-drone-runtime/mlx_inference.py \
  --model-id MirilAI/Miril-DroneVLM-2B-2-MLX-4bit \
  --image drone_frame.jpg \
  --prompt "Where is the white car?"

The helper applies the same fixed system prompt and strict response validator as the CUDA path. Invalid or contradictory coordinates are never returned as dispatch-safe points.

Export Integrity

Gemma 4 E2B uses shared key/value layers. The included shared-KV export audit verifies the expected tensor-owner layout for this exact MLX artifact; the absence of separate k_proj, v_proj, and k_norm tensors on sharing layers is intentional.

Complete Benchmark

<!-- MIRIL_RELEASE_METRICS_START -->

Complete held-out validation

Cleaned held-out deployment audit

After training, a stricter held-out audit removed pointing rows whose targets fall below the model-visible size threshold, then ran every release artifact on the complete revised validation and test splits. Strict-cleaned rows use only accepted evidence. Coverage-matched rows add evidence-preserving questions on the same held-out images to restore the earlier route and pointing action/status mix; they do not recreate the earlier object-class histogram.

Final held-out test

Strict-cleaned evidence

Coverage-matched evidence

Validation

Strict-cleaned evidence

Coverage-matched evidence

Validation supports comparison and model selection; test is the final held-out report. These automated scores measure contract and reference agreement, not flight safety.

Spoken-query results on the primary model card apply to the merged BF16 checkpoint. This deployment variant has not inherited that claim without a separate matched audio evaluation.

The merged and deployment variants use identical cases within each evaluation. Automated scores are regression signals, not safety certification.

<!-- MIRIL_RELEASE_METRICS_END -->

The tables below compare MLX and CUDA artifacts on identical complete held-out validation and test cases. Partial runs are excluded. Automated scores are regression signals, not safety certification.

Limits And Safety

This is a research perception model, not a flight controller or certified safety system. Follow the complete limitations and operational guidance on the primary model card.

License

Apache License 2.0. See LICENSE and NOTICE.