Rewrite card: plain explanation, size-picker, KL explained

README.md

@@ -7,8 +7,8 @@ tags:
   - glm
   - glm-5.3
   - moe
-  - awq
   - w4a16
+  - awq
   - int4
   - compressed-tensors
   - reap
@@ -19,49 +19,46 @@ tags:
 > [!TIP]
 > **[Support this work →](https://donate.sybilsolutions.ai)** · [X](https://x.com/0xsero) · [GitHub](https://github.com/0xsero) · [REAP paper](https://arxiv.org/abs/2510.13999) · [Cerebras REAP](https://huggingface.co/collections/cerebras/cerebras-reap)
 
-# GLM-5.3-504B — REAP keep-168 (W4A16 / AWQ-INT4)
+# GLM-5.3-504B — REAP keep-168 (W4A16 / INT4)
 
-> A **34%-expert-pruned GLM-5.3** (168 / 256 routed experts per layer, ~504B params) in **INT4 W4A16**
-> (compressed-tensors, AWQ), built for **Hopper (4x H200)** serving in vLLM / SGLang.
+**GLM-5.3 with 34% of its experts removed, at INT4 — 328 GB, built to serve on 4× H200 (Hopper) in vLLM or SGLang.**
 
-Pruned directly on the [cyankiwi/GLM-5.3-AWQ-INT4](https://huggingface.co/cyankiwi/GLM-5.3-AWQ-INT4) checkpoint
-with a **domain-protective max-over-domain saliency criterion** (each expert scored by its largest share of
-any single domains routed mass, so every domains specialist experts survive). Whole experts are dropped,
-kept experts renumbered, and the routers + MTP layer sliced to match.
+## What this is
 
-| | |
-|---|---|
-| Base | [cyankiwi/GLM-5.3-AWQ-INT4](https://huggingface.co/cyankiwi/GLM-5.3-AWQ-INT4) (compressed-tensors INT4 / AWQ) |
-| Prune | REAP, keep-168/256 (max-over-domain routed-mass saliency), all 75 MoE layers + MTP |
-| Format | INT4 W4A16, compressed-tensors (Marlin MoE kernel in vLLM) |
-| KL vs BF16 | **0.506 nats** (95% CI 0.403-0.607; 25-window full-vocabulary panel vs GLM-5.3-BF16) |
+GLM-5.3 is a 753B mixture-of-experts model: each token uses 8 of 256 expert sub-networks per layer (~40B active). **REAP** (Router-weighted Expert Activation Pruning) scores each expert’s real contribution and deletes the least useful ones — no retraining. This cut keeps **168 of 256** experts per layer.
 
-Criterion and fidelity: [`0xSero/glm-5.3-reap-fidelity-study`](https://huggingface.co/datasets/0xSero/glm-5.3-reap-fidelity-study).
-This is the Hopper-servable sibling of [`GLM-5.3-504B-EXL3-3.0bpw`](https://huggingface.co/0xSero/GLM-5.3-504B-EXL3-3.0bpw).
+The experts are then INT4 **W4A16** (compressed-tensors, AWQ), taken from the [cyankiwi/GLM-5.3-AWQ-INT4](https://huggingface.co/cyankiwi/GLM-5.3-AWQ-INT4) base. Only the routed experts are 4-bit; attention, the shared expert, the dense layers, and the head stay BF16. vLLM auto-selects the Marlin MoE kernel.
 
-## Serving (vLLM, 4x H200)
+## Which one, and what about Blackwell?
 
-```bash
-vllm serve 0xSero/GLM-5.3-504B-W4A16 --tensor-parallel-size 4 --trust-remote-code --max-model-len 131072
-```
+| Variant | Experts kept | Size | KL vs BF16 |
+|---|---|---|---|
+| **504B** (this) | 168 / 256 | 328 GB | 0.506 |
+| [569B](https://huggingface.co/0xSero/GLM-5.3-569B-W4A16) | 192 / 256 | 372 GB | 0.357 |
+
+This W4A16 build is the **Hopper-servable** sibling of the EXL3 series. On Blackwell or consumer GPUs use the EXL3 equivalent instead — [`GLM-5.3-500B-EXL3-3.0bpw`](https://huggingface.co/0xSero/GLM-5.3-500B-EXL3-3.0bpw), which measures the same fidelity (0.511).
 
-## Acknowledgements
+## How close to the original is it?
 
-- **[Z.AI / zai-org](https://huggingface.co/zai-org)** for [GLM-5.3](https://huggingface.co/zai-org/GLM-5.3), the base model.
-- **[cyankiwi](https://huggingface.co/cyankiwi)** for the [GLM-5.3-AWQ-INT4](https://huggingface.co/cyankiwi/GLM-5.3-AWQ-INT4) W4A16 base quantization this prune is built on.
-- **[Cerebras Research](https://github.com/CerebrasResearch/reap)** for REAP (Router-weighted Expert Activation Pruning) — [arXiv:2510.13999](https://arxiv.org/abs/2510.13999).
+**KL divergence vs full BF16: 0.506 nats** (sealed 25-prompt panel, full 154k vocabulary). KL is the standard “how differently do these two models predict” score — **0 = identical**, lower = closer. Notably this is essentially the same as the EXL3 cut at the same expert count (0.511): **the pruning drives the fidelity, the quant format barely moves it.** Full numbers: [fidelity study](https://huggingface.co/datasets/0xSero/glm-5.3-reap-fidelity-study).
 
-Observations: [`0xSero/glm-5.3-reap-observations-v1`](https://huggingface.co/datasets/0xSero/glm-5.3-reap-observations-v1). Fidelity study: [`0xSero/glm-5.3-reap-fidelity-study`](https://huggingface.co/datasets/0xSero/glm-5.3-reap-fidelity-study). Pruning and evaluation ran on 8x NVIDIA RTX PRO 6000 Blackwell.
+## Why these experts
 
-## Citation
+Instead of keeping the globally most-frequent experts (which deletes a domain’s specialists), each expert is scored by its **largest share of any single domain’s routed work**, so every domain — code, rare languages, structured output — keeps its specialists. Head-to-head vs frequency pruning: [fidelity study](https://huggingface.co/datasets/0xSero/glm-5.3-reap-fidelity-study).
 
-```bibtex
-@misc{lasby2025reap,
-  title  = {{REAP the Experts: Why Pruning Prevails for One-Shot MoE Compression}},
-  author = {{Mike Lasby and Ivan Lazarevich and Nish Sinnadurai and Sean Lie and Yani Ioannou and Vithursan Thangarasa}},
-  year   = {{2025}}, eprint = {{2510.13999}}, archivePrefix = {{arXiv}}
-}
+## Serving (vLLM, 4× H200)
+
+```bash
+vllm serve 0xSero/GLM-5.3-504B-W4A16 --tensor-parallel-size 4 --trust-remote-code --max-model-len 131072
 ```
 
+## Credits
+
+- **[Z.AI / zai-org](https://huggingface.co/zai-org)** — [GLM-5.3](https://huggingface.co/zai-org/GLM-5.3), the base model.
+- **[cyankiwi](https://huggingface.co/cyankiwi)** — the [GLM-5.3-AWQ-INT4](https://huggingface.co/cyankiwi/GLM-5.3-AWQ-INT4) W4A16 base this prune is built on.
+- **[Cerebras Research](https://github.com/CerebrasResearch/reap)** — REAP ([arXiv:2510.13999](https://arxiv.org/abs/2510.13999)).
+
+Observations: [`glm-5.3-reap-observations-v1`](https://huggingface.co/datasets/0xSero/glm-5.3-reap-observations-v1) · Fidelity study: [`glm-5.3-reap-fidelity-study`](https://huggingface.co/datasets/0xSero/glm-5.3-reap-fidelity-study) · Built on 8× NVIDIA RTX PRO 6000 Blackwell.
+
 ## License
-Inherited from the base model — see the [GLM-5.3 model card](https://huggingface.co/zai-org/GLM-5.3).
+Inherits the [GLM-5.3 license](https://huggingface.co/zai-org/GLM-5.3).