README.md

---
license: apache-2.0
base_model:
  - Qwen/Qwen3.5-4B
base_model_relation: quantized
library_name: llama.cpp
pipeline_tag: text-generation
thumbnail: https://huggingface.co/TheStageAI/Qwen3.5-4B-GGUF/resolve/main/assets/thestage-edge-models-header.png
tags:
  - gguf
  - llama.cpp
  - quantized
  - mixed-precision
  - local-inference
  - qwen3.5
---

<p align="center">
  <img src="./assets/thestage-edge-models-header.png" width="100%" alt="TheStageAI Edge Models — the right model at every memory budget">
</p>

<h1 align="center">Qwen3.5 4B — TheStageAI GGUF</h1>

<p align="center">
  Four GGUF deployment points for llama.cpp · 1.52 GB–4.49 GB
  <br>
  <strong>Recommended: M · 2.39 GB · 98% of BF16 IFEval</strong>
</p>

<div style="display: flex; gap: 8px; justify-content: center; align-items: center; margin: 16px 0;">
  <a href="https://github.com/TheStageAI/edge-lm"><img src="./assets/cta-edge-lm.svg" width="104" height="36" alt="Explore edge-lm on GitHub"></a>
  <a href="https://docs.thestage.ai/"><img src="./assets/cta-docs.svg" width="83" height="36" alt="Read TheStageAI documentation"></a>
  <a href="https://app.thestage.ai/"><img src="./assets/cta-platform.svg" width="110" height="36" alt="Open TheStageAI Platform"></a>
</div>

<p align="center"><strong>Qwen 3.5 family:</strong> <a href="https://huggingface.co/TheStageAI/Qwen3.5-0.8B-GGUF">0.8B</a> &nbsp;·&nbsp; <a href="https://huggingface.co/TheStageAI/Qwen3.5-2B-GGUF">2B</a> &nbsp;·&nbsp; <strong><a href="https://huggingface.co/TheStageAI/Qwen3.5-4B-GGUF">4B</a></strong> &nbsp;·&nbsp; <a href="https://huggingface.co/TheStageAI/Qwen3.5-9B-GGUF">9B</a></p>

## Start here

| Tier | Size | Best for | File |
| --- | ---: | --- | --- |
| XS | 1.52 GB | Minimum footprint | [Download](./Qwen3.5-4B-XS-TS-Q3_K_S.gguf) |
| S | 1.90 GB | Compact | [Download](./Qwen3.5-4B-S-TS-Q4_K_S.gguf) |
| **M** | **2.39 GB** | **Recommended · Balanced** | [Download](./Qwen3.5-4B-M-TS-Q4_K_M.gguf) |
| L | 4.49 GB | Maximum fidelity | [Download](./Qwen3.5-4B-L-TS-Q8_0.gguf) |

Exact byte counts, SHA-256 hashes, and tensor metadata: [`release-manifest.json`](./release-manifest.json).

## Run with llama.cpp

```bash
llama-cli \
  --hf-repo TheStageAI/Qwen3.5-4B-GGUF \
  --hf-file Qwen3.5-4B-M-TS-Q4_K_M.gguf
```

## Quality

| Tier | IFEval strict — prompt / instruction (%) | MMLU-Pro (%) |
| --- | ---: | ---: |
| BF16 reference | 82.44 / 87.53 | 79.55 |
| XS | 70.43 / 78.30 | — |
| S | 77.82 / 83.93 | 74.39 |
| **M** | 80.22 / 86.09 | 78.86 |
| L | 81.70 / 87.05 | 79.59 |

**Modes.** IFEval uses 541 deterministic non-thinking prompts. MMLU-Pro covers 12,032 questions with sampled long reasoning. Only complete MMLU-Pro runs are shown; `—` means not reported.

> **XS and reasoning:** use S, M, or L for long-form reasoning. Run Qwen XS with `--reasoning off`.

<details>
<summary><b>Evaluation protocol</b></summary>

- **IFEval:** 541 prompts, native chat template, `enable_thinking=false`, temperature 0.
- **MMLU-Pro:** 12,032 questions, native chat template, `enable_thinking=true`, temperature 1, top-p 0.95, 32,768-token output limit.
- The headline BF16-retention percentage uses instruction-strict IFEval and is capped at 100%; the uncapped raw scores are shown in the table.

XS targets minimum footprint for non-thinking chat and instruction following. For long-form reasoning, use S, M, or L. Run Qwen XS with `--reasoning off`. In matched long-thinking diagnostics, XS produced longer trajectories and reached the 32,768-token output limit more often than S. The XS MMLU-Pro cell is consequently marked `—`.

</details>

## How the compression pipeline works

The adaptive tiers separate precision allocation from final weight reconstruction:

```text
Q2_K … Q8_0 PTQ lanes
        ↓
per-group candidate bank + native byte costs
        ↓
ANNA-DIAG-BYTES or RCO allocation
        ↓
fresh scheduled GPTQ / QuantEase + QEP
        ↓
scale/min distillation with codes frozen
```

### 1. Build native candidates

For every quantizable tensor group, TorsionQuant produces six native K-quant candidates. Each lane uses the same Hessian-aware GPTQ stack: **QuantEase** optimizes the blockwise weight codes, **QEP** propagates reconstruction error through the layer, and native K refinement keeps the solver aligned with the GGUF layouts that will actually ship.

- A **uniform bank** runs each Q2/Q3/Q4/Q5/Q6/Q8 lane independently.
- An **anchor bank** builds every candidate from activations propagated along one concrete quantized trajectory.

### 2. Allocate the byte budget

The scheduler sees the exact native GGUF cost of every `(tensor group, qtype)` choice, rather than a nominal average bit width.

- **ANNA-DIAG-BYTES** installs one candidate at a time in the BF16 model, measures full-vocabulary next-token KL against the teacher while every other group remains dense, and solves an exact multiple-choice knapsack over that isolated-loss table.
- **RCO** optimizes the choices jointly: projected-Gumbel search minimizes end-to-end teacher KL on the interpolated model under the byte constraint, then exact integer rounding produces the hard assignment.

| Adaptive tier | Bank / selector | Byte target |
| --- | --- | --- |
| XS | `RCO` · anchor bank | Compact model-specific cap |
| S | `RCO` · anchor bank | Exact size of a pinned `UD-Q2_K_XL` reference |

The S reference is used only as an external byte-budget authority.

### 3. Requantize and refine

The bank determines the qtype map; the release weights are regenerated from the original dense model in a **fresh full-model PTQ pass**. Activation propagation and error compensation therefore follow the final mixed-precision trajectory.

A short affine distillation pass then tunes only the native scales and minima against cached teacher logits. Qtypes, packed integer codes, dense weights, and tensor layouts remain frozen, so the size and runtime contract cannot drift. M and L use the same reconstruction and refinement path with fixed Q4_K and Q8_0 assignments.

Only after these stages is the final GGUF exported and measured on the untouched 3,072-sequence KL set and the downstream benchmarks above. The recommendation is based on those end-to-end results, not on the scheduler's calibration objective.

**Base model:** [`Qwen/Qwen3.5-4B`](https://huggingface.co/Qwen/Qwen3.5-4B) at revision [`851bf6e8`](https://huggingface.co/Qwen/Qwen3.5-4B/tree/851bf6e806efd8d0a36b00ddf55e13ccb7b8cd0a).

<details>
<summary><b>Technical file details</b></summary>

| Tier | Hub label | GGUF file type | Whole-file BPW |
| --- | --- | --- | ---: |
| XS | `Q3_K_S` | `MOSTLY_Q2_K` | 2.889 |
| S | `Q4_K_S` | `MOSTLY_Q2_K` | 3.622 |
| M | `Q4_K_M` | `MOSTLY_Q4_K_M` | 4.538 |
| L | `Q8_0` | `MOSTLY_Q8_0` | 8.533 |

For XS and S, the public Q-type suffix is an approximate Hub size label for discoverability; [`release-manifest.json`](./release-manifest.json) is authoritative for tensor types. M and L use fixed Q4_K and Q8_0 assignments for quantized decoder tensors.

Runtime memory also includes KV cache and buffers, which grow with context length.

</details>

## More from TheStageAI

These GGUFs provide a portable llama.cpp deployment path. For native compressed models on Apple Silicon, explore [edge-lm](https://github.com/TheStageAI/edge-lm). For custom compression, compilation, and deployment workflows, use the [TheStageAI Platform](https://app.thestage.ai/) and [documentation](https://docs.thestage.ai/).

**Have a device, latency, or memory target? [Talk to our team →](https://app.thestage.ai/contact)**

## Reproducibility

- **Manifest:** [`release-manifest.json`](./release-manifest.json) records the exact base revision, byte sizes, GGUF file types, whole-file BPW, tensor inventories, SHA-256 digests, held-out KL values, and evaluation IDs.
- **Runtime gate:** export and load checks used [llama.cpp revision `bec4772f`](https://github.com/ggml-org/llama.cpp/commit/bec4772f6a2527d371557b5d2032641e5ff7619c).

## License

The model weights are released under the upstream model's **Apache-2.0** license. llama.cpp and other runtime software retain their own licenses.