qtum/Nex-N2.5-Pro-GGUF

Nex-N2.5-Pro GGUF

GGUF quantizations of nex-agi/Nex-N2.5-Pro, made with llama.cpp.

Chinese version: README_zh.md

397B total parameters, 60 layers in a hybrid layout: 45 Gated DeltaNet linear-attention layers and 15 full-attention layers (every fourth layer; GQA with 32 query / 2 KV heads, head dim 256). Each token is routed to 10 of 512 experts plus a shared expert. Partial RoPE (25 % of the head dim) with interleaved multimodal RoPE, 262,144-token context, 248,320-token vocabulary. A 27-layer vision encoder (768 px input, 16 px patches) ships here as a separate mmproj file.

Quantized from the official FP8 release, in which the routed experts are FP8 (E4M3, 128×128 blocks) and everything else is BF16. The FP8 experts are first dequantized exactly into a BF16 master; every tier is then quantized from that master with an importance matrix, and ships as 19 shards.

Quantizations

Tier	Size	Shards	BPW	PPL (wikitext-2)	Mean KLD	Same top-1
master (BF16, not in this repo)	738.5 GiB	19	16.01	3.6477 ± 0.0336	—	—
IQ4_XS	200.1 GiB	19	4.34	3.6779 ± 0.0340	0.0314 ± 0.0004	94.11 %
Q2_K	138.9 GiB	19	3.01	3.9210 ± 0.0369	0.1346 ± 0.0016	87.89 %
IQ2_XS	113.2 GiB	19	2.45	4.2645 ± 0.0405	0.2163 ± 0.0023	84.50 %
mmproj (vision, BF16)	0.86 GiB	1	—	—	—	—

The master row is not a file in this repo. It is listed so the numbers above have a reference point — the BF16 master was loaded and measured on the same machine, so every tier is compared against a real baseline rather than an estimate.

Pick IQ4_XS unless you cannot fit it. On identical text its perplexity is only 0.8 % above the BF16 master's, it keeps the master's top-1 token on 94 % of positions, and its KL divergence is 4.3× lower than the next tier down. Q2_K is the balanced choice and the best option for CPU-only inference. IQ2_XS exists for when the footprint is hard-capped — even there, the median token's KL divergence stays at 0.05.

What is protected

The routed experts are 97.5 % of this model's weights, so everything else can be kept at high precision cheaply — measured with --dry-run, it costs +3.0 / +4.1 / +4.8 GiB over the bare IQ4_XS / Q2_K / IQ2_XS tiers:

Tensors	Type	Reason
ffn_gate_inp / ffn_gate_inp_shexp	F32	MoE router (10 of 512) and the shared-expert gate
ffn_*_shexp	Q8_0	the shared expert runs on every token
ssm_a / ssm_dt / ssm_conv1d / ssm_norm / ssm_alpha / ssm_beta	F32	Gated DeltaNet recurrent state; low bit-width destroys long-range recall
ssm_out / attn_gate	Q8_0	linear-attention output projection and gate
attn_q / attn_k / attn_v / attn_output	Q8_0	the 15 full-attention layers
token_embd / output	Q6_K	248k-token vocabulary; a global type would otherwise squeeze these hard

One MTP (multi-token prediction) layer exists in the checkpoint but is excluded at conversion time via --no-mtp; these files carry the main model's tensors only.

Vision

The vision projector ships in BF16 and was checked end to end on the IQ4_XS weights with a synthetic test image (a red circle, a blue square and the text "QTUM 2026"): every shape, color and position was identified correctly, and the text was transcribed exactly.

Pass --image-min-tokens 1024. At llama.cpp's default budget a 768 px image is encoded into only 576 image tokens, which in our test was not enough to resolve fine print — the model read "QTUM" as "OTUM" — while with --image-min-tokens 1024 it read it correctly. llama.cpp itself warns that Qwen-VL-family models need at least 1024 image tokens. llama-mtmd-cli also needs --jinja to use the model's own chat template; it is off by default there.

Usage

# Text. Point at the first shard; llama.cpp finds the rest on its own.
# Sampling recommended by nex-agi: temperature 0.7, top-p 0.95, top-k 40.
llama-cli -m Nex-N2.5-Pro-IQ4_XS-00001-of-00019.gguf --temp 0.7 --top-p 0.95 --top-k 40

# Thinking is adaptive by default. Turn it off, or force it, through the chat template:
llama-cli -m Nex-N2.5-Pro-IQ4_XS-00001-of-00019.gguf --reasoning-effort none   # or: high

# Images: add the vision projector. --jinja is required here (off by default in llama-mtmd-cli).
llama-mtmd-cli -m Nex-N2.5-Pro-IQ4_XS-00001-of-00019.gguf \
  --mmproj mmproj-Nex-N2.5-Pro-BF16.gguf --jinja --image-min-tokens 1024 \
  --image photo.jpg -p "Describe this image."

Do not pass -ngl manually. llama.cpp fits layers to free VRAM by itself, and an explicit -ngl — including 0 — aborts that fitting and can fail to allocate compute buffers even when the weights would have fit.

Every tier ships as 19 shards. Download all 19 into one directory — you only ever name -00001-of-00019 on the command line. Requires a llama.cpp build with Qwen3.5-MoE (qwen35moe) support.

About the numbers

wikitext-2 test, n_ctx=512. Every figure in the table — the BF16 master's PPL included — is computed on the same 200 chunks of 512 tokens through the exact same command on 8× H100 80GB, so every row is compared on identical text. KL divergence and top-1 agreement are measured against logits saved from the BF16 master over those same chunks.

These numbers are only comparable within this table. Do not compare them against PPL figures published by other repos — different corpora and chunk counts make absolute values meaningless across setups.

Perplexity is a mean statistic that hides where a quantized model actually breaks, so KL divergence and top-1 agreement are reported alongside it.

License

Apache-2.0, inherited from nex-agi/Nex-N2.5-Pro — see the Apache License 2.0 for terms. Quantized by qtum.