---
license: apache-2.0
base_model: MirilAI/Miril-DroneVLM-2B-2
library_name: transformers
pipeline_tag: image-text-to-text
language:
  - en
tags:
  - aerial-vlm
  - drone
  - vision-language-model
  - visual-grounding
  - bitsandbytes
  - int8
  - cuda
  - edge-ai
  - structured-output
  - miril
---

# Miril-DroneVLM-2B-2-bnb8

### The 8-bit CUDA edition of Miril-DroneVLM-2B-2

**Drones can talk.**

This repository contains the 8-bit bitsandbytes deployment variant of [Miril-DroneVLM-2B-2](https://huggingface.co/MirilAI/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, packaged for lower CUDA memory use. Behavior is defined by the primary model card. It covers the `caption`, `answer`, `location`, and `pointing` responses, exact system contract, coordinate semantics, 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](https://huggingface.co/MirilAI/Miril-DroneVLM-2B-2/blob/main/technical_report.pdf).

Interactive demo: [Miril-DroneVLM-2B-2-Demo](https://huggingface.co/spaces/MirilAI/Miril-DroneVLM-2B-2-Demo)

## Deployment Profile

<!-- MIRIL_VARIANT_PROFILE_START -->
- Artifact size: **7.37 GiB**
- Recommended starting envelope: **12.0 GiB free VRAM**
- 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 when you want lower CUDA memory use. Bit width does not imply
that this artifact is behaviorally closer to merged BF16 than the NF4 variant;
the complete same-case tables below are the release evidence. The deployment
profile also reports measured artifact size and a recommended free-VRAM envelope for
one-image inference.

The complete held-out audit shows a clear capability split: this artifact keeps
high JSON, schema, and route reliability, but loses substantial caption,
factual-answer, and coordinate-grounding quality relative to merged BF16. It is
therefore an evaluated compact option, not the recommended high-fidelity CUDA
checkpoint. Use the tables below and strict downstream validation; compare the
NF4 package separately instead of assuming 8-bit is better.

## Run It

```bash
hf download MirilAI/Miril-DroneVLM-2B-2 inference.py router_contract.py requirements.txt --local-dir miril-drone-runtime
python -m pip install -r miril-drone-runtime/requirements.txt
python miril-drone-runtime/inference.py \
  --model-id MirilAI/Miril-DroneVLM-2B-2-bnb8 \
  --image drone_frame.jpg \
  --prompt "Choose a place to lower this parcel."
```

The exported checkpoint carries its quantization configuration. The shared helper validates the model's bare JSON before any response is dispatched or drawn.

Use `transformers>=5.12.1`. This artifact retains Gemma 4 E2B's shared-KV layout: language layers 15 through 34 reuse key/value states and intentionally have no separate `k_proj`, `v_proj`, or `k_norm` tensors. The [artifact audit](./shared_kv_export_report.json) records the expected and observed tensor owners.

## Complete Benchmark

<!-- MIRIL_RELEASE_METRICS_START -->
![Deployment comparison](./assets/deployment_comparison.svg)

| Metric | Merged BF16 | CUDA bnb8 |
|---|---:|---:|
| Valid JSON | 100.0% | 99.1% |
| Schema valid | 96.1% | 93.6% |
| Route accuracy | 94.8% | 91.6% |
| Caption / answer F1 | 38.2% | 19.6% |
| Spatial status | 79.2% | 63.4% |
| Precise target retained | 50.2% | 42.4% |
| Point within 100 | 33.4% | 8.0% |
| Coarse direction exact | 35.0% | 9.3% |
| No-target discipline | 93.4% | 89.6% |

### Complete held-out validation

![Complete validation comparison](./assets/full_validation_comparison.svg)

| Metric | Merged BF16 | CUDA bnb8 |
|---|---:|---:|
| Valid JSON | 99.9% | 99.7% |
| Schema valid | 99.9% | 99.7% |
| Route accuracy | 99.9% | 99.6% |
| Caption / answer F1 | 38.6% | 23.0% |
| Spatial status | 86.1% | 70.1% |
| Precise target retained | 71.7% | 60.7% |
| Point within 100 | 38.3% | 9.2% |
| Coarse direction exact | 34.4% | 11.3% |
| No-target discipline | 96.3% | 93.3% |

### Cleaned held-out deployment audit

![Cleaned test comparison](./assets/cleaned_test_comparison.svg)

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 | CUDA bnb8 - Strict cleaned test |
|---|---:|---:|
| Valid JSON | 99.8% | 99.6% |
| Schema valid | 99.8% | 99.6% |
| Route accuracy | 99.8% | 99.5% |
| Reference text F1 | 60.9% | 47.4% |
| Spatial status | 88.0% | 76.7% |
| Coordinate quality | 89.7% | 84.0% |
| Precise target retained | 65.2% | 52.6% |
| Point within 100 | 42.6% | 9.4% |
| No-target discipline | 96.5% | 97.1% |

##### Coverage-matched evidence

| Metric | Merged BF16 - Coverage-matched test | CUDA bnb8 - Coverage-matched test |
|---|---:|---:|
| Valid JSON | 99.9% | 99.6% |
| Schema valid | 99.9% | 99.5% |
| Route accuracy | 99.9% | 99.5% |
| Reference text F1 | 64.3% | 50.3% |
| Spatial status | 84.2% | 64.1% |
| Coordinate quality | 84.9% | 77.6% |
| Precise target retained | 63.5% | 49.9% |
| Point within 100 | 42.8% | 7.8% |
| No-target discipline | 96.4% | 97.6% |

#### Validation

##### Strict-cleaned evidence

| Metric | Merged BF16 - Strict cleaned validation | CUDA bnb8 - Strict cleaned validation |
|---|---:|---:|
| Valid JSON | 99.9% | 99.6% |
| Schema valid | 99.9% | 99.5% |
| Route accuracy | 99.9% | 99.5% |
| Reference text F1 | 59.9% | 48.1% |
| Spatial status | 89.6% | 80.1% |
| Coordinate quality | 89.8% | 84.9% |
| Precise target retained | 65.8% | 55.7% |
| Point within 100 | 39.3% | 9.6% |
| No-target discipline | 96.7% | 97.2% |

##### Coverage-matched evidence

| Metric | Merged BF16 - Coverage-matched validation | CUDA bnb8 - Coverage-matched validation |
|---|---:|---:|
| Valid JSON | 99.9% | 99.6% |
| Schema valid | 99.9% | 99.5% |
| Route accuracy | 99.9% | 99.4% |
| Reference text F1 | 62.6% | 50.3% |
| Spatial status | 84.5% | 66.7% |
| Coordinate quality | 84.5% | 78.7% |
| Precise target retained | 60.5% | 49.7% |
| Point within 100 | 38.4% | 8.1% |
| No-target discipline | 96.1% | 97.4% |

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 merged and quantized 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](https://huggingface.co/MirilAI/Miril-DroneVLM-2B-2).

## License

Apache License 2.0. See `LICENSE` and `NOTICE`.