GGUF-量化内幕-附录-A-公式速查

GGUF 量化内幕：附录 A 公式速查

本附录把全书涉及的量化格式汇成一表：每个格式给出反量化公式、尺度归一化约定、块字节数、bpw 计算、type id。所有 字节数、位序均以 llama.cpp 主线（2026-10）源码核实（见 asset/facts-verified.md），凡与细纲数字有出入处以本附录为准。

bpw 统一定义：每权重平均比特数（bit/weight）

[
\text{bpw} = \frac{\text{块字节数} \times 8}{\text{每块权重数}}
]

多出来的部分（参阅第 1 章）来自尺度、最小值、打包的元数据开销，不是纯粹的码位宽。

---

A.1 简单块（块共享单一尺度）

格式	type id	每块权重	块字节	bpw 计算	反量化公式	归一化/要点
Q1_0	41	128 (QK1_0)	18	18×8/128 = 1.125	(y_i = d\cdot(q_i-8))	1 bit/值，qs[16] 每字节 8 值
Q2_0	42	64 (QK2_0)	18	18×8/64 = 2.25	(y_i = d\cdot(q_i-8))	2 bit/值，qs[16] 每字节 4 值
Q4_0	2	32 (QK4_0)	18	18×8/32 = 4.5	(y_i = d\cdot(q_i-8))	q∈[0,15]，nibble 打包，减 8 免费（第 4 章）
Q4_1	3	32	20	20×8/32 = 5.0	(y_i = d\cdot q_i + m)	显式最小值 m
Q5_0	6	32	22	22×8/32 = 5.5	(y_i = d\cdot(q_i^{5}-16))	5-bit 码 = nibble + qh[] 高 1 位
Q5_1	7	32	24	24×8/32 = 6.0	(y_i = d\cdot(q_i^{5}-16)+m)	多一个最小值
Q8_0	8	32	34	34×8/32 = 8.5	(y_i = d\cdot q_i)	qs[32] 为 int8，无需减偏移
Q8_1	9	32	36	36×8/32 = 9.0	(y_i = d\cdot q_i)	额外存 s = d·Σqs 供点积用

A.2 K-quants（256 值超级块，两级尺度）

统一骨架：符号 j = 子块索引，s_j/m_j 为子块尺度/最小值（6-bit 整数），q_i 为低位量化码。

[
y_i = d\cdot s_j\cdot q_i - d_{\min}\cdot m_j
]

归一化约定（重要，核实自 ggml-quants.c）：解码端直接乘 6-bit 整数 s_j、m_j，不除以 63 或 64；归一化在量化端完成——y.d = max_scale/63、y.dmin = max_min/63（参考实现 quantize_row_q4_K_ref）。同一模式适用于 Q2_K/Q3_K/Q4_K/Q5_K（除法本质被折进 d/dmin）。

格式	type id	结构（按磁盘顺序）	块字节	bpw 计算	公式要点
Q2_K	10	scales[16] + qs[64] + dm(d+dmin)	84	84×8/256 = 2.625	16 子组×16 值；sc & 0xF→子尺度、sc>>4→子最小值；2-bit 码 4 个/字节
Q3_K	11	hmask[32] + qs[64] + scales[12] + d	110	110×8/256 = 3.4375	3-bit 码 = qs 低 2 位 + hmask 1 位；尺度过 scales[is]-32 得 int8
Q4_K	12	dm(4) + scales[12] + qs[128]	144	144×8/256 = 4.5	8 子块×32 值；6-bit s/m 交错在 scales[12]（get_scale_min_k4）；4-bit 码 nibble 打包
Q5_K	13	dm + scales[12] + qh[32] + qs[128]	176	176×8/256 = 5.5	= Q4_K + 独立高 1 位平面 qh[]，5-bit 码
Q6_K	14	ql[128] + qh[64] + scales[16](int8) + d	210	210×8/256 = 6.5625	16 子块×16 值；6-bit 码 = ql 低 4 位 + qh 高 2 位；(y_i=d\cdot \mathrm{scales}[j]\cdot(q_i-32))，无 dmin
Q8_K	15	d(f32) + qs[256](int8) + bsums[16](int16)	292	292×8/256 = 9.125	仅用于中间量化/点积，不是文件格式

4-bit 码的 nibble 打包规则（第 7 章详述）：每 64 值切一段，段内 qs[l] & 0xF 为前 32 值码、qs[l] >> 4 为后 32 值码。

Q4_K 的 6-bit 交错打包（scales[12]）：

