Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,139 @@
+---
+license: apache-2.0
+base_model:
+  - Jackrong/Qwopus3.6-27B-Coder-MTP-GGUF
+  - Qwen/Qwen3.6-27B
+base_model_relation: quantized
+pipeline_tag: text-generation
+tags:
+  - gguf
+  - ik_llama.cpp
+  - ik_llama
+  - mtp
+  - speculative-decoding
+  - imatrix
+  - qwen35
+  - code
+  - quantized
+---
+
+# Qwopus3.6-27B-Coder — ik_llama.cpp MTP IQ-quants (GGUF)
+
+This repo contains **ik_llama.cpp-optimized IQ-series GGUF quantizations** (with importance matrix) of
+**Jackrong**'s excellent [Qwopus3.6-27B-Coder-MTP](https://huggingface.co/Jackrong/Qwopus3.6-27B-Coder-MTP-GGUF),
+built specifically to run fast on a **single RTX 3090** with **Multi-Token Prediction (MTP) speculative decoding**.
+
+The original repo ships generic llama.cpp K-quants (`Q4_K_S`, etc.). These are different: they use
+**ikawrakow's SOTA non-linear quant types** (`IQ4_K`, `IQ4_KS`, `IQ3_K`) which, on the same hardware,
+decode **~40% faster at sustained generation** than the generic `Q4_K_S` — at the same quality — because of
+ik_llama's optimized GEMV kernels. MTP draft heads are preserved, so self-speculative decoding works out of the box.
+
+> ⚠️ **These require [ik_llama.cpp](https://github.com/ikawrakow/ik_llama.cpp), not mainline llama.cpp.**
+> The `IQ*_K` quant types and the MTP path are ik_llama features. Mainline llama.cpp / LM Studio / Ollama
+> will **not** load these correctly.
+
+## Model lineage
+
+| Stage | Model | By |
+|---|---|---|
+| Base | [Qwen3.6-27B](https://huggingface.co/Qwen/Qwen3.6-27B) (dense, 27B) | Alibaba / Qwen |
+| Finetune | [Qwopus3.6-27B-Coder-MTP](https://huggingface.co/Jackrong/Qwopus3.6-27B-Coder-MTP-GGUF) (reasoning-distill + agentic coding, MTP heads) | Jackrong |
+| **This repo** | ik_llama.cpp IQ-quants + imatrix | community requant |
+
+## Quant files
+
+| File | Type | bpw | Size | PPL (wikitext-2)¹ | Best for |
+|---|---|---|---|---|---|
+| `Qwopus3.6-27B-Coder-MTP-IQ4_K.gguf`  | IQ4_K  | 4.50 | 14.4 GiB | **6.460** ±0.062 | Max quality |
+| `Qwopus3.6-27B-Coder-MTP-IQ4_KS.gguf` | IQ4_KS | 4.25 | 13.7 GiB | 6.477 ±0.062 | **Recommended** — same quality as IQ4_K, ~37% faster decode |
+| `Qwopus3.6-27B-Coder-MTP-IQ3_K.gguf`  | IQ3_K  | 3.43 | 11.1 GiB | 6.578 ±0.062 | Tight VRAM |
+| `qwopus-imatrix.dat` | — | — | 12 MB | — | importance matrix (for reproducing / making your own quants) |
+
+¹ Perplexity over 250 chunks of wikitext-2-raw `test` at `n_ctx=512`. IQ4_K and IQ4_KS are
+**statistically identical** (the gap is within the error bars); IQ4_KS is the recommended default since it
+decodes markedly faster for no measurable quality loss.
+
+## Benchmarks (single RTX 3090, ik_llama.cpp build `4574`)
+
+**Raw throughput** — `llama-bench`, `-ngl 99`, no speculative decoding:
+
+| Quant | pp512 (t/s) | tg128 (t/s) |
+|---|---|---|
+| IQ4_K  |  993 | 31.2 |
+| IQ4_KS | 1215 | 42.8 |
+| IQ3_K  | 1024 | 40.0 |
+
+**Real-world with MTP** — `llama-server`, IQ4_KS, MTP on (`--draft-max 2`), KV cache `q4_0`, 200K context,
+single slot (`-np 1`):
+
+| Workload | Prefill (t/s) | Decode (t/s) |
+|---|---|---|
+| Short Q&A | 52 | **75.8** |
+| 300-token gen | 231 | **59.9** |
+| 900-token gen | 276 | **57.2** |
+| 6021-token prompt | **802** | 74.0 |
+
+Measured during the 900-token run: **≈258 W** GPU power draw, **65 °C**, **21.2 GB** VRAM (at 200K context).
+For reference, the generic `Q4_K_S` of the same model on the same machine sustains ~41 t/s decode — these
+IQ quants are **~40% faster**.
+
+## How these were built
+
+Quantizing **down from the near-lossless Q8_0** (not from a 4-bit quant — that would compound rounding error),
+guided by an importance matrix:
+
+```bash
+# 1. Importance matrix — run the Q8_0 model over a calibration corpus (GPU)
+#    corpus: bartowski's calibration_datav3 (2481 lines); 129 chunks; ik_llama cu13-full image
+llama-imatrix -m Qwopus3.6-27B-Coder-MTP-Q8_0.gguf \
+  -f calibration_datav3.txt -o qwopus-imatrix.dat -ngl 99
+
+# 2. Quantize each target from Q8_0 with the imatrix (CPU; cpu-full image)
+#    --allow-requantize is required because the source is Q8_0 (safe: Q8 is ~lossless)
+for T in IQ4_K IQ4_KS IQ3_K; do
+  llama-quantize --allow-requantize --imatrix qwopus-imatrix.dat \
+    Qwopus3.6-27B-Coder-MTP-Q8_0.gguf Qwopus3.6-27B-Coder-MTP-$T.gguf $T
+done
+```
+
+- **Engine:** [ik_llama.cpp](https://github.com/ikawrakow/ik_llama.cpp), Docker images
+  `ghcr.io/ikawrakow/ik-llama-cpp:cu13-full` (imatrix/bench) and `:cpu-full` (quantize), build `4574`.
+- **Source:** Jackrong's `Q8_0` GGUF (MTP variant), so the MTP draft heads carry through.
+- **Calibration:** [bartowski's calibration_datav3](https://gist.github.com/bartowski1182/eb213dccb3571f863da82e99418f81e8).
+
+## Usage (ik_llama.cpp)
+
+Serving with an OpenAI-compatible API and MTP speculative decoding enabled:
+
+```bash
+llama-server \
+  --model Qwopus3.6-27B-Coder-MTP-IQ4_KS.gguf \
+  -ngl 99 --ctx-size 200000 -b 4096 -ub 1024 -np 1 \
+  -ctk q4_0 -ctv q4_0 -fa on \
+  -ngld 99 --multi-token-prediction --draft-max 2 --draft-p-min 0.0 \
+  --recurrent-ckpt-mode auto --merge-qkv \
+  --jinja --parallel-tool-calls \
+  --reasoning off --reasoning-format deepseek \
+  --temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.0 --repeat-penalty 1.0
+```
+
+Then point any OpenAI-compatible client at `http://localhost:8080/v1`. Tool/function calling is supported
+(`--jinja --parallel-tool-calls`). Reasoning is off by default; the source model also supports a thinking mode.
+
+Notes:
+- `--multi-token-prediction --draft-max 2` enables MTP self-speculation; `2` is optimal for this model
+  (higher draft depths gave no gain or crashed in testing).
+- Keep `-np 1` on a single card — extra parallel slots divide throughput and disable MTP.
+
+## Credits
+
+- **Qwen team / Alibaba** — [Qwen3.6-27B](https://huggingface.co/Qwen/Qwen3.6-27B) base model.
+- **Jackrong** — [Qwopus3.6-27B-Coder-MTP](https://huggingface.co/Jackrong/Qwopus3.6-27B-Coder-MTP-GGUF) finetune.
+- **ikawrakow** — [ik_llama.cpp](https://github.com/ikawrakow/ik_llama.cpp), the IQ quant types and MTP support.
+- **bartowski** — calibration dataset.
+
+## Disclaimer
+
+Experimental community requantization for local evaluation. Quality is provided **as-is** — perplexity was
+measured, but full coding/agentic benchmarks (HumanEval/SWE-bench/etc.) were **not** run for these specific
+quants. License is inherited from the base (Apache-2.0). These GGUFs require **ik_llama.cpp**.