Skip to content

quantize: add IQ2_NL and IQ3_NL types (CPU) - #27322

Open
EAddario wants to merge 29 commits into
ggml-org:masterfrom
EAddario:iq2_nl-iq3_nl-cpu
Open

quantize: add IQ2_NL and IQ3_NL types (CPU)#27322
EAddario wants to merge 29 commits into
ggml-org:masterfrom
EAddario:iq2_nl-iq3_nl-cpu

Conversation

@EAddario

@EAddario EAddario commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Overview

K-quants and I-quants operate on 256-element super-blocks. A tensor can use them only if its row length (ncols) is an exact multiple of 256. When it isn't, the quantizer falls back to a different (usually sub-optimal) 32-element block type per tensor.

Mainline 32-block types stop at 4.50 bpw (Q4_0/IQ4_NL) creating a hard floor on every misaligned tensor and therefore on the whole file wherever misaligned tensors dominate because there is nothing better to substitute to.

This PR introduces two new CPU-only types IQ2_NL (2.50 bpw) and IQ3_NL (3.50 bpw) extending the existing non-linear family downward. Being 32-block types, they apply wherever ncols % 32 == 0.

Additional information

Test models and results including PPL, KLD and inference benchmarks available at HuggingFace.

PR for CPU + Metal backend: #27324
PR for CPU + Metal + CUDA backend: #27325
PR for CPU + Metal + CUDA + Vulkan backend: #27983

Requirements

  • I have read and agree with the contributing guidelines
  • AI usage disclosure: YES. AI used to code review and to generate Metal and CUDA implementations.

@ggml-gh-bot

This comment was marked as resolved.

@CISC CISC left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like very reasonable quants to have, but who can/will review?

Comment thread ggml/src/ggml-sycl/ggml-sycl.cpp
Co-authored-by: Sigbjørn Skjæret <sigbjorn.skjaeret@huggingface.co>
@github-actions github-actions Bot added testing Everything test related examples ggml changes relating to the ggml tensor library for machine learning SYCL https://en.wikipedia.org/wiki/SYCL - GPU programming language Apple Metal https://en.wikipedia.org/wiki/Metal_(API) conversion labels Aug 18, 2026
@Green-Sky

Copy link
Copy Markdown
Collaborator

BTW we also have q2_0 with a group size of 64. A comparison might be neat.

@EAddario

Copy link
Copy Markdown
Contributor Author

At the risk of sounding like Claude, you are absolutely right @Green-Sky!
Forgot it got merged recently. I'll add to the test results

@EAddario

Copy link
Copy Markdown
Contributor Author

Not sure if there's something wrong on my side but like-for-like test results with Q2_0 are terrible:

====== Perplexity statistics ======
Mean PPL(Q)                   : 1791393.810329 ± 10600.941002
Mean PPL(base)                :   7.740272 ±   0.051484
Cor(ln(PPL(Q)), ln(PPL(base))):   3.64%
Mean ln(PPL(Q)/PPL(base))     :  12.352068 ±   0.008741
Mean PPL(Q)/PPL(base)         : 231438.093611 ± 2022.897691
Mean PPL(Q)-PPL(base)         : 1791386.070057 ± 10600.939130

====== KL divergence statistics ======
Mean    KLD:  12.589577 ±   0.005998
Maximum KLD:  24.119755
99.9%   KLD:  19.458214
99.0%   KLD:  17.880480
95.0%   KLD:  16.360634
90.0%   KLD:  15.541903
Median  KLD:  12.619534
10.0%   KLD:   9.645974
 5.0%   KLD:   8.658699
 1.0%   KLD:   6.787046
 0.1%   KLD:   5.274840
Minimum KLD:   2.753649

====== Token probability statistics ======
Mean    Δp: -45.117 ± 0.101 %
Maximum Δp:  0.061%
99.9%   Δp:  0.000%
99.0%   Δp: -0.001%
95.0%   Δp: -0.049%
90.0%   Δp: -0.327%
75.0%   Δp: -4.782%
Median  Δp: -36.710%
25.0%   Δp: -89.473%
10.0%   Δp: -99.357%
 5.0%   Δp: -99.839%
 1.0%   Δp: -99.975%
 0.1%   Δp: -99.996%
Minimum Δp: -100.000%
RMS Δp    : 59.791 ± 0.086 %
Same top p:  0.023 ± 0.004 %

Full logs and scores here

@EAddario

Copy link
Copy Markdown
Contributor Author

but who can/will review?

@CISC, if I got it right it will be either @JohannesGaessler or @ggerganov although there may be others I don't know about.

@ggerganov ggerganov self-assigned this Aug 20, 2026
@Green-Sky

Copy link
Copy Markdown
Collaborator

Not sure if there's something wrong on my side but like-for-like test results with Q2_0 are terrible:

The quantizer for q2_0 might not be very smart. The format is mostly for ternary trained models. (or quaternary since each weight can have 4 states).

@EAddario
EAddario requested a review from a team as a code owner August 31, 2026 22:23
@github-actions github-actions Bot added the CUDA Related to the CUDA backend label Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Apple Metal https://en.wikipedia.org/wiki/Metal_(API) conversion CUDA Related to the CUDA backend examples ggml changes relating to the ggml tensor library for machine learning SYCL https://en.wikipedia.org/wiki/SYCL - GPU programming language testing Everything test related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants