llama.cpp GGUF 量化：Q8_0 生成速度低于 Q4_K_M，以及 imatrix 与 --tensor-type 的用法

llama.cpp 的 tools/quantize 把一个 GGUF 输入模型（通常是 F32/BF16 等高精度格式）转换成量化格式。量化降低模型权重精度（例如 32 位浮点转到 4 位整数），缩小模型体积，并可能加快推理。代价是可能引入精度损失，通常用 Perplexity (ppl) 和/或 Kullback–Leibler Divergence (kld) 衡量。配上合适的 imatrix 文件可以把损失降到最低。

不想在本地搭环境，可以用 Hugging Face 上的 GGUF-my-repo space 构建自己的量化，它每 6 小时从 llama.cpp main 同步一次。

仓库：

量化分两个阶段

1. 把原始模型转成 GGUF 格式；
2. 量化转好的 GGUF 文件。

如果模型支持多模态输入（图像或音频），还要额外转换和量化多模态编码器与投影层。

Python 依赖：

python3 -m pip install -r requirements.txt
# 或者
uv pip install -r requirements.txt --index-strategy unsafe-best-match

准备输入 GGUF 文件

从 Hugging Face 仓库转换模型：

python convert_hf_to_gguf.py --outfile gemma-4-E2B-it-bf16.gguf --outtype bf16 --remote google/gemma-4-E2B-it

模型通常以 16 位分发，--outtype auto（或省略 --outtype）也适用。如果模型已经下载到本地，指定目录并去掉 --remote。为兼容性，Python requirements 会装 transformers 4，但越来越多模型（如 Gemma 4）需要 transformers 5，可以安全地 pip install -U transformers 装最新版。

量化 GGUF

拿到高质量 GGUF 之后，用 llama-quantize 应用量化。例如量化到 Q4_K_M：

./build/bin/llama-quantize gemma-4-E2B-it-bf16.gguf gemma-4-E2B-it-Q4_K_M.gguf Q4_K_M

主要选项：

• --allow-requantize：允许对已量化的张量再量化。警告：相比从 16bit/32bit 量化，这可能严重降低质量。
• --leave-output-tensor：让 output.weight 不（再）量化。会增大模型体积，但可能提升质量，尤其是再量化时。
• --pure：禁用 k-quant 混合，把所有张量量化到同一类型。
• --imatrix file_name：用 file_name 中的数据作为重要性矩阵做量化优化。
• --include-weights tensor_name：对该张量使用重要性矩阵，可多次指定。
• --exclude-weights tensor_name：对未指定的张量使用重要性矩阵。include/exclude 不能混用。
• --output-tensor-type：为 output.weight 指定量化类型。
• --token-embedding-type：为 token embeddings 指定量化类型。
• --keep-split：让量化产物保持与输入相同的分片，而不是生成单个量化文件。

高级选项：

• --tensor-type：把特定张量量化到特定量化类型。支持正则语法。可多次指定。
• --prune-layers：裁剪（移除）列表中的层。
• --override-kv：覆盖量化模型中的元数据键。可多次指定。

多模态组件要单独转、单独量化

llama.cpp 转换的是源模型的 LLM 部分，足够对话应用使用。如果模型接受多模态输入并且想用上，需要单独创建 GGUF 文件（mmproj，多媒体投影器），其中可能包含视觉或音频编码器加投影层。

多模态组件通常比 LLM 小得多，但它的质量直接影响 LLM 的生成质量，因为它负责准备输入。所以多模态组件一般保持 bf16 或 q8 这类高质量格式；用更小的量化对速度和内存的影响可以忽略，整体质量却可能受影响。

python convert_hf_to_gguf.py --mmproj --outfile mmproj-gemma-4-E2B-it-Q8_0.gguf --outtype q8_0 --remote google/gemma-4-E2B-it

运行量化模型

./build/bin/llama-cli -m ./gemma-4-E2B-it-Q4_K_M.gguf --mmproj ./mmproj-gemma-4-E2B-it-Q8_0.gguf --image  --prompt "Describe this image"

量化示例

# 朴素 Q4_K_M 量化，默认设置 8 个 CPU 线程，输出 ggml-model-Q4_K_M.gguf
./llama-quantize input-model-f32.gguf q4_k_m 8

# 启用再量化、保留 output tensor 不量化、其余统一 Q4_K
./llama-quantize --allow-requantize --leave-output-tensor --pure input-model-f32.gguf q4_k_m 8

# 仅对指定张量（attn_v 和 ffn_down）使用重要性矩阵
./llama-quantize --imatrix imatrix.gguf --include-weights attn_v --include-weights ffn_down input-model-f32.gguf q4_k_m 8

# output tensor 用 Q5_K_M、token embeddings 用 Q3_K_M，并保持输入分片
./llama-quantize --imatrix imatrix.gguf --output-tensor-type q5_k --token-embedding-type q3_k --keep-split input-model-f32.gguf q4_k_m 8

# 用正则：奇数层 attn_k 量化到 Q5_K_M，偶数层 attn_q 量化到 Q3_K_M
./llama-quantize --imatrix imatrix.gguf --tensor-type "\.(\d*[13579])\.attn_k=q5_k" --tensor-type "\.(\d*[02468])\.attn_q=q3_k" input-model-f32.gguf q4_k_m 8

# attn_v 和 ffn_down 设为 Q5_K_M，并裁剪 20,21,22 层
./llama-quantize --imatrix imatrix.gguf --tensor-type attn_v=q5_k --tensor-type ffn_down=q5_k --prune-layers 20,21,22 input-model-f32.gguf q4_k_m 8

# 覆盖 expert_used_count 元数据为 16，裁剪 20,21,22 层但不量化（copy 张量），指定输出文件名
./llama-quantize --imatrix imatrix.gguf --override-kv qwen3moe.expert_used_count=int:16 --prune-layers 20,21,22 input-model-f32.gguf pruned-model-f32.gguf copy 8

内存 / 磁盘需求

跑更大的模型要留足磁盘存放中间文件。模型当前会完整加载进内存，所以需要足够的磁盘保存、足够的 RAM 加载，两者需求相同。以 Llama 3.1 为例：

量化方法：体积与推理速度

支持多种量化方法，磁盘体积和推理速度各不相同。以 meta-llama/Llama-3.1-8B 为例：

Q8_0 是每权重 8 bit 的 INT8 量化，bit 数和体积都高于 K-quant 系列，但生成速度不是同向变化：Q8_0 的 prompt processing 865.09 t/s 高于 Q4_K_M 的 821.81 t/s，text generation 却只有 50.93 t/s，低于 Q4_K_M 的 71.93 t/s。同样是 8 bit 级别的 Q6_K，生成速度 58.67 t/s 也低于 Q4_K_M；2-bit 的 IQ2_XXS 体积仅 2.23 GiB，生成 79.86 t/s。

背景信息

k-quants、k-quants improvements and i-quants、2-bit i-quants (inference)、importance matrix、MoE models、imatrix for all k-quants、imatrix on the GPU、legacy quants 等内容，见 llama.cpp 相关 PR。

GGUF-my-repo space 位于 Hugging Face，无需本地环境即可构建量化。

标签：int8量化、GGUF、llama.cpp、量化