• j<4：s_j = scales[j] & 63，m_j = scales[j+4] & 63
• j≥4：s_j = (scales[j+4] & 0xF) | ((scales[j-4] >> 6) << 4)，m_j = (scales[j+4] >> 4) | ((scales[j] >> 6) << 4)

A.3 IQ 系列（码本查表，重要压缩至极限位宽）

范式特征：反量化不是算术展开，而是用索引查表（grid/codebook），每个表项是一个小整数向量；另有符号位/符号表。

格式	type id	结构	块字节	bpw 计算	查表要点
IQ2_XXS	16	d + qs[32](uint16)	66	66×8/256 = 2.0625	每 8 值查 iq2xxs_grid，索引 8 bit
IQ2_XS	17	d + qs[32](uint16) + scales[8]	74	74×8/256 = 2.3125	索引 9 bit + 符号 7 bit；子组尺度半字节
IQ2_S	22	d + qs[64] + qh[8] + scales[8]	82	82×8/256 = 2.5625	索引 8+2 bit
IQ3_XXS	18	d + qs[96]	98	98×8/256 = 3.0625	注意：3.0625 而非细纲的 3.4375（那是 IQ3_S 的值）；每 8 值由两个 4 值表项拼成
IQ3_S	21	d + qs[64] + qh[8] + signs[32] + scales[4]	110	110×8/256 = 3.4375	每 4 值 1 表项 + 独立符号表
IQ1_S	19	d + qs[32] + qh[8](uint16)	50	50×8/256 = 1.5625	细纲写 74 字节/1.5 bpw 有误，主线为 50 字节/1.5625 bpw；32 值一组共享尺度
IQ1_M	29	qs[32] + qh[16] + scales[8]	56	56×8/256 = 1.75	无 d 字段，尺度藏在 scales（fp16 位模式重组）
IQ4_NL	20	d + qs[16]（QK4_NL=32）	18	18×8/32 = 4.5	4-bit 索引查非线性格点 kvalues_iq4nl[16]，布局同 Q4_0 等价位宽
IQ4_XS	23	d + scales_h(u16) + scales_l[4] + qs[128]	136	136×8/256 = 4.25	4-bit 非线性格点 + 细粒度尺度

关键常量：IQ1S_DELTA = IQ1M_DELTA = 0.125f；NGRID_IQ1S = 2048。

IQ1_S 解码（32 值一组）：

[
d_l = d\cdot\big(2\cdot((q_h\gg12)&7)+1\big),\qquad
y_j = d_l \cdot\big(\operatorname{grid}[,q_s[l]\ |\ ((q_h\gg3l)&7)\ll8,][j] + \delta\big)
]

其中 (\delta = \pm,\text{IQ1S_DELTA}) 由 qh 的 bit15 决定（& 0x8000）。

A.4 三值（权重 ∈ {−d, 0, +d}）

格式	主线状态	块尺寸	块字节	bpw 计算	编码要点
TQ1_0	✅ 已合入（type 34）	256	54	54×8/256 = 1.6875	base-3 打包：qs[48] 每字节 5 trits + qh[4] 每字节 4 trits
TQ2_0	✅ 已合入（type 35）	256	66	66×8/256 = 2.0625	每个权重独立 2-bit 三值（含 d）
STQ1_0	⚠ fork/PR	256	42（细纲口径）	42×8/256 = 1.3125	3:4 稀疏——每 4 权重恰 1 零，32 模式，5 bit/组（4-bit 码本索引 + 1-bit 符号）；stride-16 分组利于 SIMD
PTQ1_0	⚠ fork/PR	128	28（细纲口径）	28×8/128 = 1.75	稠密三值，base-3 编码（24 B × 5 trits/字节 + 2 B 余数）；Hadamard 折叠是必需变换，缺失则 logits 全错（第 13 章）

A.5 速查使用说明

1. bpw 统一自算：表内均给出「字节×8÷权重数」展开式，直接用即可；想验证某个格式，套公式比背数字可靠。
2. type id 对应主线（2026-10）：GGML_TYPE_* 枚举与表内一致；已移除类型（Q4_2、Q4_3、Q4_0_4_4 等）不在此表。
3. 归一化「除以多少」：解码侧无除法，是量化侧把 /63（或对 Q6_K 等的等价归一）折进 d/dmin 后存为 fp16。两种约定冲突的旧文档以主线 ggml-quants.c 为准。
4. 三值格式的 STQ1_0/PTQ1_0 字节数为细纲口径，因不在主线，落地前必须以实际 fork/PR 文档复核（第 13/15/20 章详述）。