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

• 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.

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:

Metric	Merged BF16	CUDA bnb4	MLX 8-bit	MLX 4-bit
Valid JSON	100.0%	96.7%	100.0%	100.0%
Correct response type	96.1%	92.6%	94.6%	98.4%
Exact schema	96.1%	92.1%	94.6%	55.8%
Exact route	94.8%	91.2%	93.4%	56.9%

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

Metric	Merged BF16	MLX 4-bit
Valid JSON	100.0%	100.0%
Schema valid	96.1%	55.8%
Route accuracy	94.8%	56.9%
Caption / answer F1	38.2%	35.1%
Spatial status	79.2%	77.3%
Precise target retained	50.2%	46.9%
Point within 100	33.4%	25.1%
Coarse direction exact	35.0%	27.6%
No-target discipline	93.4%	91.6%

Complete held-out validation

Metric	Merged BF16	MLX 4-bit
Valid JSON	99.9%	100.0%
Schema valid	99.9%	53.0%
Route accuracy	99.9%	53.2%
Caption / answer F1	38.6%	35.6%
Spatial status	86.1%	82.8%
Precise target retained	71.7%	68.8%
Point within 100	38.3%	27.8%
Coarse direction exact	34.4%	25.8%
No-target discipline	96.3%	95.5%

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

Metric	Merged BF16 - Strict cleaned test	MLX 4-bit - Strict cleaned test
Valid JSON	99.8%	100.0%
Schema valid	99.8%	62.8%
Route accuracy	99.8%	63.3%
Reference text F1	60.9%	57.2%
Spatial status	88.0%	83.8%
Coordinate quality	89.7%	86.1%
Precise target retained	65.2%	61.3%
Point within 100	42.6%	31.4%
No-target discipline	96.5%	93.4%

Coverage-matched evidence

Metric	Merged BF16 - Coverage-matched test	MLX 4-bit - Coverage-matched test
Valid JSON	99.9%	100.0%
Schema valid	99.9%	50.2%
Route accuracy	99.9%	50.5%
Reference text F1	64.3%	60.6%
Spatial status	84.2%	79.0%
Coordinate quality	84.9%	80.9%
Precise target retained	63.5%	59.7%
Point within 100	42.8%	31.4%
No-target discipline	96.4%	93.1%

Validation

Strict-cleaned evidence

Metric	Merged BF16 - Strict cleaned validation	MLX 4-bit - Strict cleaned validation
Valid JSON	99.9%	100.0%
Schema valid	99.9%	64.3%
Route accuracy	99.9%	64.6%
Reference text F1	59.9%	56.7%
Spatial status	89.6%	86.3%
Coordinate quality	89.8%	87.4%
Precise target retained	65.8%	62.9%
Point within 100	39.3%	28.6%
No-target discipline	96.7%	95.2%

Coverage-matched evidence

Metric	Merged BF16 - Coverage-matched validation	MLX 4-bit - Coverage-matched validation
Valid JSON	99.9%	100.0%
Schema valid	99.9%	53.0%
Route accuracy	99.9%	53.2%
Reference text F1	62.6%	59.5%
Spatial status	84.5%	80.7%
Coordinate quality	84.5%	81.7%
Precise target retained	60.5%	58.8%
Point within 100	38.4%	28.0%
No-target discipline	96.1%	94.1%

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.

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.