llama-quantize 接收 GGUF 模型文件，通常从 F32 或 BF16 等高精度格式转换为量化格式。量化会降低模型权重的表示精度，例如从 32 位浮点数改为 4 位整数，从而缩小模型文件，并可能加快推理。
这一过程也可能造成精度损失，通常用困惑度（Perplexity，ppl）或 Kullback–Leibler 散度（kld）衡量。使用合适的重要性矩阵文件，也就是 imatrix，可以帮助减小损失。
还可以使用 Hugging Face 上的 GGUF-my-repo 空间，在无需自行搭建环境的情况下生成量化模型。v0.5.0 的文档描述，该空间每 6 小时从 llama.cpp 的 main 分支同步一次；在线空间与固定版本的功能可能不同，应以实际服务为准。
整体流程
量化分为两个阶段：
- 将原始模型转换为 GGUF 格式。
- 对转换后的 GGUF 文件进行量化。
如果模型支持图像或音频等多模态输入，还需要转换多模态编码器和投影器，并选择合适的精度或量化格式。
执行这些步骤前，要安装项目的 Python 依赖：
python3 -m pip install -r requirements.txt
使用 uv 时，原文给出的对应命令是：
uv pip install -r requirements.txt --index-strategy unsafe-best-match
这些命令以已取得的 llama.cpp v0.5.0 项目目录为工作目录；此处保留原参数。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 依赖为兼容性安装 Transformers 4，但包括 Gemma 4 在内的更多模型需要 Transformers 5；原文建议用
pip install -U transformers更新。实际环境应记录兼容版本，不能把一次升级视为所有模型都可用的保证。
模型的获取与使用还受模型自身的许可、访问条件和资源需求约束。llama.cpp 的 MIT 许可不代替模型许可；上面的官方仓库标识保留原样，不代表本文已取得模型或执行下载。
量化 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：允许对已经量化过的张量再次量化。与从 16 位或 32 位权重开始量化相比，重复量化可能严重损害质量。--leave-output-tensor：保持output.weight不量化或不重复量化。文件会变大，但质量可能提高，尤其是在重复量化时。--pure：禁用 k-quant 的混合格式，让所有张量使用同一种量化类型。--imatrix file_name：使用指定文件中的重要性矩阵，优化量化。--include-weights tensor_name：为指定张量使用重要性矩阵，可以多次指定。--exclude-weights tensor_name：对没有列出的张量使用重要性矩阵。include与exclude不能混用。--output-tensor-type：指定output.weight张量的量化类型。--token-embedding-type：指定词元嵌入张量的量化类型。--keep-split：沿用输入模型的分片方式生成量化模型，而不是合并为单个文件。
高级选项：
--tensor-type：把指定张量量化为指定类型，支持正则表达式，可以多次指定。--prune-layers：剪除列表中指定的层。--override-kv：在量化后的模型中按键覆盖模型元数据，可以多次指定。
可选：转换多模态组件
llama.cpp 会转换源模型的大语言模型部分，这已经足以支持纯文本对话。如果模型支持多模态输入，而且需要使用这些能力，还要创建一个独立的 GGUF 文件。这个文件通常称为 mmproj，即 multimedia projector；除了投影层，也可能包含视觉或音频编码器等组件。
多模态组件通常比与之配套的大语言模型小得多，但其质量会直接影响生成质量。这些组件负责准备大语言模型的输入；输入越接近训练期间见到的数据，模型表现通常越好。
因此，多模态组件通常保留在 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 <input_image> --prompt "Describe this image"
<input_image> 要替换为自己的输入图片路径，不能把尖括号占位符直接当作 Shell 参数。模型文件、mmproj 与运行程序也要实际存在，并相互兼容。此命令保留 v0.5.0 文档的统一 llama cli 入口，未宣称在本文环境中运行成功。
量化命令示例
下面的七段代码均保留官方命令与注释。这里的 ./llama-quantize 假设可执行文件在当前目录；若自己的构建产物位于 build/bin，应使用对应路径。该版本的用法允许省略输出文件名；省略时由工具生成默认输出文件名。
使用默认设置、8 个 CPU 线程进行 Q4_K_M 量化。原注释中的默认输出名为 ggml-model-Q4_K_M.gguf：
# naive Q4_K_M quantization using default settings and 8 CPU threads. Output will be "ggml-model-Q4_K_M.gguf"
./llama-quantize input-model-f32.gguf q4_k_m 8
允许重复量化，让输出张量保留原精度，其余张量统一量化为 Q4_K：
# quantize model enabling re-quantization, leaving the output tensor unquantized and all others quantized at the same level (Q4_K)
./llama-quantize --allow-requantize --leave-output-tensor --pure input-model-f32.gguf q4_k_m 8
只为 attn_v 和 ffn_down 使用重要性矩阵：
# quantize model using an importance matrix for specified tensors only (attn_v and ffn_down)
./llama-quantize --imatrix imatrix.gguf --include-weights attn_v --include-weights ffn_down input-model-f32.gguf q4_k_m 8
把输出张量设置为 Q5_K，词元嵌入设置为 Q3_K，并保留输入文件的分片：
# quantize model setting output tensor to Q5_K_M, token embeddings to Q3_K_M, and keeping the input file's shards
./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
这里的 --output-tensor-type、--token-embedding-type 和后面的 --tensor-type 都指定单个张量的 GGML 类型。固定版本的 undefined通过 parse_ggml_type 解析它们，因此 q5_k、q3_k 分别是 Q5_K、Q3_K，不同于整个模型的混合量化方案 Q5_K_M、Q3_K_M。官方示例注释使用了后者的名称，措辞不精确；上面的注释及下面同类注释保留原样，正文按实际参数类型解释。
用正则表达式，将奇数层的 attn_k 量化为 Q5_K，偶数层的 attn_q 量化为 Q3_K：
# quantize model using a regex to quantize attn_k tensors in odd layers to Q5_K_M and attn_q tensors in even layers to 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，同时剪除第 20、21、22 层：
# quantize model setting tensors attn_v and ffn_down to Q5_K_M and pruning layers 20, 21, and 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 层，不进行量化而只复制张量，并明确指定输出文件名：
# override expert used count metadata to 16, prune layers 20, 21, and 22 without quantizing the model (copy tensors) and use specified name for the output file
./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 的原文示例：
| 模型 | 原始体积 | 量化后体积 (Q4_K_M) |
|---|---|---|
| 8B | 32.1 GB | 4.9 GB |
| 70B | 280.9 GB | 43.1 GB |
| 405B | 1,625.1 GB | 249.1 GB |
量化方法与示例数据
llama.cpp 支持多种量化方法，它们在模型磁盘体积与推理速度方面有所不同。下表全部来自 v0.5.0 文档中 meta-llama/Llama-3.1-8B 的示例，数值及误差原样保留。
表中 bits/weight 是平均每个权重的位数，GiB 为文件体积单位，t/s 为每秒处理或生成的词元数。@ 512、@ 128 保留原文的基准标签；原表未在此处完整列出测试硬件、后端与所有运行条件。它们用于理解不同格式的权衡，不应推断为本文实测或所有设备上的速度排序。
| 指标 | IQ1_S | IQ1_M | IQ2_XXS | IQ2_XS | IQ2_S | IQ2_M |
|---|---|---|---|---|---|---|
| 位数/权重 | 2.0042 | 2.1460 | 2.3824 | 2.5882 | 2.7403 | 2.9294 |
| 体积 (GiB) | 1.87 | 2.01 | 2.23 | 2.42 | 2.56 | 2.74 |
| 提示处理 t/s @ 512 | 858.88 ±1.22 | 847.99 ±0.47 | 852.39 ±0.85 | 826.99 ±12.51 | 783.55 ±13.73 | 787.68 ±7.00 |
| 文本生成 t/s @ 128 | 79.73 ±0.79 | 72.92 ±0.14 | 79.86 ±0.22 | 78.04 ±0.46 | 77.30 ±2.47 | 74.44 ±0.15 |
| 指标 | IQ3_XXS | IQ3_XS | IQ3_S | IQ3_M | IQ4_XS | IQ4_NL |
|---|---|---|---|---|---|---|
| 位数/权重 | 3.2548 | 3.4977 | 3.6606 | 3.7628 | 4.4597 | 4.6818 |
| 体积 (GiB) | 3.04 | 3.27 | 3.42 | 3.52 | 4.17 | 4.38 |
| 提示处理 t/s @ 512 | 813.88 ±6.53 | 708.71 ±1.26 | 798.78 ±8.81 | 768.70 ±13.73 | 771.80 ±11.38 | 806.03 ±7.07 |
| 文本生成 t/s @ 128 | 73.95 ±0.20 | 71.67 ±0.54 | 69.31 ±0.63 | 70.15 ±0.33 | 77.51 ±0.20 | 76.63 ±0.28 |
| 指标 | Q2_K_S | Q2_K | Q3_K_S | Q3_K_M | Q3_K_L | Q4_K_S |
|---|---|---|---|---|---|---|
| 位数/权重 | 2.9697 | 3.1593 | 3.6429 | 3.9960 | 4.2979 | 4.6672 |
| 体积 (GiB) | 2.78 | 2.95 | 3.41 | 3.74 | 4.02 | 4.36 |
| 提示处理 t/s @ 512 | 798.91 ±6.40 | 784.45 ±7.85 | 752.17 ±7.94 | 783.44 ±9.92 | 761.17 ±7.55 | 818.55 ±9.58 |
| 文本生成 t/s @ 128 | 90.01 ±0.12 | 79.85 ±0.20 | 69.84 ±0.18 | 71.68 ±0.22 | 69.38 ±0.49 | 76.71 ±0.20 |
| 指标 | Q4_K_S | Q4_K_M | Q5_K_S | Q5_K_M | Q6_K | Q8_0 |
|---|---|---|---|---|---|---|
| 位数/权重 | 4.6672 | 4.8944 | 5.5704 | 5.7036 | 6.5633 | 8.5008 |
| 体积 (GiB) | 4.36 | 4.58 | 5.21 | 5.33 | 6.14 | 7.95 |
| 提示处理 t/s @ 512 | 818.55 ±9.58 | 821.81 ±21.44 | 752.52 ±0.99 | 758.69 ±7.43 | 812.01 ±10.82 | 865.09 ±8.30 |
| 文本生成 t/s @ 128 | 76.71 ±0.20 | 71.93 ±1.52 | 69.53 ±0.18 | 67.23 ±1.08 | 58.67 ±3.13 | 50.93 ±0.08 |
| 指标 | F16 |
|---|---|
| 位数/权重 | 16.0005 |
| 体积 (GiB) | 14.96 |
| 提示处理 t/s @ 512 | 923.49 ±0.53 |
| 文本生成 t/s @ 128 | 29.17 ±0.04 |
原文两组表都出现 Q4_K_S，其数据相同；为保持完整，仍按原表分别保留。
llama-quantize 的背景资料
- k-quants
- k-quants 的改进与 i-quants：PR #2707、PR #2807
- #4773：2 位 i-quants（推理）
- #4856：2 位 i-quants（推理）
- #4861：重要性矩阵
- #4872：MoE 模型
- #4897：2 位量化
- #4930：为所有 k-quants 使用 imatrix
- #4951：在 GPU 上运行 imatrix
- #4969：为旧式量化格式使用 imatrix
- #4996：k-quants 调优
- #5060：Q3_K_XS
- #5196：3 位 i-quants
- 量化调优：PR #5320、PR #5334、PR #5361
其中 #4951 的文字与链接目标 4957 不一致，源文如此，本文保留该引用并明确指出差异。
来源与许可
原文：quantize，llama.cpp v0.5.0，llama.cpp 文档贡献者。官方仓库对应页面。本文依据该固定标签的文档完整整理为中文，保留命令、数字表格及官方链接，并补充路径、版本与实测边界。
MIT License
Copyright (c) 2023-2026 The ggml authors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
暂无评论内容